mirror of
https://sourceware.org/git/binutils-gdb.git
synced 2024-12-09 04:21:49 +08:00
de220cbdb9
fields.
* lexsup.c (parse_args): Recognize --auxiliary/-f and
--filter/-F.
* emultempl/elf32.em (gld${EMULATION_NAME}_before_allocation):
Pass filter_shlib and auxiliary_filter_shlib to
size_dynamic_sections.
* ld.texinfo, ld.1: Document --filter/-F and --auxiliary/-f.
3426 lines
121 KiB
Plaintext
3426 lines
121 KiB
Plaintext
\input texinfo
|
|
@setfilename ld.info
|
|
@syncodeindex ky cp
|
|
@include configdoc.texi
|
|
@c (configdoc.texi is generated by the Makefile)
|
|
|
|
@c @smallbook
|
|
|
|
@ifinfo
|
|
@format
|
|
START-INFO-DIR-ENTRY
|
|
* Ld: (ld). The GNU linker.
|
|
END-INFO-DIR-ENTRY
|
|
@end format
|
|
@end ifinfo
|
|
|
|
@ifinfo
|
|
This file documents the @sc{gnu} linker LD.
|
|
|
|
Copyright (C) 1991, 92, 93, 94, 95, 1996 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to make and distribute verbatim copies of
|
|
this manual provided the copyright notice and this permission notice
|
|
are preserved on all copies.
|
|
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided also that
|
|
the entire resulting derived work is distributed under the terms of a
|
|
permission notice identical to this one.
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
into another language, under the above conditions for modified versions.
|
|
|
|
@ignore
|
|
Permission is granted to process this file through Tex and print the
|
|
results, provided the printed document carries copying permission
|
|
notice identical to this one except for the removal of this paragraph
|
|
(this paragraph not being relevant to the printed manual).
|
|
|
|
@end ignore
|
|
@end ifinfo
|
|
@iftex
|
|
@finalout
|
|
@setchapternewpage odd
|
|
@settitle Using LD, the GNU linker
|
|
@titlepage
|
|
@title Using ld
|
|
@subtitle The GNU linker
|
|
@sp 1
|
|
@subtitle @code{ld} version 2
|
|
@subtitle January 1994
|
|
@author Steve Chamberlain
|
|
@author Cygnus Support
|
|
@page
|
|
|
|
@tex
|
|
{\parskip=0pt
|
|
\hfill Cygnus Support\par
|
|
\hfill steve\@cygnus.com, doc\@cygnus.com\par
|
|
\hfill {\it Using LD, the GNU linker}\par
|
|
\hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par
|
|
}
|
|
\global\parindent=0pt % Steve likes it this way.
|
|
@end tex
|
|
|
|
@vskip 0pt plus 1filll
|
|
Copyright @copyright{} 1991, 92, 93, 94, 95, 1996 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to make and distribute verbatim copies of
|
|
this manual provided the copyright notice and this permission notice
|
|
are preserved on all copies.
|
|
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided also that
|
|
the entire resulting derived work is distributed under the terms of a
|
|
permission notice identical to this one.
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
into another language, under the above conditions for modified versions.
|
|
@end titlepage
|
|
@end iftex
|
|
@c FIXME: Talk about importance of *order* of args, cmds to linker!
|
|
|
|
@ifinfo
|
|
@node Top
|
|
@top Using ld
|
|
This file documents the @sc{gnu} linker ld.
|
|
|
|
@menu
|
|
* Overview:: Overview
|
|
* Invocation:: Invocation
|
|
* Commands:: Command Language
|
|
@ifset GENERIC
|
|
* Machine Dependent:: Machine Dependent Features
|
|
@end ifset
|
|
@ifclear GENERIC
|
|
@ifset H8300
|
|
* H8/300:: ld and the H8/300
|
|
@end ifset
|
|
@ifset Hitachi
|
|
* Hitachi:: ld and other Hitachi micros
|
|
@end ifset
|
|
@ifset I960
|
|
* i960:: ld and the Intel 960 family
|
|
@end ifset
|
|
@end ifclear
|
|
@ifclear SingleFormat
|
|
* BFD:: BFD
|
|
@end ifclear
|
|
@c Following blank line required for remaining bug in makeinfo conds/menus
|
|
|
|
* Reporting Bugs:: Reporting Bugs
|
|
* MRI:: MRI Compatible Script Files
|
|
* Index:: Index
|
|
@end menu
|
|
@end ifinfo
|
|
|
|
@node Overview
|
|
@chapter Overview
|
|
|
|
@cindex @sc{gnu} linker
|
|
@cindex what is this?
|
|
@code{ld} combines a number of object and archive files, relocates
|
|
their data and ties up symbol references. Usually the last step in
|
|
compiling a program is to run @code{ld}.
|
|
|
|
@code{ld} accepts Linker Command Language files written in
|
|
a superset of AT&T's Link Editor Command Language syntax,
|
|
to provide explicit and total control over the linking process.
|
|
|
|
@ifclear SingleFormat
|
|
This version of @code{ld} uses the general purpose BFD libraries
|
|
to operate on object files. This allows @code{ld} to read, combine, and
|
|
write object files in many different formats---for example, COFF or
|
|
@code{a.out}. Different formats may be linked together to produce any
|
|
available kind of object file. @xref{BFD}, for more information.
|
|
@end ifclear
|
|
|
|
Aside from its flexibility, the @sc{gnu} linker is more helpful than other
|
|
linkers in providing diagnostic information. Many linkers abandon
|
|
execution immediately upon encountering an error; whenever possible,
|
|
@code{ld} continues executing, allowing you to identify other errors
|
|
(or, in some cases, to get an output file in spite of the error).
|
|
|
|
@node Invocation
|
|
@chapter Invocation
|
|
|
|
The @sc{gnu} linker @code{ld} is meant to cover a broad range of situations,
|
|
and to be as compatible as possible with other linkers. As a result,
|
|
you have many choices to control its behavior.
|
|
|
|
@ifset UsesEnvVars
|
|
@menu
|
|
* Options:: Command Line Options
|
|
* Environment:: Environment Variables
|
|
@end menu
|
|
|
|
@node Options
|
|
@section Command Line Options
|
|
@end ifset
|
|
|
|
@cindex command line
|
|
@cindex options
|
|
The linker supports a plethora of command-line options, but in actual
|
|
practice few of them are used in any particular context.
|
|
@cindex standard Unix system
|
|
For instance, a frequent use of @code{ld} is to link standard Unix
|
|
object files on a standard, supported Unix system. On such a system, to
|
|
link a file @code{hello.o}:
|
|
|
|
@smallexample
|
|
ld -o @var{output} /lib/crt0.o hello.o -lc
|
|
@end smallexample
|
|
|
|
This tells @code{ld} to produce a file called @var{output} as the
|
|
result of linking the file @code{/lib/crt0.o} with @code{hello.o} and
|
|
the library @code{libc.a}, which will come from the standard search
|
|
directories. (See the discussion of the @samp{-l} option below.)
|
|
|
|
The command-line options to @code{ld} may be specified in any order, and
|
|
may be repeated at will. Repeating most options with a different
|
|
argument will either have no further effect, or override prior
|
|
occurrences (those further to the left on the command line) of that
|
|
option. Options which may be meaningfully specified more than once are
|
|
noted in the descriptions below.
|
|
|
|
@cindex object files
|
|
Non-option arguments are objects files which are to be linked together.
|
|
They may follow, precede, or be mixed in with command-line options,
|
|
except that an object file argument may not be placed between an option
|
|
and its argument.
|
|
|
|
Usually the linker is invoked with at least one object file, but you can
|
|
specify other forms of binary input files using @samp{-l}, @samp{-R},
|
|
and the script command language. If @emph{no} binary input files at all
|
|
are specified, the linker does not produce any output, and issues the
|
|
message @samp{No input files}.
|
|
|
|
If the linker can not recognize the format of an object file, it will
|
|
assume that it is a linker script. A script specified in this way
|
|
augments the main linker script used for the link (either the default
|
|
linker script or the one specified by using @samp{-T}). This feature
|
|
permits the linker to link against a file which appears to be an object
|
|
or an archive, but actually merely defines some symbol values, or uses
|
|
@code{INPUT} or @code{GROUP} to load other objects. @xref{Commands}.
|
|
|
|
For options whose names are a single letter,
|
|
option arguments must either follow the option letter without intervening
|
|
whitespace, or be given as separate arguments immediately following the
|
|
option that requires them.
|
|
|
|
For options whose names are multiple letters, either one dash or two can
|
|
precede the option name; for example, @samp{--oformat} and
|
|
@samp{--oformat} are equivalent. Arguments to multiple-letter options
|
|
must either be separated from the option name by an equals sign, or be
|
|
given as separate arguments immediately following the option that
|
|
requires them. For example, @samp{--oformat srec} and
|
|
@samp{--oformat=srec} are equivalent. Unique abbreviations of the names
|
|
of multiple-letter options are accepted.
|
|
|
|
@table @code
|
|
@kindex -a@var{keyword}
|
|
@item -a@var{keyword}
|
|
This option is supported for HP/UX compatibility. The @var{keyword}
|
|
argument must be one of the strings @samp{archive}, @samp{shared}, or
|
|
@samp{default}. @samp{-aarchive} is functionally equivalent to
|
|
@samp{-Bstatic}, and the other two keywords are functionally equivalent
|
|
to @samp{-Bdynamic}. This option may be used any number of times.
|
|
|
|
@ifset I960
|
|
@cindex architectures
|
|
@kindex -A@var{arch}
|
|
@item -A@var{architecture}
|
|
@kindex --architecture=@var{arch}
|
|
@itemx --architecture=@var{architecture}
|
|
In the current release of @code{ld}, this option is useful only for the
|
|
Intel 960 family of architectures. In that @code{ld} configuration, the
|
|
@var{architecture} argument identifies the particular architecture in
|
|
the 960 family, enabling some safeguards and modifying the
|
|
archive-library search path. @xref{i960,,@code{ld} and the Intel 960
|
|
family}, for details.
|
|
|
|
Future releases of @code{ld} may support similar functionality for
|
|
other architecture families.
|
|
@end ifset
|
|
|
|
@ifclear SingleFormat
|
|
@cindex binary input format
|
|
@kindex -b @var{format}
|
|
@kindex --format=@var{format}
|
|
@cindex input format
|
|
@cindex input format
|
|
@item -b @var{input-format}
|
|
@itemx --format=@var{input-format}
|
|
@code{ld} may be configured to support more than one kind of object
|
|
file. If your @code{ld} is configured this way, you can use the
|
|
@samp{-b} option to specify the binary format for input object files
|
|
that follow this option on the command line. Even when @code{ld} is
|
|
configured to support alternative object formats, you don't usually need
|
|
to specify this, as @code{ld} should be configured to expect as a
|
|
default input format the most usual format on each machine.
|
|
@var{input-format} is a text string, the name of a particular format
|
|
supported by the BFD libraries. (You can list the available binary
|
|
formats with @samp{objdump -i}.)
|
|
@xref{BFD}.
|
|
|
|
You may want to use this option if you are linking files with an unusual
|
|
binary format. You can also use @samp{-b} to switch formats explicitly (when
|
|
linking object files of different formats), by including
|
|
@samp{-b @var{input-format}} before each group of object files in a
|
|
particular format.
|
|
|
|
The default format is taken from the environment variable
|
|
@code{GNUTARGET}.
|
|
@ifset UsesEnvVars
|
|
@xref{Environment}.
|
|
@end ifset
|
|
You can also define the input
|
|
format from a script, using the command @code{TARGET}; see @ref{Option
|
|
Commands}.
|
|
@end ifclear
|
|
|
|
@kindex -c @var{MRI-cmdfile}
|
|
@kindex --mri-script=@var{MRI-cmdfile}
|
|
@cindex compatibility, MRI
|
|
@item -c @var{MRI-commandfile}
|
|
@itemx --mri-script=@var{MRI-commandfile}
|
|
For compatibility with linkers produced by MRI, @code{ld} accepts script
|
|
files written in an alternate, restricted command language, described in
|
|
@ref{MRI,,MRI Compatible Script Files}. Introduce MRI script files with
|
|
the option @samp{-c}; use the @samp{-T} option to run linker
|
|
scripts written in the general-purpose @code{ld} scripting language.
|
|
If @var{MRI-cmdfile} does not exist, @code{ld} looks for it in the directories
|
|
specified by any @samp{-L} options.
|
|
|
|
@cindex common allocation
|
|
@kindex -d
|
|
@kindex -dc
|
|
@kindex -dp
|
|
@item -d
|
|
@itemx -dc
|
|
@itemx -dp
|
|
These three options are equivalent; multiple forms are supported for
|
|
compatibility with other linkers. They
|
|
assign space to common symbols even if a relocatable output file is
|
|
specified (with @samp{-r}). The script command
|
|
@code{FORCE_COMMON_ALLOCATION} has the same effect. @xref{Option
|
|
Commands}.
|
|
|
|
@cindex entry point, from command line
|
|
@kindex -e @var{entry}
|
|
@kindex --entry=@var{entry}
|
|
@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.
|
|
|
|
@cindex dynamic symbol table
|
|
@kindex -E
|
|
@kindex --export-dynamic
|
|
@item -E
|
|
@itemx --export-dynamic
|
|
When creating a dynamically linked executable, add all symbols to the
|
|
dynamic symbol table. Normally, the dynamic symbol table contains only
|
|
symbols which are used by a dynamic object. This option is needed for
|
|
some uses of @code{dlopen}.
|
|
|
|
@kindex -f
|
|
@kindex --auxiliary
|
|
@item -f
|
|
@itemx --auxiliary @var{name}
|
|
When creating an ELF shared object, set the internal DT_AUXILIARY field
|
|
to the specified name. This tells the dynamic linker that the symbol
|
|
table of the shared object should be used as an auxiliary filter on the
|
|
symbol table of the shared object @var{name}.
|
|
|
|
@kindex -F
|
|
@kindex --filter
|
|
@item -F @var{name}
|
|
@itemx --filter @var{name}
|
|
When creating an ELF shared object, set the internal DT_FILTER field to
|
|
the specified name. This tells the dynamic linker that the symbol table
|
|
of the shared object should be used as a filter on the symbol table of
|
|
the shared object @var{name}.
|
|
|
|
Some older linkers used the @code{-F} option throughout a compilation
|
|
toolchain for specifying object-file format for both input and output
|
|
object files. The @sc{gnu} linker uses other mechanisms for this
|
|
purpose: the @code{-b}, @code{--format}, @code{--oformat} options, the
|
|
@code{TARGET} command in linker scripts, and the @code{GNUTARGET}
|
|
environment variable. The @sc{gnu} linker will ignore the @code{-F}
|
|
option when not creating an ELF shared object.
|
|
|
|
@kindex --force-exe-suffix
|
|
@item --force-exe-suffix
|
|
Make sure that an output file has a .exe suffix.
|
|
|
|
If a successfully built fully linked output file does not have a
|
|
@code{.exe} or @code{.dll} suffix, this option forces the linker to copy
|
|
the output file to one of the same name with a @code{.exe} suffix. This
|
|
option is useful when using unmodified Unix makefiles on a Microsoft
|
|
Windows host, since some versions of Windows won't run an image unless
|
|
it ends in a @code{.exe} suffix.
|
|
|
|
@kindex -g
|
|
@item -g
|
|
Ignored. Provided for compatibility with other tools.
|
|
|
|
@kindex -G
|
|
@kindex --gpsize
|
|
@cindex object size
|
|
@item -G@var{value}
|
|
@itemx --gpsize=@var{value}
|
|
Set the maximum size of objects to be optimized using the GP register to
|
|
@var{size}. This is only meaningful for object file formats such as
|
|
MIPS ECOFF which supports putting large and small objects into different
|
|
sections. This is ignored for other object file formats.
|
|
|
|
@cindex runtime library name
|
|
@kindex -h@var{name}
|
|
@kindex -soname=@var{name}
|
|
@item -h@var{name}
|
|
@itemx -soname=@var{name}
|
|
When creating an ELF shared object, set the internal DT_SONAME field to
|
|
the specified name. When an executable is linked with a shared object
|
|
which has a DT_SONAME field, then when the executable is run the dynamic
|
|
linker will attempt to load the shared object specified by the DT_SONAME
|
|
field rather than the using the file name given to the linker.
|
|
|
|
@kindex -i
|
|
@cindex incremental link
|
|
@item -i
|
|
Perform an incremental link (same as option @samp{-r}).
|
|
|
|
@cindex archive files, from cmd line
|
|
@kindex -l@var{archive}
|
|
@kindex --library=@var{archive}
|
|
@item -l@var{archive}
|
|
@itemx --library=@var{archive}
|
|
Add archive file @var{archive} to the list of files to link. This
|
|
option may be used any number of times. @code{ld} will search its
|
|
path-list for occurrences of @code{lib@var{archive}.a} for every
|
|
@var{archive} specified.
|
|
|
|
On systems which support shared libraries, @code{ld} may also search for
|
|
libraries with extensions other than @code{.a}. Specifically, on ELF
|
|
and SunOS systems, @code{ld} will search a directory for a library with
|
|
an extension of @code{.so} before searching for one with an extension of
|
|
@code{.a}. By convention, a @code{.so} extension indicates a shared
|
|
library.
|
|
|
|
The linker will search an archive only once, at the location where it is
|
|
specified on the command line. If the archive defines a symbol which
|
|
was undefined in some object which appeared before the archive on the
|
|
command line, the linker will include the appropriate file(s) from the
|
|
archive. However, an undefined symbol in an object appearing later on
|
|
the command line will not cause the linker to search the archive again.
|
|
|
|
See the @code{-(} option for a way to force the linker to search
|
|
archives multiple times.
|
|
|
|
You may list the same archive multiple times on the command line.
|
|
|
|
@ifset GENERIC
|
|
This type of archive searching is standard for Unix linkers. However,
|
|
if you are using @code{ld} on AIX, note that it is different from the
|
|
behaviour of the AIX linker.
|
|
@end ifset
|
|
|
|
@cindex search directory, from cmd line
|
|
@kindex -L@var{dir}
|
|
@kindex --library-path=@var{dir}
|
|
@item -L@var{searchdir}
|
|
@itemx --library-path=@var{searchdir}
|
|
Add path @var{searchdir} to the list of paths that @code{ld} will search
|
|
for archive libraries and @code{ld} control scripts. You may use this
|
|
option any number of times. The directories are searched in the order
|
|
in which they are specified on the command line. Directories specified
|
|
on the command line are searched before the default directories. All
|
|
@code{-L} options apply to all @code{-l} options, regardless of the
|
|
order in which the options appear.
|
|
|
|
@ifset UsesEnvVars
|
|
The default set of paths searched (without being specified with
|
|
@samp{-L}) depends on which emulation mode @code{ld} is using, and in
|
|
some cases also on how it was configured. @xref{Environment}.
|
|
@end ifset
|
|
|
|
The paths can also be specified in a link script with the
|
|
@code{SEARCH_DIR} command. Directories specified this way are searched
|
|
at the point in which the linker script appears in the command line.
|
|
|
|
@cindex emulation
|
|
@kindex -m @var{emulation}
|
|
@item -m@var{emulation}
|
|
Emulate the @var{emulation} linker. You can list the available
|
|
emulations with the @samp{--verbose} or @samp{-V} options. The default
|
|
depends on how your @code{ld} was configured.
|
|
|
|
@cindex link map
|
|
@kindex -M
|
|
@kindex --print-map
|
|
@item -M
|
|
@itemx --print-map
|
|
Print (to the standard output) a link map---diagnostic information about
|
|
where symbols are mapped by @code{ld}, and information on global common
|
|
storage allocation.
|
|
|
|
@kindex -n
|
|
@cindex read-only text
|
|
@cindex NMAGIC
|
|
@kindex --nmagic
|
|
@item -n
|
|
@itemx --nmagic
|
|
Set the text segment to be read only, and mark the output as
|
|
@code{NMAGIC} if possible.
|
|
|
|
@kindex -N
|
|
@kindex --omagic
|
|
@cindex read/write from cmd line
|
|
@cindex OMAGIC
|
|
@item -N
|
|
@itemx --omagic
|
|
Set the text and data sections to be readable and writable. Also, do
|
|
not page-align the data segment. If the output format supports Unix
|
|
style magic numbers, mark the output as @code{OMAGIC}.
|
|
|
|
@kindex -o @var{output}
|
|
@kindex --output=@var{output}
|
|
@cindex naming the output file
|
|
@item -o @var{output}
|
|
@itemx --output=@var{output}
|
|
Use @var{output} as the name for the program produced by @code{ld}; if this
|
|
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.
|
|
|
|
@cindex partial link
|
|
@cindex relocatable output
|
|
@kindex -r
|
|
@kindex --relocateable
|
|
@item -r
|
|
@itemx --relocateable
|
|
Generate relocatable output---i.e., generate an output file that can in
|
|
turn serve as input to @code{ld}. This is often called @dfn{partial
|
|
linking}. As a side effect, in environments that support standard Unix
|
|
magic numbers, this option also sets the output file's magic number to
|
|
@code{OMAGIC}.
|
|
@c ; see @code{-N}.
|
|
If this option is not specified, an absolute file is produced. When
|
|
linking C++ programs, this option @emph{will not} resolve references to
|
|
constructors; to do that, use @samp{-Ur}.
|
|
|
|
This option does the same thing as @samp{-i}.
|
|
|
|
@kindex -R @var{file}
|
|
@kindex --just-symbols=@var{file}
|
|
@cindex symbol-only input
|
|
@item -R @var{filename}
|
|
@itemx --just-symbols=@var{filename}
|
|
Read symbol names and their addresses from @var{filename}, but do not
|
|
relocate it or include it in the output. This allows your output file
|
|
to refer symbolically to absolute locations of memory defined in other
|
|
programs. You may use this option more than once.
|
|
|
|
For compatibility with other ELF linkers, if the @code{-R} option is
|
|
followed by a directory name, rather than a file name, it is treated as
|
|
the @code{-rpath} option.
|
|
|
|
@kindex -s
|
|
@kindex --strip-all
|
|
@cindex strip all symbols
|
|
@item -s
|
|
@itemx --strip-all
|
|
Omit all symbol information from the output file.
|
|
|
|
@kindex -S
|
|
@kindex --strip-debug
|
|
@cindex strip debugger symbols
|
|
@item -S
|
|
@itemx --strip-debug
|
|
Omit debugger symbol information (but not all symbols) from the output file.
|
|
|
|
@kindex -t
|
|
@kindex --trace
|
|
@cindex input files, displaying
|
|
@item -t
|
|
@itemx --trace
|
|
Print the names of the input files as @code{ld} processes them.
|
|
|
|
@kindex -T @var{script}
|
|
@kindex --script=@var{script}
|
|
@cindex script files
|
|
@item -T @var{commandfile}
|
|
@itemx --script=@var{commandfile}
|
|
Read link commands from the file @var{commandfile}. These commands
|
|
replace @code{ld}'s default link script (rather than adding
|
|
to it), so @var{commandfile} must specify everything necessary to describe
|
|
the target format. @xref{Commands}. If @var{commandfile} does not
|
|
exist, @code{ld} looks for it in the directories specified by any
|
|
preceding @samp{-L} options. Multiple @samp{-T} options accumulate.
|
|
|
|
@kindex -u @var{symbol}
|
|
@kindex --undefined=@var{symbol}
|
|
@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.
|
|
|
|
@kindex -v
|
|
@kindex -V
|
|
@kindex --version
|
|
@cindex version
|
|
@item -v
|
|
@itemx --version
|
|
@itemx -V
|
|
Display the version number for @code{ld}. The @code{-V} option also
|
|
lists the supported emulations.
|
|
|
|
@kindex -x
|
|
@kindex --discard-all
|
|
@cindex deleting local symbols
|
|
@item -x
|
|
@itemx --discard-all
|
|
Delete all local symbols.
|
|
|
|
@kindex -X
|
|
@kindex --discard-locals
|
|
@cindex local symbols, deleting
|
|
@cindex L, deleting symbols beginning
|
|
@item -X
|
|
@itemx --discard-locals
|
|
Delete all temporary local symbols. For most targets, this is all local
|
|
symbols whose names begin with @samp{L}.
|
|
|
|
@kindex -y @var{symbol}
|
|
@kindex --trace-symbol=@var{symbol}
|
|
@cindex symbol tracing
|
|
@item -y @var{symbol}
|
|
@itemx --trace-symbol=@var{symbol}
|
|
Print the name of each linked file in which @var{symbol} appears. This
|
|
option may be given any number of times. On many systems it is necessary
|
|
to prepend an underscore.
|
|
|
|
This option is useful when you have an undefined symbol in your link but
|
|
don't know where the reference is coming from.
|
|
|
|
@kindex -Y @var{path}
|
|
@item -Y @var{path}
|
|
Add @var{path} to the default library search path. This option exists
|
|
for Solaris compatibility.
|
|
|
|
@kindex -z @var{keyword}
|
|
@item -z @var{keyword}
|
|
This option is ignored for Solaris compatibility.
|
|
|
|
@kindex -(
|
|
@cindex groups of archives
|
|
@item -( @var{archives} -)
|
|
@itemx --start-group @var{archives} --end-group
|
|
The @var{archives} should be a list of archive files. They may be
|
|
either explicit file names, or @samp{-l} options.
|
|
|
|
The specified archives are searched repeatedly until no new undefined
|
|
references are created. Normally, an archive is searched only once in
|
|
the order that it is specified on the command line. If a symbol in that
|
|
archive is needed to resolve an undefined symbol referred to by an
|
|
object in an archive that appears later on the command line, the linker
|
|
would not be able to resolve that reference. By grouping the archives,
|
|
they all be searched repeatedly until all possible references are
|
|
resolved.
|
|
|
|
Using this option has a significant performance cost. It is best to use
|
|
it only when there are unavoidable circular references between two or
|
|
more archives.
|
|
|
|
@kindex -assert @var{keyword}
|
|
@item -assert @var{keyword}
|
|
This option is ignored for SunOS compatibility.
|
|
|
|
@kindex -Bdynamic
|
|
@kindex -dy
|
|
@kindex -call_shared
|
|
@item -Bdynamic
|
|
@itemx -dy
|
|
@itemx -call_shared
|
|
Link against dynamic libraries. This is only meaningful on platforms
|
|
for which shared libraries are supported. This option is normally the
|
|
default on such platforms. The different variants of this option are
|
|
for compatibility with various systems. You may use this option
|
|
multiple times on the command line: it affects library searching for
|
|
@code{-l} options which follow it.
|
|
|
|
@kindex -Bstatic
|
|
@kindex -dn
|
|
@kindex -non_shared
|
|
@kindex -static
|
|
@item -Bstatic
|
|
@itemx -dn
|
|
@itemx -non_shared
|
|
@itemx -static
|
|
Do not link against shared libraries. This is only meaningful on
|
|
platforms for which shared libraries are supported. The different
|
|
variants of this option are for compatibility with various systems. You
|
|
may use this option multiple times on the command line: it affects
|
|
library searching for @code{-l} options which follow it.
|
|
|
|
@kindex -Bsymbolic
|
|
@item -Bsymbolic
|
|
When creating a shared library, bind references to global symbols to the
|
|
definition within the shared library, if any. Normally, it is possible
|
|
for a program linked against a shared library to override the definition
|
|
within the shared library. This option is only meaningful on ELF
|
|
platforms which support shared libraries.
|
|
|
|
@cindex cross reference table
|
|
@kindex --cref
|
|
@item --cref
|
|
Output a cross reference table. If a linker map file is being
|
|
generated, the cross reference table is printed to the map file.
|
|
Otherwise, it is printed on the standard output.
|
|
|
|
The format of the table is intentionally simple, so that it may be
|
|
easily processed by a script if necessary. The symbols are printed out,
|
|
sorted by name. For each symbol, a list of file names is given. If the
|
|
symbol is defined, the first file listed is the location of the
|
|
definition. The remaining files contain references to the symbol.
|
|
|
|
@cindex symbols, from command line
|
|
@kindex --defsym @var{symbol}=@var{exp}
|
|
@item --defsym @var{symbol}=@var{expression}
|
|
Create a global symbol in the output file, containing the absolute
|
|
address given by @var{expression}. You may use this option as many
|
|
times as necessary to define multiple symbols in the command line. A
|
|
limited form of arithmetic is supported for the @var{expression} in this
|
|
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{Assignment, ,
|
|
Assignment: Symbol Definitions}). @emph{Note:} there should be no
|
|
white space between @var{symbol}, the equals sign (``@key{=}''), and
|
|
@var{expression}.
|
|
|
|
@cindex dynamic linker, from command line
|
|
@kindex --dynamic-linker @var{file}
|
|
@item --dynamic-linker @var{file}
|
|
Set the name of the dynamic linker. This is only meaningful when
|
|
generating dynamically linked ELF executables. The default dynamic
|
|
linker is normally correct; don't use this unless you know what you are
|
|
doing.
|
|
|
|
@cindex big-endian objects
|
|
@cindex endianness
|
|
@kindex -EB
|
|
@item -EB
|
|
Link big-endian objects. This affects the default output format.
|
|
|
|
@cindex little-endian objects
|
|
@kindex -EL
|
|
@item -EL
|
|
Link little-endian objects. This affects the default output format.
|
|
|
|
@cindex MIPS embedded PIC code
|
|
@kindex --embedded-relocs
|
|
@item --embedded-relocs
|
|
This option is only meaningful when linking MIPS embedded PIC code,
|
|
generated by the -membedded-pic option to the @sc{gnu} compiler and
|
|
assembler. It causes the linker to create a table which may be used at
|
|
runtime to relocate any data which was statically initialized to pointer
|
|
values. See the code in testsuite/ld-empic for details.
|
|
|
|
@cindex help
|
|
@cindex usage
|
|
@kindex --help
|
|
@item --help
|
|
Print a summary of the command-line options on the standard output and exit.
|
|
|
|
@cindex link map
|
|
@kindex -Map
|
|
@item -Map @var{mapfile}
|
|
Print to the file @var{mapfile} a link map---diagnostic information
|
|
about where symbols are mapped by @code{ld}, and information on global
|
|
common storage allocation.
|
|
|
|
@cindex memory usage
|
|
@kindex --no-keep-memory
|
|
@item --no-keep-memory
|
|
@code{ld} normally optimizes for speed over memory usage by caching the
|
|
symbol tables of input files in memory. This option tells @code{ld} to
|
|
instead optimize for memory usage, by rereading the symbol tables as
|
|
necessary. This may be required if @code{ld} runs out of memory space
|
|
while linking a large executable.
|
|
|
|
@kindex --no-whole-archive
|
|
@item --no-whole-archive
|
|
Turn off the effect of the @code{--whole-archive} option for subsequent
|
|
archive files.
|
|
|
|
@cindex output file after errors
|
|
@kindex --noinhibit-exec
|
|
@item --noinhibit-exec
|
|
Retain the executable output file whenever it is still usable.
|
|
Normally, the linker will not produce an output file if it encounters
|
|
errors during the link process; it exits without writing an output file
|
|
when it issues any error whatsoever.
|
|
|
|
@ifclear SingleFormat
|
|
@kindex --oformat
|
|
@item --oformat @var{output-format}
|
|
@code{ld} may be configured to support more than one kind of object
|
|
file. If your @code{ld} is configured this way, you can use the
|
|
@samp{--oformat} option to specify the binary format for the output
|
|
object file. Even when @code{ld} is configured to support alternative
|
|
object formats, you don't usually need to specify this, as @code{ld}
|
|
should be configured to produce as a default output format the most
|
|
usual format on each machine. @var{output-format} is a text string, the
|
|
name of a particular format supported by the BFD libraries. (You can
|
|
list the available binary formats with @samp{objdump -i}.) The script
|
|
command @code{OUTPUT_FORMAT} can also specify the output format, but
|
|
this option overrides it. @xref{BFD}.
|
|
@end ifclear
|
|
|
|
@kindex -qmagic
|
|
@item -qmagic
|
|
This option is ignored for Linux compatibility.
|
|
|
|
@kindex -Qy
|
|
@item -Qy
|
|
This option is ignored for SVR4 compatibility.
|
|
|
|
@kindex --relax
|
|
@cindex synthesizing linker
|
|
@cindex relaxing addressing modes
|
|
@item --relax
|
|
An option with machine dependent effects.
|
|
@ifset GENERIC
|
|
This option is only supported on a few targets.
|
|
@end ifset
|
|
@ifset H8300
|
|
@xref{H8/300,,@code{ld} and the H8/300}.
|
|
@end ifset
|
|
@ifset I960
|
|
@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.
|
|
|
|
@ifset GENERIC
|
|
On platforms where this is not supported, @samp{--relax} is accepted,
|
|
but ignored.
|
|
@end ifset
|
|
|
|
@cindex retaining specified symbols
|
|
@cindex stripping all but some symbols
|
|
@cindex symbols, retaining selectively
|
|
@item --retain-symbols-file @var{filename}
|
|
Retain @emph{only} the symbols listed in the file @var{filename},
|
|
discarding all others. @var{filename} is simply a flat file, with one
|
|
symbol name per line. This option is especially useful in environments
|
|
@ifset GENERIC
|
|
(such as VxWorks)
|
|
@end ifset
|
|
where a large global symbol table is accumulated gradually, to conserve
|
|
run-time memory.
|
|
|
|
@samp{--retain-symbols-file} does @emph{not} discard undefined symbols,
|
|
or symbols needed for relocations.
|
|
|
|
You may only specify @samp{--retain-symbols-file} once in the command
|
|
line. It overrides @samp{-s} and @samp{-S}.
|
|
|
|
@ifset GENERIC
|
|
@item -rpath @var{dir}
|
|
@cindex runtime library search path
|
|
@kindex -rpath
|
|
Add a directory to the runtime library search path. This is used when
|
|
linking an ELF executable with shared objects. All @code{-rpath}
|
|
arguments are concatenated and passed to the runtime linker, which uses
|
|
them to locate shared objects at runtime. The @code{-rpath} option is
|
|
also used when locating shared objects which are needed by shared
|
|
objects explicitly included in the link; see the description of the
|
|
@code{-rpath-link} option. If @code{-rpath} is not used when linking an
|
|
ELF executable, the contents of the environment variable
|
|
@code{LD_RUN_PATH} will be used if it is defined.
|
|
|
|
The @code{-rpath} option may also be used on SunOS. By default, on
|
|
SunOS, the linker will form a runtime search patch out of all the
|
|
@code{-L} options it is given. If a @code{-rpath} option is used, the
|
|
runtime search path will be formed exclusively using the @code{-rpath}
|
|
options, ignoring the @code{-L} options. This can be useful when using
|
|
gcc, which adds many @code{-L} options which may be on NFS mounted
|
|
filesystems.
|
|
|
|
For compatibility with other ELF linkers, if the @code{-R} option is
|
|
followed by a directory name, rather than a file name, it is treated as
|
|
the @code{-rpath} option.
|
|
@end ifset
|
|
|
|
@ifset GENERIC
|
|
@cindex link-time runtime library search path
|
|
@kindex -rpath-link
|
|
@item -rpath-link @var{DIR}
|
|
When using ELF or SunOS, one shared library may require another. This
|
|
happens when an @code{ld -shared} link includes a shared library as one
|
|
of the input files.
|
|
|
|
When the linker encounters such a dependency when doing a non-shared,
|
|
non-relocateable link, it will automatically try to locate the required
|
|
shared library and include it in the link, if it is not included
|
|
explicitly. In such a case, the @code{-rpath-link} option
|
|
specifies the first set of directories to search. The
|
|
@code{-rpath-link} option may specify a sequence of directory names
|
|
either by specifying a list of names separated by colons, or by
|
|
appearing multiple times.
|
|
|
|
The linker uses the following search paths to locate required shared
|
|
libraries.
|
|
@enumerate
|
|
@item
|
|
Any directories specified by @code{-rpath-link} options.
|
|
@item
|
|
Any directories specified by @code{-rpath} options. The difference
|
|
between @code{-rpath} and @code{-rpath-link} is that directories
|
|
specified by @code{-rpath} options are included in the executable and
|
|
used at runtime, whereas the @code{-rpath-link} option is only effective
|
|
at link time.
|
|
@item
|
|
On an ELF system, if the @code{-rpath} and @code{rpath-link} options
|
|
were not used, search the contents of the environment variable
|
|
@code{LD_RUN_PATH}.
|
|
@item
|
|
On SunOS, if the @code{-rpath} option was not used, search any
|
|
directories specified using @code{-L} options.
|
|
@item
|
|
For a native linker, the contents of the environment variable
|
|
@code{LD_LIBRARY_PATH}.
|
|
@item
|
|
The default directories, normally @file{/lib} and @file{/usr/lib}.
|
|
@end enumerate
|
|
|
|
If the required shared library is not found, the linker will issue a
|
|
warning and continue with the link.
|
|
@end ifset
|
|
|
|
@kindex -shared
|
|
@kindex -Bshareable
|
|
@item -shared
|
|
@itemx -Bshareable
|
|
@cindex shared libraries
|
|
Create a shared library. This is currently only supported on ELF, XCOFF
|
|
and SunOS platforms. On SunOS, the linker will automatically create a
|
|
shared library if the @code{-e} option is not used and there are
|
|
undefined symbols in the link.
|
|
|
|
@item --sort-common
|
|
@kindex --sort-common
|
|
This option tells @code{ld} to sort the common symbols by size when it
|
|
places them in the appropriate output sections. First come all the one
|
|
byte symbols, then all the two bytes, then all the four bytes, and then
|
|
everything else. This is to prevent gaps between symbols due to
|
|
alignment constraints.
|
|
|
|
@kindex --split-by-file
|
|
@item --split-by-file
|
|
Similar to @code{--split-by-reloc} but creates a new output section for
|
|
each input file.
|
|
|
|
@kindex --split-by-reloc
|
|
@item --split-by-reloc @var{count}
|
|
Trys to creates extra sections in the output file so that no single
|
|
output section in the file contains more than @var{count} relocations.
|
|
This is useful when generating huge relocatable for downloading into
|
|
certain real time kernels with the COFF object file format; since COFF
|
|
cannot represent more than 65535 relocations in a single section. Note
|
|
that this will fail to work with object file formats which do not
|
|
support arbitrary sections. The linker will not split up individual
|
|
input sections for redistribution, so if a single input section contains
|
|
more than @var{count} relocations one output section will contain that
|
|
many relocations.
|
|
|
|
@kindex --stats
|
|
@item --stats
|
|
Compute and display statistics about the operation of the linker, such
|
|
as execution time and memory usage.
|
|
|
|
@kindex --traditional-format
|
|
@cindex traditional format
|
|
@item --traditional-format
|
|
For some targets, the output of @code{ld} is different in some ways from
|
|
the output of some existing linker. This switch requests @code{ld} to
|
|
use the traditional format instead.
|
|
|
|
@cindex dbx
|
|
For example, on SunOS, @code{ld} combines duplicate entries in the
|
|
symbol string table. This can reduce the size of an output file with
|
|
full debugging information by over 30 percent. Unfortunately, the SunOS
|
|
@code{dbx} program can not read the resulting program (@code{gdb} has no
|
|
trouble). The @samp{--traditional-format} switch tells @code{ld} to not
|
|
combine duplicate entries.
|
|
|
|
@kindex -Tbss @var{org}
|
|
@kindex -Tdata @var{org}
|
|
@kindex -Ttext @var{org}
|
|
@cindex segment origins, cmd line
|
|
@item -Tbss @var{org}
|
|
@itemx -Tdata @var{org}
|
|
@itemx -Ttext @var{org}
|
|
Use @var{org} as the starting address for---respectively---the
|
|
@code{bss}, @code{data}, or the @code{text} segment of the output file.
|
|
@var{org} must be a single hexadecimal integer;
|
|
for compatibility with other linkers, you may omit the leading
|
|
@samp{0x} usually associated with hexadecimal values.
|
|
|
|
@kindex -Ur
|
|
@cindex constructors
|
|
@item -Ur
|
|
For anything other than C++ programs, this option is equivalent to
|
|
@samp{-r}: it generates relocatable output---i.e., an output file that can in
|
|
turn serve as input to @code{ld}. When linking C++ programs, @samp{-Ur}
|
|
@emph{does} resolve references to constructors, unlike @samp{-r}.
|
|
It does not work to use @samp{-Ur} on files that were themselves linked
|
|
with @samp{-Ur}; once the constructor table has been built, it cannot
|
|
be added to. Use @samp{-Ur} only for the last partial link, and
|
|
@samp{-r} for the others.
|
|
|
|
@kindex --verbose
|
|
@cindex verbose
|
|
@item --verbose
|
|
Display the version number for @code{ld} and list the linker emulations
|
|
supported. Display which input files can and cannot be opened. Display
|
|
the linker script if using a default builtin script.
|
|
|
|
@kindex --warn-comon
|
|
@cindex warnings, on combining symbols
|
|
@cindex combining symbols, warnings on
|
|
@item --warn-common
|
|
Warn when a common symbol is combined with another common symbol or with
|
|
a symbol definition. Unix linkers allow this somewhat sloppy practice,
|
|
but linkers on some other operating systems do not. This option allows
|
|
you to find potential problems from combining global symbols.
|
|
Unfortunately, some C libraries use this practice, so you may get some
|
|
warnings about symbols in the libraries as well as in your programs.
|
|
|
|
There are three kinds of global symbols, illustrated here by C examples:
|
|
|
|
@table @samp
|
|
@item int i = 1;
|
|
A definition, which goes in the initialized data section of the output
|
|
file.
|
|
|
|
@item extern int i;
|
|
An undefined reference, which does not allocate space.
|
|
There must be either a definition or a common symbol for the
|
|
variable somewhere.
|
|
|
|
@item int i;
|
|
A common symbol. If there are only (one or more) common symbols for a
|
|
variable, it goes in the uninitialized data area of the output file.
|
|
The linker merges multiple common symbols for the same variable into a
|
|
single symbol. If they are of different sizes, it picks the largest
|
|
size. The linker turns a common symbol into a declaration, if there is
|
|
a definition of the same variable.
|
|
@end table
|
|
|
|
The @samp{--warn-common} option can produce five kinds of warnings.
|
|
Each warning consists of a pair of lines: the first describes the symbol
|
|
just encountered, and the second describes the previous symbol
|
|
encountered with the same name. One or both of the two symbols will be
|
|
a common symbol.
|
|
|
|
@enumerate
|
|
@item
|
|
Turning a common symbol into a reference, because there is already a
|
|
definition for the symbol.
|
|
@smallexample
|
|
@var{file}(@var{section}): warning: common of `@var{symbol}'
|
|
overridden by definition
|
|
@var{file}(@var{section}): warning: defined here
|
|
@end smallexample
|
|
|
|
@item
|
|
Turning a common symbol into a reference, because a later definition for
|
|
the symbol is encountered. This is the same as the previous case,
|
|
except that the symbols are encountered in a different order.
|
|
@smallexample
|
|
@var{file}(@var{section}): warning: definition of `@var{symbol}'
|
|
overriding common
|
|
@var{file}(@var{section}): warning: common is here
|
|
@end smallexample
|
|
|
|
@item
|
|
Merging a common symbol with a previous same-sized common symbol.
|
|
@smallexample
|
|
@var{file}(@var{section}): warning: multiple common
|
|
of `@var{symbol}'
|
|
@var{file}(@var{section}): warning: previous common is here
|
|
@end smallexample
|
|
|
|
@item
|
|
Merging a common symbol with a previous larger common symbol.
|
|
@smallexample
|
|
@var{file}(@var{section}): warning: common of `@var{symbol}'
|
|
overridden by larger common
|
|
@var{file}(@var{section}): warning: larger common is here
|
|
@end smallexample
|
|
|
|
@item
|
|
Merging a common symbol with a previous smaller common symbol. This is
|
|
the same as the previous case, except that the symbols are
|
|
encountered in a different order.
|
|
@smallexample
|
|
@var{file}(@var{section}): warning: common of `@var{symbol}'
|
|
overriding smaller common
|
|
@var{file}(@var{section}): warning: smaller common is here
|
|
@end smallexample
|
|
@end enumerate
|
|
|
|
@kindex --warn-constructors
|
|
@item --warn-constructors
|
|
Warn if any global constructors are used. This is only useful for a few
|
|
object file formats. For formats like COFF or ELF, the linker can not
|
|
detect the use of global constructors.
|
|
|
|
@kindex --warn-multiple-gp
|
|
@item --warn-multiple-gp
|
|
Warn if multiple global pointer values are required in the output file.
|
|
This is only meaningful for certain processors, such as the Alpha.
|
|
Specifically, some processors put large-valued constants in a special
|
|
section. A special register (the global pointer) points into the middle
|
|
of this section, so that constants can be loaded efficiently via a
|
|
base-register relative addressing mode. Since the offset in
|
|
base-register relative mode is fixed and relatively small (e.g., 16
|
|
bits), this limits the maximum size of the constant pool. Thus, in
|
|
large programs, it is often necessary to use multiple global pointer
|
|
values in order to be able to address all possible constants. This
|
|
option causes a warning to be issued whenever this case occurs.
|
|
|
|
@kindex --warn-once
|
|
@cindex warnings, on undefined symbols
|
|
@cindex undefined symbols, warnings on
|
|
@item --warn-once
|
|
Only warn once for each undefined symbol, rather than once per module
|
|
which refers to it.
|
|
|
|
@kindex --warn-section-align
|
|
@cindex warnings, on section alignment
|
|
@cindex section alignment, warnings on
|
|
@item --warn-section-align
|
|
Warn if the address of an output section is changed because of
|
|
alignment. Typically, the alignment will be set by an input section.
|
|
The address will only be changed if it not explicitly specified; that
|
|
is, if the @code{SECTIONS} command does not specify a start address for
|
|
the section (@pxref{SECTIONS}).
|
|
|
|
@kindex --whole-archive
|
|
@cindex including an entire archive
|
|
@item --whole-archive
|
|
For each archive mentioned on the command line after the
|
|
@code{--whole-archive} option, include every object file in the archive
|
|
in the link, rather than searching the archive for the required object
|
|
files. This is normally used to turn an archive file into a shared
|
|
library, forcing every object to be included in the resulting shared
|
|
library. This option may be used more than once.
|
|
|
|
@kindex --wrap
|
|
@item --wrap @var{symbol}
|
|
Use a wrapper function for @var{symbol}. Any undefined reference to
|
|
@var{symbol} will be resolved to @code{__wrap_@var{symbol}}. Any
|
|
undefined reference to @code{__real_@var{symbol}} will be resolved to
|
|
@var{symbol}.
|
|
|
|
This can be used to provide a wrapper for a system function. The
|
|
wrapper function should be called @code{__wrap_@var{symbol}}. If it
|
|
wishes to call the system function, it should call
|
|
@code{__real_@var{symbol}}.
|
|
|
|
Here is a trivial example:
|
|
|
|
@smallexample
|
|
void *
|
|
__wrap_malloc (int c)
|
|
@{
|
|
printf ("malloc called with %ld\n", c);
|
|
return __real_malloc (c);
|
|
@}
|
|
@end smallexample
|
|
|
|
If you link other code with this file using @code{--wrap malloc}, then
|
|
all calls to @code{malloc} will call the function @code{__wrap_malloc}
|
|
instead. The call to @code{__real_malloc} in @code{__wrap_malloc} will
|
|
call the real @code{malloc} function.
|
|
|
|
You may wish to provide a @code{__real_malloc} function as well, so that
|
|
links without the @code{--wrap} option will succeed. If you do this,
|
|
you should not put the definition of @code{__real_malloc} in the same
|
|
file as @code{__wrap_malloc}; if you do, the assembler may resolve the
|
|
call before the linker has a chance to wrap it to @code{malloc}.
|
|
|
|
@end table
|
|
|
|
@ifset UsesEnvVars
|
|
@node Environment
|
|
@section Environment Variables
|
|
|
|
You can change the behavior of @code{ld} with the environment
|
|
variable @code{GNUTARGET}.
|
|
|
|
@kindex GNUTARGET
|
|
@cindex default input format
|
|
@code{GNUTARGET} determines the input-file object format if you don't
|
|
use @samp{-b} (or its synonym @samp{--format}). Its value should be one
|
|
of the BFD names for an input format (@pxref{BFD}). If there is no
|
|
@code{GNUTARGET} in the environment, @code{ld} uses the natural format
|
|
of the target. If @code{GNUTARGET} is set to @code{default} then BFD
|
|
attempts to discover the input format by examining binary input files;
|
|
this method often succeeds, but there are potential ambiguities, since
|
|
there is no method of ensuring that the magic number used to specify
|
|
object-file formats is unique. However, the configuration procedure for
|
|
BFD on each system places the conventional format for that system first
|
|
in the search-list, so ambiguities are resolved in favor of convention.
|
|
@end ifset
|
|
|
|
@node Commands
|
|
@chapter Command Language
|
|
|
|
@cindex command files
|
|
The command language provides explicit control over the link process,
|
|
allowing complete specification of the mapping between the linker's
|
|
input files and its output. It controls:
|
|
@itemize @bullet
|
|
@item
|
|
input files
|
|
@item
|
|
file formats
|
|
@item
|
|
output file layout
|
|
@item
|
|
addresses of sections
|
|
@item
|
|
placement of common blocks
|
|
@end itemize
|
|
|
|
You may supply a command file (also known as a link script) to the
|
|
linker either explicitly through the @samp{-T} option, or implicitly as
|
|
an ordinary file. If the linker opens a file which it cannot recognize
|
|
as a supported object or archive format, it reports an error.
|
|
|
|
@menu
|
|
* Scripts:: Linker Scripts
|
|
* Expressions:: Expressions
|
|
* MEMORY:: MEMORY Command
|
|
* SECTIONS:: SECTIONS Command
|
|
* PHDRS:: PHDRS Command
|
|
* Entry Point:: The Entry Point
|
|
* Option Commands:: Option Commands
|
|
@end menu
|
|
|
|
@node Scripts
|
|
@section Linker Scripts
|
|
The @code{ld} command language is a collection of statements; some are
|
|
simple keywords setting a particular option, some are used to select and
|
|
group input files or name output files; and two statement
|
|
types have a fundamental and pervasive impact on the linking process.
|
|
|
|
@cindex fundamental script commands
|
|
@cindex commands, fundamental
|
|
@cindex output file layout
|
|
@cindex layout of output file
|
|
The most fundamental command of the @code{ld} command language is the
|
|
@code{SECTIONS} command (@pxref{SECTIONS}). Every meaningful command
|
|
script must have a @code{SECTIONS} command: it specifies a
|
|
``picture'' of the output file's layout, in varying degrees of detail.
|
|
No other command is required in all cases.
|
|
|
|
The @code{MEMORY} command complements @code{SECTIONS} by describing the
|
|
available memory in the target architecture. This command is optional;
|
|
if you don't use a @code{MEMORY} command, @code{ld} assumes sufficient
|
|
memory is available in a contiguous block for all output.
|
|
@xref{MEMORY}.
|
|
|
|
@cindex comments
|
|
You may include comments in linker scripts just as in C: delimited
|
|
by @samp{/*} and @samp{*/}. As in C, comments are syntactically
|
|
equivalent to whitespace.
|
|
|
|
@node Expressions
|
|
@section Expressions
|
|
@cindex expression syntax
|
|
@cindex arithmetic
|
|
Many useful commands involve arithmetic expressions. The syntax for
|
|
expressions in the command language is identical to that of C
|
|
expressions, with the following features:
|
|
@itemize @bullet
|
|
@item
|
|
All expressions evaluated as integers and
|
|
are of ``long'' or ``unsigned long'' type.
|
|
@item
|
|
All constants are integers.
|
|
@item
|
|
All of the C arithmetic operators are provided.
|
|
@item
|
|
You may reference, define, and create global variables.
|
|
@item
|
|
You may call special purpose built-in functions.
|
|
@end itemize
|
|
|
|
@menu
|
|
* Integers:: Integers
|
|
* Symbols:: Symbol Names
|
|
* Location Counter:: The Location Counter
|
|
* Operators:: Operators
|
|
* Evaluation:: Evaluation
|
|
* Assignment:: Assignment: Defining Symbols
|
|
* Arithmetic Functions:: Built-In Functions
|
|
* Semicolons:: Semicolon Usage
|
|
@end menu
|
|
|
|
@node Integers
|
|
@subsection Integers
|
|
@cindex integer notation
|
|
@cindex octal integers
|
|
An octal integer is @samp{0} followed by zero or more of the octal
|
|
digits (@samp{01234567}).
|
|
@smallexample
|
|
_as_octal = 0157255;
|
|
@end smallexample
|
|
|
|
@cindex decimal integers
|
|
A decimal integer starts with a non-zero digit followed by zero or
|
|
more digits (@samp{0123456789}).
|
|
@smallexample
|
|
_as_decimal = 57005;
|
|
@end smallexample
|
|
|
|
@cindex hexadecimal integers
|
|
@kindex 0x
|
|
A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or
|
|
more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}.
|
|
@smallexample
|
|
_as_hex = 0xdead;
|
|
@end smallexample
|
|
|
|
@cindex negative integers
|
|
To write a negative integer, use
|
|
the prefix operator @samp{-} (@pxref{Operators}).
|
|
@smallexample
|
|
_as_neg = -57005;
|
|
@end smallexample
|
|
|
|
@cindex scaled integers
|
|
@cindex K and M integer suffixes
|
|
@cindex M and K integer suffixes
|
|
@cindex suffixes for integers
|
|
@cindex integer suffixes
|
|
Additionally the suffixes @code{K} and @code{M} may be used to scale a
|
|
constant by
|
|
@c TEXI2ROFF-KILL
|
|
@ifinfo
|
|
@c END TEXI2ROFF-KILL
|
|
@code{1024} or @code{1024*1024}
|
|
@c TEXI2ROFF-KILL
|
|
@end ifinfo
|
|
@tex
|
|
${\rm 1024}$ or ${\rm 1024}^2$
|
|
@end tex
|
|
@c END TEXI2ROFF-KILL
|
|
respectively. For example, the following all refer to the same quantity:
|
|
|
|
@smallexample
|
|
_fourk_1 = 4K;
|
|
_fourk_2 = 4096;
|
|
_fourk_3 = 0x1000;
|
|
@end smallexample
|
|
|
|
@node Symbols
|
|
@subsection Symbol Names
|
|
@cindex symbol names
|
|
@cindex names
|
|
@cindex quoted symbol names
|
|
@kindex "
|
|
Unless quoted, symbol names start with a letter, underscore, or point
|
|
and may include any letters, underscores, digits, points,
|
|
and hyphens. Unquoted symbol names must not conflict with any
|
|
keywords. You can specify a symbol which contains odd characters or has
|
|
the same name as a keyword, by surrounding the symbol name in double quotes:
|
|
@smallexample
|
|
"SECTION" = 9;
|
|
"with a space" = "also with a space" + 10;
|
|
@end smallexample
|
|
|
|
Since symbols can contain many non-alphabetic characters, it is safest
|
|
to delimit symbols with spaces. For example, @samp{A-B} is one symbol,
|
|
whereas @samp{A - B} is an expression involving subtraction.
|
|
|
|
@node Location Counter
|
|
@subsection The Location Counter
|
|
@kindex .
|
|
@cindex dot
|
|
@cindex location counter
|
|
@cindex current output location
|
|
The special linker variable @dfn{dot} @samp{.} always contains the
|
|
current output location counter. Since the @code{.} always refers to
|
|
a location in an output section, it must always appear in an
|
|
expression within a @code{SECTIONS} command. The @code{.} symbol
|
|
may appear anywhere that an ordinary symbol is allowed in an
|
|
expression, but its assignments have a side effect. Assigning a value
|
|
to the @code{.} symbol will cause the location counter to be moved.
|
|
@cindex holes
|
|
This may be used to create holes in the output section. The location
|
|
counter may never be moved backwards.
|
|
@smallexample
|
|
SECTIONS
|
|
@{
|
|
output :
|
|
@{
|
|
file1(.text)
|
|
. = . + 1000;
|
|
file2(.text)
|
|
. += 1000;
|
|
file3(.text)
|
|
@} = 0x1234;
|
|
@}
|
|
@end smallexample
|
|
@noindent
|
|
In the previous example, @code{file1} is located at the beginning of the
|
|
output section, then there is a 1000 byte gap. Then @code{file2}
|
|
appears, also with a 1000 byte gap following before @code{file3} is
|
|
loaded. The notation @samp{= 0x1234} specifies what data to write in
|
|
the gaps (@pxref{Section Options}).
|
|
|
|
@iftex
|
|
@vfill
|
|
@end iftex
|
|
|
|
@need 2000
|
|
@node Operators
|
|
@subsection Operators
|
|
@cindex Operators for arithmetic
|
|
@cindex arithmetic operators
|
|
@cindex precedence in expressions
|
|
The linker recognizes the standard C set of arithmetic operators, with
|
|
the standard bindings and precedence levels:
|
|
@c TEXI2ROFF-KILL
|
|
@ifinfo
|
|
@c END TEXI2ROFF-KILL
|
|
@smallexample
|
|
precedence associativity Operators Notes
|
|
(highest)
|
|
1 left ! - ~ (1)
|
|
2 left * / %
|
|
3 left + -
|
|
4 left >> <<
|
|
5 left == != > < <= >=
|
|
6 left &
|
|
7 left |
|
|
8 left &&
|
|
9 left ||
|
|
10 right ? :
|
|
11 right &= += -= *= /= (2)
|
|
(lowest)
|
|
@end smallexample
|
|
Notes:
|
|
(1) Prefix operators
|
|
(2) @xref{Assignment}.
|
|
@c TEXI2ROFF-KILL
|
|
@end ifinfo
|
|
@tex
|
|
\vskip \baselineskip
|
|
%"lispnarrowing" is the extra indent used generally for @smallexample
|
|
\hskip\lispnarrowing\vbox{\offinterlineskip
|
|
\hrule
|
|
\halign
|
|
{\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
|
|
height2pt&\omit&&\omit&&\omit&\cr
|
|
&Precedence&& Associativity &&{\rm Operators}&\cr
|
|
height2pt&\omit&&\omit&&\omit&\cr
|
|
\noalign{\hrule}
|
|
height2pt&\omit&&\omit&&\omit&\cr
|
|
&highest&&&&&\cr
|
|
% '176 is tilde, '~' in tt font
|
|
&1&&left&&\qquad- \char'176\ !\qquad\dag&\cr
|
|
&2&&left&&* / \%&\cr
|
|
&3&&left&&+ -&\cr
|
|
&4&&left&&>> <<&\cr
|
|
&5&&left&&== != > < <= >=&\cr
|
|
&6&&left&&\&&\cr
|
|
&7&&left&&|&\cr
|
|
&8&&left&&{\&\&}&\cr
|
|
&9&&left&&||&\cr
|
|
&10&&right&&? :&\cr
|
|
&11&&right&&\qquad\&= += -= *= /=\qquad\ddag&\cr
|
|
&lowest&&&&&\cr
|
|
height2pt&\omit&&\omit&&\omit&\cr}
|
|
\hrule}
|
|
@end tex
|
|
@iftex
|
|
{
|
|
@obeylines@parskip=0pt@parindent=0pt
|
|
@dag@quad Prefix operators.
|
|
@ddag@quad @xref{Assignment}.
|
|
}
|
|
@end iftex
|
|
@c END TEXI2ROFF-KILL
|
|
|
|
@node Evaluation
|
|
@subsection Evaluation
|
|
|
|
@cindex lazy evaluation
|
|
@cindex expression evaluation order
|
|
The linker uses ``lazy evaluation'' for expressions; it only calculates
|
|
an expression when absolutely necessary. The linker needs the value of
|
|
the start address, and the lengths of memory regions, in order to do any
|
|
linking at all; these values are computed as soon as possible when the
|
|
linker reads in the command file. However, other values (such as symbol
|
|
values) are not known or needed until after storage allocation. Such
|
|
values are evaluated later, when other information (such as the sizes of
|
|
output sections) is available for use in the symbol assignment
|
|
expression.
|
|
|
|
@node Assignment
|
|
@subsection Assignment: Defining Symbols
|
|
@cindex assignment in scripts
|
|
@cindex symbol definition, scripts
|
|
@cindex variables, defining
|
|
You may create global symbols, and assign values (addresses) to global
|
|
symbols, using any of the C assignment operators:
|
|
|
|
@table @code
|
|
@item @var{symbol} = @var{expression} ;
|
|
@itemx @var{symbol} &= @var{expression} ;
|
|
@itemx @var{symbol} += @var{expression} ;
|
|
@itemx @var{symbol} -= @var{expression} ;
|
|
@itemx @var{symbol} *= @var{expression} ;
|
|
@itemx @var{symbol} /= @var{expression} ;
|
|
@end table
|
|
|
|
Two things distinguish assignment from other operators in @code{ld}
|
|
expressions.
|
|
@itemize @bullet
|
|
@item
|
|
Assignment may only be used at the root of an expression;
|
|
@samp{a=b+3;} is allowed, but @samp{a+b=3;} is an error.
|
|
|
|
@kindex ;
|
|
@cindex semicolon
|
|
@item
|
|
You must place a trailing semicolon (``@key{;}'') at the end of an
|
|
assignment statement.
|
|
@end itemize
|
|
|
|
Assignment statements may appear:
|
|
@itemize @bullet
|
|
@item
|
|
as commands in their own right in an @code{ld} script; or
|
|
@item
|
|
as independent statements within a @code{SECTIONS} command; or
|
|
@item
|
|
as part of the contents of a section definition in a
|
|
@code{SECTIONS} command.
|
|
@end itemize
|
|
|
|
The first two cases are equivalent in effect---both define a symbol with
|
|
an absolute address. The last case defines a symbol whose address is
|
|
relative to a particular section (@pxref{SECTIONS}).
|
|
|
|
@cindex absolute and relocatable symbols
|
|
@cindex relocatable and absolute symbols
|
|
@cindex symbols, relocatable and absolute
|
|
When a linker expression is evaluated and assigned to a variable, it is
|
|
given either an absolute or a relocatable type. An absolute expression
|
|
type is one in which the symbol contains the value that it will have in
|
|
the output file; a relocatable expression type is one in which the
|
|
value is expressed as a fixed offset from the base of a section.
|
|
|
|
The type of the expression is controlled by its position in the script
|
|
file. A symbol assigned within a section definition is created relative
|
|
to the base of the section; a symbol assigned in any other place is
|
|
created as an absolute symbol. Since a symbol created within a
|
|
section definition is relative to the base of the section, it
|
|
will remain relocatable if relocatable output is requested. A symbol
|
|
may be created with an absolute value even when assigned to within a
|
|
section definition by using the absolute assignment function
|
|
@code{ABSOLUTE}. For example, to create an absolute symbol whose address
|
|
is the last byte of an output section named @code{.data}:
|
|
@smallexample
|
|
SECTIONS@{ @dots{}
|
|
.data :
|
|
@{
|
|
*(.data)
|
|
_edata = ABSOLUTE(.) ;
|
|
@}
|
|
@dots{} @}
|
|
@end smallexample
|
|
|
|
The linker tries to put off the evaluation of an assignment until all
|
|
the terms in the source expression are known (@pxref{Evaluation}). For
|
|
instance, the sizes of sections cannot be known until after allocation,
|
|
so assignments dependent upon these are not performed until after
|
|
allocation. Some expressions, such as those depending upon the location
|
|
counter @dfn{dot}, @samp{.} must be evaluated during allocation. If the
|
|
result of an expression is required, but the value is not available,
|
|
then an error results. For example, a script like the following
|
|
@smallexample
|
|
SECTIONS @{ @dots{}
|
|
text 9+this_isnt_constant :
|
|
@{ @dots{}
|
|
@}
|
|
@dots{} @}
|
|
@end smallexample
|
|
@kindex Non constant expression
|
|
@noindent
|
|
will cause the error message ``@code{Non constant expression for initial
|
|
address}''.
|
|
|
|
@cindex provide
|
|
In some cases, it is desirable for a linker script to define a symbol
|
|
only if it is referenced, and only if it is not defined by any object
|
|
included in the link. For example, traditional linkers defined the
|
|
symbol @samp{etext}. However, ANSI C requires that the user be able to
|
|
use @samp{etext} as a function name without encountering an error.
|
|
The @code{PROVIDE} keyword may be used to define a symbol, such as
|
|
@samp{etext}, only if it is referenced but not defined. The syntax is
|
|
@code{PROVIDE(@var{symbol} = @var{expression})}.
|
|
|
|
@node Arithmetic Functions
|
|
@subsection Arithmetic Functions
|
|
@cindex functions in expression language
|
|
The command language includes a number of built-in
|
|
functions for use in link script expressions.
|
|
@table @code
|
|
@kindex ABSOLUTE(@var{exp})
|
|
@cindex expression, absolute
|
|
@item ABSOLUTE(@var{exp})
|
|
Return the absolute (non-relocatable, as opposed to non-negative) value
|
|
of the expression @var{exp}. Primarily useful to assign an absolute
|
|
value to a symbol within a section definition, where symbol values are
|
|
normally section-relative.
|
|
|
|
@kindex ADDR(@var{section})
|
|
@cindex section address
|
|
@item ADDR(@var{section})
|
|
Return the absolute address 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:
|
|
@smallexample
|
|
@group
|
|
SECTIONS@{ @dots{}
|
|
.output1 :
|
|
@{
|
|
start_of_output_1 = ABSOLUTE(.);
|
|
@dots{}
|
|
@}
|
|
.output :
|
|
@{
|
|
symbol_1 = ADDR(.output1);
|
|
symbol_2 = start_of_output_1;
|
|
@}
|
|
@dots{} @}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@kindex LOADADDR(@var{section})
|
|
@cindex section load address
|
|
@item LOADADDR(@var{section})
|
|
Return the absolute load address of the named @var{section}. This is
|
|
normally the same as @code{ADDR}, but it may be different if the
|
|
@code{AT} keyword is used in the section definition (@pxref{Section
|
|
Options}).
|
|
|
|
@kindex ALIGN(@var{exp})
|
|
@cindex rounding up location counter
|
|
@item ALIGN(@var{exp})
|
|
Return the result of the current location counter (@code{.}) aligned to
|
|
the next @var{exp} boundary. @var{exp} must be an expression whose
|
|
value is a power of two. This is equivalent to
|
|
@smallexample
|
|
(. + @var{exp} - 1) & ~(@var{exp} - 1)
|
|
@end smallexample
|
|
|
|
@code{ALIGN} doesn't change the value of the location counter---it just
|
|
does arithmetic on it. As an example, to align the output @code{.data}
|
|
section to the next @code{0x2000} byte boundary after the preceding
|
|
section and to set a variable within the section to the next
|
|
@code{0x8000} boundary after the input sections:
|
|
@smallexample
|
|
@group
|
|
SECTIONS@{ @dots{}
|
|
.data ALIGN(0x2000): @{
|
|
*(.data)
|
|
variable = ALIGN(0x8000);
|
|
@}
|
|
@dots{} @}
|
|
@end group
|
|
@end smallexample
|
|
@noindent
|
|
The first use of @code{ALIGN} in this example specifies the location of
|
|
a section because it is used as the optional @var{start} attribute of a
|
|
section definition (@pxref{Section Options}). The second use simply
|
|
defines the value of a variable.
|
|
|
|
The built-in @code{NEXT} is closely related to @code{ALIGN}.
|
|
|
|
@kindex DEFINED(@var{symbol})
|
|
@cindex symbol defaults
|
|
@item DEFINED(@var{symbol})
|
|
Return 1 if @var{symbol} is in the linker global symbol table and is
|
|
defined, otherwise return 0. You can use this function to provide default
|
|
values for symbols. For example, the following command-file fragment shows how
|
|
to set a global symbol @code{begin} to the first location in the
|
|
@code{.text} section---but if a symbol called @code{begin} already
|
|
existed, its value is preserved:
|
|
|
|
@smallexample
|
|
@group
|
|
SECTIONS@{ @dots{}
|
|
.text : @{
|
|
begin = DEFINED(begin) ? begin : . ;
|
|
@dots{}
|
|
@}
|
|
@dots{} @}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@kindex NEXT(@var{exp})
|
|
@cindex unallocated address, next
|
|
@item NEXT(@var{exp})
|
|
Return the next unallocated address that is a multiple of @var{exp}.
|
|
This function is closely related to @code{ALIGN(@var{exp})}; unless you
|
|
use the @code{MEMORY} command to define discontinuous memory for the
|
|
output file, the two functions are equivalent.
|
|
|
|
@kindex SIZEOF(@var{section})
|
|
@cindex section size
|
|
@item SIZEOF(@var{section})
|
|
Return the size in bytes of the named @var{section}, if that section has
|
|
been allocated. In the following example, @code{symbol_1} and
|
|
@code{symbol_2} are assigned identical values:
|
|
@c What does it return if the section hasn't been allocated? 0?
|
|
@smallexample
|
|
@group
|
|
SECTIONS@{ @dots{}
|
|
.output @{
|
|
.start = . ;
|
|
@dots{}
|
|
.end = . ;
|
|
@}
|
|
symbol_1 = .end - .start ;
|
|
symbol_2 = SIZEOF(.output);
|
|
@dots{} @}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@kindex SIZEOF_HEADERS
|
|
@cindex header size
|
|
@kindex sizeof_headers
|
|
@item SIZEOF_HEADERS
|
|
@itemx sizeof_headers
|
|
Return the size in bytes of the output file's headers. You can use this number
|
|
as the start address of the first section, if you choose, to facilitate
|
|
paging.
|
|
|
|
@kindex MAX
|
|
@item MAX(@var{exp1}, @var{exp2})
|
|
Returns the maximum of @var{exp1} and @var{exp2}.
|
|
|
|
@kindex MIN
|
|
@item MIN(@var{exp1}, @var{exp2})
|
|
Returns the minimum of @var{exp1} and @var{exp2}.
|
|
|
|
@end table
|
|
|
|
@node Semicolons
|
|
@subsection Semicolons
|
|
|
|
Semicolons (``@key{;}'') are required in the following places. In all
|
|
other places they can appear for aesthetic reasons but are otherwise ignored.
|
|
|
|
@table @code
|
|
@item Assignment
|
|
Semicolons must appear at the end of assignment expressions.
|
|
@xref{Assignment}
|
|
|
|
@item PHDRS
|
|
Semicolons must appear at the end of a @code{PHDRS} statement.
|
|
@xref{PHDRS}
|
|
@end table
|
|
|
|
@node MEMORY
|
|
@section Memory Layout
|
|
@kindex MEMORY
|
|
@cindex regions of memory
|
|
@cindex discontinuous memory
|
|
@cindex allocating memory
|
|
The linker's default configuration permits allocation of all available memory.
|
|
You can override this configuration by using the @code{MEMORY} command. The
|
|
@code{MEMORY} command describes the location and size of blocks of
|
|
memory in the target. By using it carefully, you can describe which
|
|
memory regions may be used by the linker, and which memory regions it
|
|
must avoid. The linker does not shuffle sections to fit into the
|
|
available regions, but does move the requested sections into the correct
|
|
regions and issue errors when the regions become too full.
|
|
|
|
A command file may contain at most one use of the @code{MEMORY}
|
|
command; however, you can define as many blocks of memory within it as
|
|
you wish. The syntax is:
|
|
|
|
@smallexample
|
|
@group
|
|
MEMORY
|
|
@{
|
|
@var{name} (@var{attr}) : ORIGIN = @var{origin}, LENGTH = @var{len}
|
|
@dots{}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
@table @code
|
|
@cindex naming memory regions
|
|
@item @var{name}
|
|
is a name used internally by the linker to refer to the region. Any
|
|
symbol name may be used. The region names are stored in a separate
|
|
name space, and will not conflict with symbols, file names or section
|
|
names. Use distinct names to specify multiple regions.
|
|
|
|
@cindex memory region attributes
|
|
@item (@var{attr})
|
|
is an optional list of attributes, permitted for compatibility with the
|
|
AT&T linker but not used by @code{ld} beyond checking that the
|
|
attribute list is valid. Valid attribute lists must be made up of the
|
|
characters ``@code{LIRWX}''. If you omit the attribute list, you may
|
|
omit the parentheses around it as well.
|
|
|
|
@kindex ORIGIN =
|
|
@kindex o =
|
|
@kindex org =
|
|
@item @var{origin}
|
|
is the start address of the region in physical memory. It is
|
|
an expression that must evaluate to a constant before
|
|
memory allocation is performed. The keyword @code{ORIGIN} may be
|
|
abbreviated to @code{org} or @code{o} (but not, for example, @samp{ORG}).
|
|
|
|
@kindex LENGTH =
|
|
@kindex len =
|
|
@kindex l =
|
|
@item @var{len}
|
|
is the size in bytes of the region (an expression).
|
|
The keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}.
|
|
@end table
|
|
|
|
For example, to specify that memory has two regions available for
|
|
allocation---one starting at 0 for 256 kilobytes, and the other
|
|
starting at @code{0x40000000} for four megabytes:
|
|
|
|
@smallexample
|
|
@group
|
|
MEMORY
|
|
@{
|
|
rom : ORIGIN = 0, LENGTH = 256K
|
|
ram : org = 0x40000000, l = 4M
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
Once you have defined a region of memory named @var{mem}, you can direct
|
|
specific output sections there by using a command ending in
|
|
@samp{>@var{mem}} within the @code{SECTIONS} command (@pxref{Section
|
|
Options}). If the combined output sections directed to a region are too
|
|
big for the region, the linker will issue an error message.
|
|
|
|
@node SECTIONS
|
|
@section Specifying Output Sections
|
|
|
|
@kindex SECTIONS
|
|
The @code{SECTIONS} command controls exactly where input sections are
|
|
placed into output sections, their order in the output file, and to
|
|
which output sections they are allocated.
|
|
|
|
You may use at most one @code{SECTIONS} command in a script file,
|
|
but you can have as many statements within it as you wish. Statements
|
|
within the @code{SECTIONS} command can do one of three things:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
define the entry point;
|
|
|
|
@item
|
|
assign a value to a symbol;
|
|
|
|
@item
|
|
describe the placement of a named output section, and which input
|
|
sections go into it.
|
|
@end itemize
|
|
|
|
You can also use the first two operations---defining the entry point and
|
|
defining symbols---outside the @code{SECTIONS} command: @pxref{Entry
|
|
Point}, and @ref{Assignment}. They are permitted here as well for
|
|
your convenience in reading the script, so that symbols and the entry
|
|
point can be defined at meaningful points in your output-file layout.
|
|
|
|
If you do not use a @code{SECTIONS} command, the linker places each input
|
|
section into an identically named output section in the order that the
|
|
sections are first encountered in the input files. If all input sections
|
|
are present in the first file, for example, the order of sections in the
|
|
output file will match the order in the first input file.
|
|
|
|
@menu
|
|
* Section Definition:: Section Definitions
|
|
* Section Placement:: Section Placement
|
|
* Section Data Expressions:: Section Data Expressions
|
|
* Section Options:: Optional Section Attributes
|
|
* Overlays:: Overlays
|
|
@end menu
|
|
|
|
@node Section Definition
|
|
@subsection Section Definitions
|
|
@cindex section definition
|
|
The most frequently used statement in the @code{SECTIONS} command is
|
|
the @dfn{section definition}, which specifies the
|
|
properties of an output section: its location, alignment, contents,
|
|
fill pattern, and target memory region. Most of
|
|
these specifications are optional; the simplest form of a section
|
|
definition is
|
|
@smallexample
|
|
SECTIONS @{ @dots{}
|
|
@var{secname} : @{
|
|
@var{contents}
|
|
@}
|
|
@dots{} @}
|
|
@end smallexample
|
|
@cindex naming output sections
|
|
@noindent
|
|
@var{secname} is the name of the output section, and @var{contents} a
|
|
specification of what goes there---for example, a list of input files or
|
|
sections of input files (@pxref{Section Placement}). As you might
|
|
assume, the whitespace shown is optional. You do need the colon
|
|
@samp{:} and the braces @samp{@{@}}, however.
|
|
|
|
@var{secname} must meet the constraints of your output format. In
|
|
formats which only support a limited number of sections, such as
|
|
@code{a.out}, the name must be one of the names supported by the format
|
|
(@code{a.out}, for example, allows only @code{.text}, @code{.data} or
|
|
@code{.bss}). If the output format supports any number of sections, but
|
|
with numbers and not names (as is the case for Oasys), the name should be
|
|
supplied as a quoted numeric string. A section name may consist of any
|
|
sequence of characters, but any name which does not conform to the standard
|
|
@code{ld} symbol name syntax must be quoted.
|
|
@xref{Symbols, , Symbol Names}.
|
|
|
|
The special @var{secname} @samp{/DISCARD/} may be used to discard input
|
|
sections. Any sections which are assigned to an output section named
|
|
@samp{/DISCARD/} are not included in the final link output.
|
|
|
|
The linker will not create output sections which do not have any
|
|
contents. This is for convenience when referring to input sections that
|
|
may or may not exist. For example,
|
|
@smallexample
|
|
.foo @{ *(.foo) @}
|
|
@end smallexample
|
|
will only create a @samp{.foo} section in the output file if there is a
|
|
@samp{.foo} section in at least one input file.
|
|
|
|
@node Section Placement
|
|
@subsection Section Placement
|
|
|
|
@cindex contents of a section
|
|
In a section definition, you can specify the contents of an output
|
|
section by listing particular input files, by listing particular
|
|
input-file sections, or by a combination of the two. You can also place
|
|
arbitrary data in the section, and define symbols relative to the
|
|
beginning of the section.
|
|
|
|
The @var{contents} of a section definition may include any of the
|
|
following kinds of statement. You can include as many of these as you
|
|
like in a single section definition, separated from one another by
|
|
whitespace.
|
|
|
|
@table @code
|
|
@kindex @var{filename}
|
|
@cindex input files, section defn
|
|
@cindex files, including in output sections
|
|
@item @var{filename}
|
|
You may simply name a particular input file to be placed in the current
|
|
output section; @emph{all} sections from that file are placed in the
|
|
current section definition. If the file name has already been mentioned
|
|
in another section definition, with an explicit section name list, then
|
|
only those sections which have not yet been allocated are used.
|
|
|
|
To specify a list of particular files by name:
|
|
@smallexample
|
|
.data : @{ afile.o bfile.o cfile.o @}
|
|
@end smallexample
|
|
@noindent
|
|
The example also illustrates that multiple statements can be included in
|
|
the contents of a section definition, since each file name is a separate
|
|
statement.
|
|
|
|
@kindex @var{filename}(@var{section})
|
|
@cindex files and sections, section defn
|
|
@item @var{filename}( @var{section} )
|
|
@itemx @var{filename}( @var{section} , @var{section}, @dots{} )
|
|
@itemx @var{filename}( @var{section} @var{section} @dots{} )
|
|
You can name one or more sections from your input files, for
|
|
insertion in the current output section. If you wish to specify a list
|
|
of input-file sections inside the parentheses, you may separate the
|
|
section names by either commas or whitespace.
|
|
|
|
@cindex input sections to output section
|
|
@kindex *(@var{section})
|
|
@item * (@var{section})
|
|
@itemx * (@var{section}, @var{section}, @dots{})
|
|
@itemx * (@var{section} @var{section} @dots{})
|
|
Instead of explicitly naming particular input files in a link control
|
|
script, you can refer to @emph{all} files from the @code{ld} command
|
|
line: use @samp{*} instead of a particular file name before the
|
|
parenthesized input-file section list.
|
|
|
|
If you have already explicitly included some files by name, @samp{*}
|
|
refers to all @emph{remaining} files---those whose places in the output
|
|
file have not yet been defined.
|
|
|
|
For example, to copy sections @code{1} through @code{4} from an Oasys file
|
|
into the @code{.text} section of an @code{a.out} file, and sections @code{13}
|
|
and @code{14} into the @code{.data} section:
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{
|
|
.text :@{
|
|
*("1" "2" "3" "4")
|
|
@}
|
|
|
|
.data :@{
|
|
*("13" "14")
|
|
@}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@cindex @code{[@var{section}@dots{}]}, not supported
|
|
@samp{[ @var{section} @dots{} ]} used to be accepted as an alternate way
|
|
to specify named sections from all unallocated input files. Because
|
|
some operating systems (VMS) allow brackets in file names, that notation
|
|
is no longer supported.
|
|
|
|
@cindex uninitialized data
|
|
@cindex commons in output
|
|
@kindex *( COMMON )
|
|
@item @var{filename}@code{( COMMON )}
|
|
@itemx *( COMMON )
|
|
Specify where in your output file to place uninitialized data
|
|
with this notation. @code{*(COMMON)} by itself refers to all
|
|
uninitialized data from all input files (so far as it is not yet
|
|
allocated); @var{filename}@code{(COMMON)} refers to uninitialized data
|
|
from a particular file. Both are special cases of the general
|
|
mechanisms for specifying where to place input-file sections:
|
|
@code{ld} permits you to refer to uninitialized data as if it
|
|
were in an input-file section named @code{COMMON}, regardless of the
|
|
input file's format.
|
|
@end table
|
|
|
|
In any place where you may use a specific file or section name, you may
|
|
also use a wildcard pattern. The linker handles wildcards much as the
|
|
Unix shell does. A @samp{*} character matches any number of characters.
|
|
A @samp{?} character matches any single character. The sequence
|
|
@samp{[@var{chars}]} will match a single instance of any of the
|
|
@var{chars}; the @samp{-} character may be used to specify a range of
|
|
characters, as in @samp{[a-z]} to match any lower case letter. A
|
|
@samp{\} character may be used to quote the following character.
|
|
|
|
When a file name is matched with a wildcard, the wildcard characters
|
|
will not match a @samp{/} character (used to separate directory names on
|
|
Unix). A pattern consisting of a single @samp{*} character is an
|
|
exception; it will always match any file name. In a section name, the
|
|
wildcard characters will match a @samp{/} character.
|
|
|
|
Wildcards only match files which are explicitly specified on the command
|
|
line. The linker does not search directories to expand wildcards.
|
|
However, if you specify a simple file name---a name with no wildcard
|
|
characters---in a linker script, and the file name is not also specified
|
|
on the command line, the linker will attempt to open the file as though
|
|
it appeared on the command line.
|
|
|
|
In the following example, the command script arranges the output file
|
|
into three consecutive sections, named @code{.text}, @code{.data}, and
|
|
@code{.bss}, taking the input for each from the correspondingly named
|
|
sections of all the input files:
|
|
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{
|
|
.text : @{ *(.text) @}
|
|
.data : @{ *(.data) @}
|
|
.bss : @{ *(.bss) *(COMMON) @}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
The following example reads all of the sections from file @code{all.o}
|
|
and places them at the start of output section @code{outputa} which
|
|
starts at location @code{0x10000}. All of section @code{.input1} from
|
|
file @code{foo.o} follows immediately, in the same output section. All
|
|
of section @code{.input2} from @code{foo.o} goes into output section
|
|
@code{outputb}, followed by section @code{.input1} from @code{foo1.o}.
|
|
All of the remaining @code{.input1} and @code{.input2} sections from any
|
|
files are written to output section @code{outputc}.
|
|
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{
|
|
outputa 0x10000 :
|
|
@{
|
|
all.o
|
|
foo.o (.input1)
|
|
@}
|
|
outputb :
|
|
@{
|
|
foo.o (.input2)
|
|
foo1.o (.input1)
|
|
@}
|
|
outputc :
|
|
@{
|
|
*(.input1)
|
|
*(.input2)
|
|
@}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
This example shows how wildcard patterns might be used to partition
|
|
files. All @code{.text} sections are placed in @code{.text}, and all
|
|
@code{.bss} sections are placed in @code{.bss}. For all files beginning
|
|
with an upper case character, the @code{.data} section is placed into
|
|
@code{.DATA}; for all other files, the @code{.data} section is placed
|
|
into @code{.data}.
|
|
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{
|
|
.text : @{ *(.text) @}
|
|
.DATA : @{ [A-Z]*(.data) @}
|
|
.data : @{ *(.data) @}
|
|
.bss : @{ *(.bss) @}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node Section Data Expressions
|
|
@subsection Section Data Expressions
|
|
|
|
@cindex expressions in a section
|
|
The foregoing statements arrange, in your output file, data originating
|
|
from your input files. You can also place data directly in an output
|
|
section from the link command script. Most of these additional
|
|
statements involve expressions (@pxref{Expressions}). Although these
|
|
statements are shown separately here for ease of presentation, no such
|
|
segregation is needed within a section definition in the @code{SECTIONS}
|
|
command; you can intermix them freely with any of the statements we've
|
|
just described.
|
|
|
|
@table @code
|
|
@cindex input filename symbols
|
|
@cindex filename symbols
|
|
@kindex CREATE_OBJECT_SYMBOLS
|
|
@item CREATE_OBJECT_SYMBOLS
|
|
Create a symbol for each input file
|
|
in the current section, set to the address of the first byte of
|
|
data written from that input file. For instance, with @code{a.out}
|
|
files it is conventional to have a symbol for each input file. You can
|
|
accomplish this by defining the output @code{.text} section as follows:
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{
|
|
.text 0x2020 :
|
|
@{
|
|
CREATE_OBJECT_SYMBOLS
|
|
*(.text)
|
|
_etext = ALIGN(0x2000);
|
|
@}
|
|
@dots{}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
If @code{sample.ld} is a file containing this script, and @code{a.o},
|
|
@code{b.o}, @code{c.o}, and @code{d.o} are four input files with
|
|
contents like the following---
|
|
@smallexample
|
|
@group
|
|
/* a.c */
|
|
|
|
afunction() @{ @}
|
|
int adata=1;
|
|
int abss;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
@samp{ld -M -T sample.ld a.o b.o c.o d.o} would create a map like this,
|
|
containing symbols matching the object file names:
|
|
@smallexample
|
|
00000000 A __DYNAMIC
|
|
00004020 B _abss
|
|
00004000 D _adata
|
|
00002020 T _afunction
|
|
00004024 B _bbss
|
|
00004008 D _bdata
|
|
00002038 T _bfunction
|
|
00004028 B _cbss
|
|
00004010 D _cdata
|
|
00002050 T _cfunction
|
|
0000402c B _dbss
|
|
00004018 D _ddata
|
|
00002068 T _dfunction
|
|
00004020 D _edata
|
|
00004030 B _end
|
|
00004000 T _etext
|
|
00002020 t a.o
|
|
00002038 t b.o
|
|
00002050 t c.o
|
|
00002068 t d.o
|
|
@end smallexample
|
|
|
|
@kindex @var{symbol} = @var{expression} ;
|
|
@kindex @var{symbol} @var{f}= @var{expression} ;
|
|
@item @var{symbol} = @var{expression} ;
|
|
@itemx @var{symbol} @var{f}= @var{expression} ;
|
|
@var{symbol} is any symbol name (@pxref{Symbols}). ``@var{f}=''
|
|
refers to any of the operators @code{&= += -= *= /=} which combine
|
|
arithmetic and assignment.
|
|
|
|
@cindex assignment, in section defn
|
|
When you assign a value to a symbol within a particular section
|
|
definition, the value is relative to the beginning of the section
|
|
(@pxref{Assignment}). If you write
|
|
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{
|
|
abs = 14 ;
|
|
@dots{}
|
|
.data : @{ @dots{} rel = 14 ; @dots{} @}
|
|
abs2 = 14 + ADDR(.data);
|
|
@dots{}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@c FIXME: Try above example!
|
|
@noindent
|
|
@code{abs} and @code{rel} do not have the same value; @code{rel} has the
|
|
same value as @code{abs2}.
|
|
|
|
@kindex BYTE(@var{expression})
|
|
@kindex SHORT(@var{expression})
|
|
@kindex LONG(@var{expression})
|
|
@kindex QUAD(@var{expression})
|
|
@cindex direct output
|
|
@item BYTE(@var{expression})
|
|
@itemx SHORT(@var{expression})
|
|
@itemx LONG(@var{expression})
|
|
@itemx QUAD(@var{expression})
|
|
By including one of these four statements in a section definition, you
|
|
can explicitly place one, two, four, or eight bytes (respectively) at
|
|
the current address of that section. @code{QUAD} is only supported when
|
|
using a 64 bit host or target.
|
|
|
|
@ifclear SingleFormat
|
|
Multiple-byte quantities are represented in whatever byte order is
|
|
appropriate for the output file format (@pxref{BFD}).
|
|
@end ifclear
|
|
|
|
@kindex FILL(@var{expression})
|
|
@cindex holes, filling
|
|
@cindex unspecified memory
|
|
@item FILL(@var{expression})
|
|
Specify the ``fill pattern'' for the current section. Any otherwise
|
|
unspecified regions of memory within the section (for example, regions
|
|
you skip over by assigning a new value to the location counter @samp{.})
|
|
are filled with the two least significant bytes from the
|
|
@var{expression} argument. A @code{FILL} statement covers memory
|
|
locations @emph{after} the point it occurs in the section definition; by
|
|
including more than one @code{FILL} statement, you can have different
|
|
fill patterns in different parts of an output section.
|
|
@end table
|
|
|
|
@node Section Options
|
|
@subsection Optional Section Attributes
|
|
@cindex section defn, full syntax
|
|
Here is the full syntax of a section definition, including all the
|
|
optional portions:
|
|
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{
|
|
@dots{}
|
|
@var{secname} @var{start} BLOCK(@var{align}) (NOLOAD) : AT ( @var{ldadr} )
|
|
@{ @var{contents} @} >@var{region} :@var{phdr} =@var{fill}
|
|
@dots{}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@var{secname} and @var{contents} are required. @xref{Section
|
|
Definition}, and @ref{Section Placement}, for details on
|
|
@var{contents}. The remaining elements---@var{start},
|
|
@code{BLOCK(@var{align)}}, @code{(NOLOAD)}, @code{AT ( @var{ldadr} )},
|
|
@code{>@var{region}}, @code{:@var{phdr}}, and @code{=@var{fill}}---are
|
|
all optional.
|
|
|
|
@table @code
|
|
@cindex start address, section
|
|
@cindex section start
|
|
@cindex section address
|
|
@item @var{start}
|
|
You can force the output section to be loaded at a specified address by
|
|
specifying @var{start} immediately following the section name.
|
|
@var{start} can be represented as any expression. The following
|
|
example generates section @var{output} at location
|
|
@code{0x40000000}:
|
|
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{
|
|
@dots{}
|
|
output 0x40000000: @{
|
|
@dots{}
|
|
@}
|
|
@dots{}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@kindex BLOCK(@var{align})
|
|
@cindex section alignment
|
|
@cindex aligning sections
|
|
@item BLOCK(@var{align})
|
|
You can include @code{BLOCK()} specification to advance
|
|
the location counter @code{.} prior to the beginning of the section, so
|
|
that the section will begin at the specified alignment. @var{align} is
|
|
an expression.
|
|
|
|
@kindex NOLOAD
|
|
@cindex prevent unnecessary loading
|
|
@cindex loading, preventing
|
|
@item (NOLOAD)
|
|
Use @samp{(NOLOAD)} to prevent a section from being loaded into memory
|
|
each time it is accessed. For example, in the script sample below, the
|
|
@code{ROM} segment is addressed at memory location @samp{0} and does not
|
|
need to be loaded into each object file:
|
|
|
|
@smallexample
|
|
@group
|
|
SECTIONS @{
|
|
ROM 0 (NOLOAD) : @{ @dots{} @}
|
|
@dots{}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@kindex AT ( @var{ldadr} )
|
|
@cindex specify load address
|
|
@cindex load address, specifying
|
|
@item AT ( @var{ldadr} )
|
|
The expression @var{ldadr} that follows the @code{AT} keyword specifies
|
|
the load address of the section. The default (if you do not use the
|
|
@code{AT} keyword) is to make the load address the same as the
|
|
relocation address. This feature is designed to make it easy to build a
|
|
ROM image. For example, this @code{SECTIONS} definition creates two
|
|
output sections: one called @samp{.text}, which starts at @code{0x1000},
|
|
and one called @samp{.mdata}, which is loaded at the end of the
|
|
@samp{.text} section even though its relocation address is
|
|
@code{0x2000}. The symbol @code{_data} is defined with the value
|
|
@code{0x2000}:
|
|
|
|
@smallexample
|
|
@group
|
|
SECTIONS
|
|
@{
|
|
.text 0x1000 : @{ *(.text) _etext = . ; @}
|
|
.mdata 0x2000 :
|
|
AT ( ADDR(.text) + SIZEOF ( .text ) )
|
|
@{ _data = . ; *(.data); _edata = . ; @}
|
|
.bss 0x3000 :
|
|
@{ _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;@}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
The run-time initialization code (for C programs, usually @code{crt0})
|
|
for use with a ROM generated this way has to include something like
|
|
the following, to copy the initialized data from the ROM image to its runtime
|
|
address:
|
|
|
|
@smallexample
|
|
@group
|
|
char *src = _etext;
|
|
char *dst = _data;
|
|
|
|
/* ROM has data at end of text; copy it. */
|
|
while (dst < _edata) @{
|
|
*dst++ = *src++;
|
|
@}
|
|
|
|
/* Zero bss */
|
|
for (dst = _bstart; dst< _bend; dst++)
|
|
*dst = 0;
|
|
@end group
|
|
@end smallexample
|
|
|
|
@kindex >@var{region}
|
|
@cindex section, assigning to memory region
|
|
@cindex memory regions and sections
|
|
@item >@var{region}
|
|
Assign this section to a previously defined region of memory.
|
|
@xref{MEMORY}.
|
|
|
|
@kindex :@var{phdr}
|
|
@cindex section, assigning to program header
|
|
@cindex program headers and sections
|
|
@item :@var{phdr}
|
|
Assign this section to a segment described by a program header.
|
|
@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}.
|
|
|
|
@kindex =@var{fill}
|
|
@cindex section fill pattern
|
|
@cindex fill pattern, entire section
|
|
@item =@var{fill}
|
|
Including @code{=@var{fill}} in a section definition specifies the
|
|
initial fill value for that section. You may use any expression to
|
|
specify @var{fill}. Any unallocated holes in the current output section
|
|
when written to the output file will be filled with the two least
|
|
significant bytes of the value, repeated as necessary. You can also
|
|
change the fill value with a @code{FILL} statement in the @var{contents}
|
|
of a section definition.
|
|
|
|
@end table
|
|
|
|
@node Overlays
|
|
@subsection Overlays
|
|
@kindex OVERLAY
|
|
@cindex overlays
|
|
|
|
The @code{OVERLAY} command provides an easy way to describe sections
|
|
which are to be loaded as part of a single memory image but are to be
|
|
run at the same memory address. At run time, some sort of overlay
|
|
manager will copy the overlaid sections in and out of the runtime memory
|
|
address as required, perhaps by simply manipulating addressing bits.
|
|
This approach can be useful, for example, when a certain region of
|
|
memory is faster than another.
|
|
|
|
The @code{OVERLAY} command is used within a @code{SECTIONS} command. It
|
|
appears as follows:
|
|
@smallexample
|
|
@group
|
|
OVERLAY @var{start} : [ NOCROSSREFS ] AT ( @var{ldaddr} )
|
|
@{
|
|
@var{secname1} @{ @var{contents} @} :@var{phdr} =@var{fill}
|
|
@var{secname2} @{ @var{contents} @} :@var{phdr} =@var{fill}
|
|
@dots{}
|
|
@} >@var{region} :@var{phdr} =@var{fill}
|
|
@end group
|
|
@end smallexample
|
|
|
|
Everything is optional except @code{OVERLAY} (a keyword), and each
|
|
section must have a name (@var{secname1} and @var{secname2} above). The
|
|
section definitions within the @code{OVERLAY} construct are identical to
|
|
those within the general @code{SECTIONS} contruct (@pxref{SECTIONS}),
|
|
except that no addresses and no memory regions may be defined for
|
|
sections within an @code{OVERLAY}.
|
|
|
|
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
|
|
whole (as with normal section definitions, the load address is optional,
|
|
and defaults to the start address; the start address is also optional,
|
|
and defaults to @code{.}).
|
|
|
|
If the @code{NOCROSSREFS} keyword is used, and there any references
|
|
among the sections, the linker will report an error. Since the sections
|
|
all run at the same address, it normally does not make sense for one
|
|
section to refer directly to another. @xref{Option Commands,
|
|
NOCROSSREFS}.
|
|
|
|
For each section within the @code{OVERLAY}, the linker automatically
|
|
defines two symbols. The symbol @code{__load_start_@var{secname}} is
|
|
defined as the starting load address of the section. The symbol
|
|
@code{__load_stop_@var{secname}} is defined as the final load address of
|
|
the section. Any characters within @var{secname} which are not legal
|
|
within C identifiers are removed. C (or assembler) code may use these
|
|
symbols to move the overlaid sections around as necessary.
|
|
|
|
At the end of the overlay, the value of @code{.} is set to the start
|
|
address of the overlay plus the size of the largest section.
|
|
|
|
Here is an example. Remember that this would appear inside a
|
|
@code{SECTIONS} construct.
|
|
|
|
@smallexample
|
|
@group
|
|
OVERLAY 0x1000 : AT (0x4000)
|
|
@{
|
|
.text0 @{ o1/*.o(.text) @}
|
|
.text1 @{ o2/*.o(.text) @}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
This will define both @code{.text0} and @code{.text1} to start at
|
|
address 0x1000. @code{.text0} will be loaded at address 0x4000, and
|
|
@code{.text1} will be loaded immediately after @code{.text0}. The
|
|
following symbols will be defined: @code{__load_start_text0},
|
|
@code{__load_stop_text0}, @code{__load_start_text1},
|
|
@code{__load_stop_text1}.
|
|
|
|
C code to copy overlay @code{.text1} into the overlay area might look
|
|
like the following.
|
|
|
|
@smallexample
|
|
@group
|
|
extern char __load_start_text1, __load_stop_text1;
|
|
memcpy ((char *) 0x1000, &__load_start_text1,
|
|
&__load_stop_text1 - &__load_start_text1);
|
|
@end group
|
|
@end smallexample
|
|
|
|
Note that the @code{OVERLAY} command is just syntactic sugar, since
|
|
everything it does can be done using the more basic commands. The above
|
|
example could have been written identically as follows.
|
|
|
|
@smallexample
|
|
@group
|
|
.text0 0x1000 : AT (0x4000) @{ o1/*.o(.text) @}
|
|
__load_start_text0 = LOADADDR (.text0);
|
|
__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0);
|
|
.text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) @{ o2/*.o(.text) @}
|
|
__load_start_text1 = LOADADDR (.text1);
|
|
__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1);
|
|
. = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node PHDRS
|
|
@section ELF Program Headers
|
|
@kindex PHDRS
|
|
@cindex program headers
|
|
@cindex ELF program headers
|
|
|
|
The ELF object file format uses @dfn{program headers}, which are read by
|
|
the system loader and describe how the program should be loaded into
|
|
memory. These program headers must be set correctly in order to run the
|
|
program on a native ELF system. The linker will create reasonable
|
|
program headers by default. However, in some cases, it is desirable to
|
|
specify the program headers more precisely; the @code{PHDRS} command may
|
|
be used for this purpose. When the @code{PHDRS} command is used, the
|
|
linker will not generate any program headers itself.
|
|
|
|
The @code{PHDRS} command is only meaningful when generating an ELF
|
|
output file. It is ignored in other cases. This manual does not
|
|
describe the details of how the system loader interprets program
|
|
headers; for more information, see the ELF ABI. The program headers of
|
|
an ELF file may be displayed using the @samp{-p} option of the
|
|
@code{objdump} command.
|
|
|
|
This is the syntax of the @code{PHDRS} command. The words @code{PHDRS},
|
|
@code{FILEHDR}, @code{AT}, and @code{FLAGS} are keywords.
|
|
|
|
@smallexample
|
|
@group
|
|
PHDRS
|
|
@{
|
|
@var{name} @var{type} [ FILEHDR ] [ PHDRS ] [ AT ( @var{address} ) ]
|
|
[ FLAGS ( @var{flags} ) ] ;
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
The @var{name} is used only for reference in the @code{SECTIONS} command
|
|
of the linker script. It does not get put into the output file.
|
|
|
|
Certain program header types describe segments of memory which are
|
|
loaded from the file by the system loader. In the linker script, the
|
|
contents of these segments are specified by directing allocated output
|
|
sections to be placed in the segment. To do this, the command
|
|
describing the output section in the @code{SECTIONS} command should use
|
|
@samp{:@var{name}}, where @var{name} is the name of the program header
|
|
as it appears in the @code{PHDRS} command. @xref{Section Options}.
|
|
|
|
It is normal for certain sections to appear in more than one segment.
|
|
This merely implies that one segment of memory contains another. This
|
|
is specified by repeating @samp{:@var{name}}, using it once for each
|
|
program header in which the section is to appear.
|
|
|
|
If a section is placed in one or more segments using @samp{:@var{name}},
|
|
then all subsequent allocated sections which do not specify
|
|
@samp{:@var{name}} are placed 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}.
|
|
|
|
The @code{FILEHDR} and @code{PHDRS} keywords which may appear after the
|
|
program header type also indicate contents of the segment of memory.
|
|
The @code{FILEHDR} keyword means that the segment should include the ELF
|
|
file header. The @code{PHDRS} keyword means that the segment should
|
|
include the ELF program headers themselves.
|
|
|
|
The @var{type} may be one of the following. The numbers indicate the
|
|
value of the keyword.
|
|
|
|
@table @asis
|
|
@item @code{PT_NULL} (0)
|
|
Indicates an unused program header.
|
|
|
|
@item @code{PT_LOAD} (1)
|
|
Indicates that this program header describes a segment to be loaded from
|
|
the file.
|
|
|
|
@item @code{PT_DYNAMIC} (2)
|
|
Indicates a segment where dynamic linking information can be found.
|
|
|
|
@item @code{PT_INTERP} (3)
|
|
Indicates a segment where the name of the program interpreter may be
|
|
found.
|
|
|
|
@item @code{PT_NOTE} (4)
|
|
Indicates a segment holding note information.
|
|
|
|
@item @code{PT_SHLIB} (5)
|
|
A reserved program header type, defined but not specified by the ELF
|
|
ABI.
|
|
|
|
@item @code{PT_PHDR} (6)
|
|
Indicates a segment where the program headers may be found.
|
|
|
|
@item @var{expression}
|
|
An expression giving the numeric type of the program header. This may
|
|
be used for types not defined above.
|
|
@end table
|
|
|
|
It is possible to specify that a segment should be loaded at a
|
|
particular address in memory. This is done using an @code{AT}
|
|
expression. This is identical to the @code{AT} command used in the
|
|
@code{SECTIONS} command (@pxref{Section Options}). Using the @code{AT}
|
|
command for a program header overrides any information in the
|
|
@code{SECTIONS} command.
|
|
|
|
Normally the segment flags are set based on the sections. The
|
|
@code{FLAGS} keyword may be used to explicitly specify the segment
|
|
flags. The value of @var{flags} must be an integer. It is used to
|
|
set the @code{p_flags} field of the program header.
|
|
|
|
Here is an example of the use of @code{PHDRS}. This shows a typical set
|
|
of program headers used on a native ELF system.
|
|
|
|
@example
|
|
@group
|
|
PHDRS
|
|
@{
|
|
headers PT_PHDR PHDRS ;
|
|
interp PT_INTERP ;
|
|
text PT_LOAD FILEHDR PHDRS ;
|
|
data PT_LOAD ;
|
|
dynamic PT_DYNAMIC ;
|
|
@}
|
|
|
|
SECTIONS
|
|
@{
|
|
. = SIZEOF_HEADERS;
|
|
.interp : @{ *(.interp) @} :text :interp
|
|
.text : @{ *(.text) @} :text
|
|
.rodata : @{ *(.rodata) @} /* defaults to :text */
|
|
@dots{}
|
|
. = . + 0x1000; /* move to a new page in memory */
|
|
.data : @{ *(.data) @} :data
|
|
.dynamic : @{ *(.dynamic) @} :data :dynamic
|
|
@dots{}
|
|
@}
|
|
@end group
|
|
@end example
|
|
|
|
@node Entry Point
|
|
@section The Entry Point
|
|
@kindex ENTRY(@var{symbol})
|
|
@cindex start of execution
|
|
@cindex first instruction
|
|
The linker command language includes a command specifically for
|
|
defining the first executable instruction in an output file (its
|
|
@dfn{entry point}). Its argument is a symbol name:
|
|
@smallexample
|
|
ENTRY(@var{symbol})
|
|
@end smallexample
|
|
|
|
Like symbol assignments, the @code{ENTRY} command may be placed either
|
|
as an independent command in the command file, or among the section
|
|
definitions within the @code{SECTIONS} command---whatever makes the most
|
|
sense for your layout.
|
|
|
|
@cindex entry point, defaults
|
|
@code{ENTRY} is only one of several ways of choosing the entry point.
|
|
You may indicate it in any of the following ways (shown in descending
|
|
order of priority: methods higher in the list override methods lower down).
|
|
@itemize @bullet
|
|
@item
|
|
the @samp{-e} @var{entry} command-line option;
|
|
@item
|
|
the @code{ENTRY(@var{symbol})} command in a linker control script;
|
|
@item
|
|
the value of the symbol @code{start}, if present;
|
|
@item
|
|
the address of the first byte of the @code{.text} section, if present;
|
|
@item
|
|
The address @code{0}.
|
|
@end itemize
|
|
|
|
For example, you can use these rules to generate an entry point with an
|
|
assignment statement: if no symbol @code{start} is defined within your
|
|
input files, you can simply define it, assigning it an appropriate
|
|
value---
|
|
|
|
@smallexample
|
|
start = 0x2020;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The example shows an absolute address, but you can use any expression.
|
|
For example, if your input object files use some other symbol-name
|
|
convention for the entry point, you can just assign the value of
|
|
whatever symbol contains the start address to @code{start}:
|
|
|
|
@smallexample
|
|
start = other_symbol ;
|
|
@end smallexample
|
|
|
|
@node Option Commands
|
|
@section Option Commands
|
|
The command language includes a number of other commands that you can
|
|
use for specialized purposes. They are similar in purpose to
|
|
command-line options.
|
|
|
|
@table @code
|
|
@kindex CONSTRUCTORS
|
|
@cindex C++ constructors, arranging in link
|
|
@cindex constructors, arranging in link
|
|
@item CONSTRUCTORS
|
|
When linking using the @code{a.out} object file format, the linker uses
|
|
an unusual set construct to support C++ global constructors and
|
|
destructors. When linking object file formats which do not support
|
|
arbitrary sections, such as @code{ECOFF} and @code{XCOFF}, the linker
|
|
will automatically recognize C++ global constructors and destructors by
|
|
name. For these object file formats, the @code{CONSTRUCTORS} command
|
|
tells the linker where this information should be placed. The
|
|
@code{CONSTRUCTORS} command is ignored for other object file formats.
|
|
|
|
The symbol @w{@code{__CTOR_LIST__}} marks the start of the global
|
|
constructors, and the symbol @w{@code{__DTOR_LIST}} marks the end. The
|
|
first word in the list is the number of entries, followed by the address
|
|
of each constructor or destructor, followed by a zero word. The
|
|
compiler must arrange to actually run the code. For these object file
|
|
formats @sc{gnu} C++ calls constructors from a subroutine @code{__main};
|
|
a call to @code{__main} is automatically inserted into the startup code
|
|
for @code{main}. @sc{gnu} C++ runs destructors either by using
|
|
@code{atexit}, or directly from the function @code{exit}.
|
|
|
|
For object file formats such as @code{COFF} or @code{ELF} which support
|
|
multiple sections, @sc{gnu} C++ will normally arrange to put the
|
|
addresses of global constructors and destructors into the @code{.ctors}
|
|
and @code{.dtors} sections. Placing the following sequence into your
|
|
linker script will build the sort of table which the @sc{gnu} C++
|
|
runtime code expects to see.
|
|
|
|
@smallexample
|
|
__CTOR_LIST__ = .;
|
|
LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
|
|
*(.ctors)
|
|
LONG(0)
|
|
__CTOR_END__ = .;
|
|
__DTOR_LIST__ = .;
|
|
LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
|
|
*(.dtors)
|
|
LONG(0)
|
|
__DTOR_END__ = .;
|
|
@end smallexample
|
|
|
|
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.
|
|
|
|
@need 1000
|
|
@kindex FLOAT
|
|
@kindex NOFLOAT
|
|
@item FLOAT
|
|
@itemx NOFLOAT
|
|
These keywords were used in some older linkers to request a particular
|
|
math subroutine library. @code{ld} doesn't use the keywords, assuming
|
|
instead that any necessary subroutines are in libraries specified using
|
|
the general mechanisms for linking to archives; but to permit the use of
|
|
scripts that were written for the older linkers, the keywords
|
|
@code{FLOAT} and @code{NOFLOAT} are accepted and ignored.
|
|
|
|
@kindex FORCE_COMMON_ALLOCATION
|
|
@cindex common allocation
|
|
@item FORCE_COMMON_ALLOCATION
|
|
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}).
|
|
|
|
@kindex INPUT ( @var{files} )
|
|
@cindex binary input files
|
|
@item INPUT ( @var{file}, @var{file}, @dots{} )
|
|
@itemx INPUT ( @var{file} @var{file} @dots{} )
|
|
Use this command to include binary input files in the link, without
|
|
including them in a particular section definition.
|
|
Specify the full name for each @var{file}, including @samp{.a} if
|
|
required.
|
|
|
|
@code{ld} searches for each @var{file} through the archive-library
|
|
search path, just as for files you specify on the command line.
|
|
See the description of @samp{-L} in @ref{Options,,Command Line
|
|
Options}.
|
|
|
|
If you use @samp{-l@var{file}}, @code{ld} will transform the name to
|
|
@code{lib@var{file}.a} as with the command line argument @samp{-l}.
|
|
|
|
@kindex GROUP ( @var{files} )
|
|
@cindex grouping input files
|
|
@item GROUP ( @var{file}, @var{file}, @dots{} )
|
|
@itemx GROUP ( @var{file} @var{file} @dots{} )
|
|
This command is like @code{INPUT}, except that the named files should
|
|
all be archives, and they are searched repeatedly until no new undefined
|
|
references are created. See the description of @samp{-(} in
|
|
@ref{Options,,Command Line Options}.
|
|
|
|
@ignore
|
|
@kindex MAP ( @var{name} )
|
|
@item MAP ( @var{name} )
|
|
@c MAP(...) appears to look for an F in the arg, ignoring all other
|
|
@c chars; if it finds one, it sets "map_option_f" to true. But nothing
|
|
@c checks map_option_f. Apparently a stub for the future...
|
|
@end ignore
|
|
|
|
@kindex OUTPUT ( @var{filename} )
|
|
@cindex naming the output file
|
|
@item OUTPUT ( @var{filename} )
|
|
Use this command to name the link output file @var{filename}. The
|
|
effect of @code{OUTPUT(@var{filename})} is identical to the effect of
|
|
@w{@samp{-o @var{filename}}}, which overrides it. You can use this
|
|
command to supply a default output-file name other than @code{a.out}.
|
|
|
|
@ifclear SingleFormat
|
|
@kindex OUTPUT_ARCH ( @var{bfdname} )
|
|
@cindex machine architecture, output
|
|
@item OUTPUT_ARCH ( @var{bfdname} )
|
|
Specify a particular output machine architecture, with one of the names
|
|
used by the BFD back-end routines (@pxref{BFD}). This command is often
|
|
unnecessary; the architecture is most often set implicitly by either the
|
|
system BFD configuration or as a side effect of the @code{OUTPUT_FORMAT}
|
|
command.
|
|
|
|
@kindex OUTPUT_FORMAT ( @var{bfdname} )
|
|
@cindex format, output file
|
|
@item OUTPUT_FORMAT ( @var{bfdname} )
|
|
When @code{ld} is configured to support multiple object code formats,
|
|
you can use this command to specify a particular output format.
|
|
@var{bfdname} is one of the names used by the BFD back-end routines
|
|
(@pxref{BFD}). The effect is identical to the effect of the
|
|
@samp{--oformat} command-line option. This selection affects only the
|
|
output file; the related command @code{TARGET} affects primarily input
|
|
files.
|
|
@end ifclear
|
|
|
|
@kindex SEARCH_DIR ( @var{path} )
|
|
@cindex path for libraries
|
|
@cindex search path, libraries
|
|
@item SEARCH_DIR ( @var{path} )
|
|
Add @var{path} to the list of paths where @code{ld} looks for
|
|
archive libraries. @code{SEARCH_DIR(@var{path})} has the same
|
|
effect as @samp{-L@var{path}} on the command line.
|
|
|
|
@kindex STARTUP ( @var{filename} )
|
|
@cindex first input file
|
|
@item STARTUP ( @var{filename} )
|
|
Ensure that @var{filename} is the first input file used in the link
|
|
process.
|
|
|
|
@ifclear SingleFormat
|
|
@cindex input file format
|
|
@kindex TARGET ( @var{format} )
|
|
@item TARGET ( @var{format} )
|
|
When @code{ld} is configured to support multiple object code formats,
|
|
you can use this command to change the input-file object code format
|
|
(like the command-line option @samp{-b} or its synonym @samp{--format}).
|
|
The argument @var{format} is one of the strings used by BFD to name
|
|
binary formats. If @code{TARGET} is specified but @code{OUTPUT_FORMAT}
|
|
is not, the last @code{TARGET} argument is also used as the default
|
|
format for the @code{ld} output file. @xref{BFD}.
|
|
|
|
@kindex GNUTARGET
|
|
If you don't use the @code{TARGET} command, @code{ld} uses the value of
|
|
the environment variable @code{GNUTARGET}, if available, to select the
|
|
output file format. If that variable is also absent, @code{ld} uses
|
|
the default format configured for your machine in the BFD libraries.
|
|
@end ifclear
|
|
|
|
@cindex cross references
|
|
@kindex NOCROSSREFS ( @var{sections} )
|
|
@item NOCROSSREFS ( @var{section} @var{section} @dots{} )
|
|
This command may be used to tell @code{ld} to issue an error about any
|
|
references among certain sections.
|
|
|
|
In certain types of programs, particularly on embedded systems, when one
|
|
section is loaded into memory, another section will not be. Any direct
|
|
references between the two sections would be errors. For example, it
|
|
would be an error if code in one section called a function defined in
|
|
the other section.
|
|
|
|
The @code{NOCROSSREFS} command takes a list of section names. If
|
|
@code{ld} detects any cross references between the sections, it reports
|
|
an error and returns a non-zero exit status. The @code{NOCROSSREFS}
|
|
command uses output section names, defined in the @code{SECTIONS}
|
|
command. It does not use the names of input sections.
|
|
@end table
|
|
|
|
@ifset GENERIC
|
|
@node Machine Dependent
|
|
@chapter Machine Dependent Features
|
|
|
|
@cindex machine dependencies
|
|
@code{ld} has additional features on some platforms; the following
|
|
sections describe them. Machines where @code{ld} has no additional
|
|
functionality are not listed.
|
|
|
|
@menu
|
|
* H8/300:: @code{ld} and the H8/300
|
|
* i960:: @code{ld} and the Intel 960 family
|
|
@end menu
|
|
@end ifset
|
|
|
|
@c FIXME! This could use @raisesections/@lowersections, but there seems to be a conflict
|
|
@c between those and node-defaulting.
|
|
@ifset H8300
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
@node H8/300
|
|
@section @code{ld} and the H8/300
|
|
|
|
@cindex H8/300 support
|
|
For the H8/300, @code{ld} can perform these global optimizations when
|
|
you specify the @samp{--relax} command-line option.
|
|
|
|
@table @emph
|
|
@cindex relaxing on H8/300
|
|
@item relaxing address modes
|
|
@code{ld} finds all @code{jsr} and @code{jmp} instructions whose
|
|
targets are within eight bits, and turns them into eight-bit
|
|
program-counter relative @code{bsr} and @code{bra} instructions,
|
|
respectively.
|
|
|
|
@cindex synthesizing on H8/300
|
|
@item synthesizing instructions
|
|
@c FIXME: specifically mov.b, or any mov instructions really?
|
|
@code{ld} finds all @code{mov.b} instructions which use the
|
|
sixteen-bit absolute address form, but refer to the top
|
|
page of memory, and changes them to use the eight-bit address form.
|
|
(That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into
|
|
@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
|
|
@end ifset
|
|
|
|
@ifclear GENERIC
|
|
@ifset Hitachi
|
|
@c This stuff is pointless to say unless you're especially concerned
|
|
@c with Hitachi chips; don't enable it for generic case, please.
|
|
@node Hitachi
|
|
@chapter @code{ld} and other Hitachi chips
|
|
|
|
@code{ld} also supports the H8/300H, the H8/500, and the Hitachi SH. No
|
|
special features, commands, or command-line options are required for
|
|
these chips.
|
|
@end ifset
|
|
@end ifclear
|
|
|
|
@ifset I960
|
|
@ifclear GENERIC
|
|
@raisesections
|
|
@end ifclear
|
|
@node i960
|
|
@section @code{ld} and the Intel 960 family
|
|
|
|
@cindex i960 support
|
|
|
|
You can use the @samp{-A@var{architecture}} command line option to
|
|
specify one of the two-letter names identifying members of the 960
|
|
family; the option specifies the desired output target, and warns of any
|
|
incompatible instructions in the input files. It also modifies the
|
|
linker's search strategy for archive libraries, to support the use of
|
|
libraries specific to each particular architecture, by including in the
|
|
search loop names suffixed with the string identifying the architecture.
|
|
|
|
For example, if your @code{ld} command line included @w{@samp{-ACA}} as
|
|
well as @w{@samp{-ltry}}, the linker would look (in its built-in search
|
|
paths, and in any paths you specify with @samp{-L}) for a library with
|
|
the names
|
|
|
|
@smallexample
|
|
@group
|
|
try
|
|
libtry.a
|
|
tryca
|
|
libtryca.a
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The first two possibilities would be considered in any event; the last
|
|
two are due to the use of @w{@samp{-ACA}}.
|
|
|
|
You can meaningfully use @samp{-A} more than once on a command line, since
|
|
the 960 architecture family allows combination of target architectures; each
|
|
use will add another pair of name variants to search for when @w{@samp{-l}}
|
|
specifies a library.
|
|
|
|
@cindex @code{--relax} on i960
|
|
@cindex relaxing on i960
|
|
@code{ld} supports the @samp{--relax} option for the i960 family. If
|
|
you specify @samp{--relax}, @code{ld} finds all @code{balx} and
|
|
@code{calx} instructions whose targets are within 24 bits, and turns
|
|
them into 24-bit program-counter relative @code{bal} and @code{cal}
|
|
instructions, respectively. @code{ld} also turns @code{cal}
|
|
instructions into @code{bal} instructions when it determines that the
|
|
target subroutine is a leaf routine (that is, the target subroutine does
|
|
not itself call any subroutines).
|
|
|
|
@ifclear GENERIC
|
|
@lowersections
|
|
@end ifclear
|
|
@end ifset
|
|
|
|
@ifclear SingleFormat
|
|
@node BFD
|
|
@chapter BFD
|
|
|
|
@cindex back end
|
|
@cindex object file management
|
|
@cindex object formats available
|
|
@kindex objdump -i
|
|
The linker accesses object and archive files using the BFD libraries.
|
|
These libraries allow the linker to use the same routines to operate on
|
|
object files whatever the object file format. A different object file
|
|
format can be supported simply by creating a new BFD back end and adding
|
|
it to the library. To conserve runtime memory, however, the linker and
|
|
associated tools are usually configured to support only a subset of the
|
|
object file formats available. You can use @code{objdump -i}
|
|
(@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to
|
|
list all the formats available for your configuration.
|
|
|
|
@cindex BFD requirements
|
|
@cindex requirements for BFD
|
|
As with most implementations, BFD is a compromise between
|
|
several conflicting requirements. The major factor influencing
|
|
BFD design was efficiency: any time used converting between
|
|
formats is time which would not have been spent had BFD not
|
|
been involved. This is partly offset by abstraction payback; since
|
|
BFD simplifies applications and back ends, more time and care
|
|
may be spent optimizing algorithms for a greater speed.
|
|
|
|
One minor artifact of the BFD solution which you should bear in
|
|
mind is the potential for information loss. There are two places where
|
|
useful information can be lost using the BFD mechanism: during
|
|
conversion and during output. @xref{BFD information loss}.
|
|
|
|
@menu
|
|
* BFD outline:: How it works: an outline of BFD
|
|
@end menu
|
|
|
|
@node BFD outline
|
|
@section How it works: an outline of BFD
|
|
@cindex opening object files
|
|
@include bfdsumm.texi
|
|
@end ifclear
|
|
|
|
@node Reporting Bugs
|
|
@chapter Reporting Bugs
|
|
@cindex bugs in @code{ld}
|
|
@cindex reporting bugs in @code{ld}
|
|
|
|
Your bug reports play an essential role in making @code{ld} reliable.
|
|
|
|
Reporting a bug may help you by bringing a solution to your problem, or
|
|
it may not. But in any case the principal function of a bug report is
|
|
to help the entire community by making the next version of @code{ld}
|
|
work better. Bug reports are your contribution to the maintenance of
|
|
@code{ld}.
|
|
|
|
In order for a bug report to serve its purpose, you must include the
|
|
information that enables us to fix the bug.
|
|
|
|
@menu
|
|
* Bug Criteria:: Have you found a bug?
|
|
* Bug Reporting:: How to report bugs
|
|
@end menu
|
|
|
|
@node Bug Criteria
|
|
@section Have you found a bug?
|
|
@cindex bug criteria
|
|
|
|
If you are not sure whether you have found a bug, here are some guidelines:
|
|
|
|
@itemize @bullet
|
|
@cindex fatal signal
|
|
@cindex linker crash
|
|
@cindex crash of linker
|
|
@item
|
|
If the linker gets a fatal signal, for any input whatever, that is a
|
|
@code{ld} bug. Reliable linkers never crash.
|
|
|
|
@cindex error on valid input
|
|
@item
|
|
If @code{ld} produces an error message for valid input, that is a bug.
|
|
|
|
@cindex invalid input
|
|
@item
|
|
If @code{ld} does not produce an error message for invalid input, that
|
|
may be a bug. In the general case, the linker can not verify that
|
|
object files are correct.
|
|
|
|
@item
|
|
If you are an experienced user of linkers, your suggestions for
|
|
improvement of @code{ld} are welcome in any case.
|
|
@end itemize
|
|
|
|
@node Bug Reporting
|
|
@section How to report bugs
|
|
@cindex bug reports
|
|
@cindex @code{ld} bugs, reporting
|
|
|
|
A number of companies and individuals offer support for @sc{gnu}
|
|
products. If you obtained @code{ld} from a support organization, we
|
|
recommend you contact that organization first.
|
|
|
|
You can find contact information for many support companies and
|
|
individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
|
|
distribution.
|
|
|
|
In any event, we also recommend that you send bug reports for @code{ld}
|
|
to @samp{bug-gnu-utils@@prep.ai.mit.edu}.
|
|
|
|
The fundamental principle of reporting bugs usefully is this:
|
|
@strong{report all the facts}. If you are not sure whether to state a
|
|
fact or leave it out, state it!
|
|
|
|
Often people omit facts because they think they know what causes the
|
|
problem and assume that some details do not matter. Thus, you might
|
|
assume that the name of a symbol you use in an example does not matter.
|
|
Well, probably it does not, but one cannot be sure. Perhaps the bug is
|
|
a stray memory reference which happens to fetch from the location where
|
|
that name is stored in memory; perhaps, if the name were different, the
|
|
contents of that location would fool the linker into doing the right
|
|
thing despite the bug. Play it safe and give a specific, complete
|
|
example. That is the easiest thing for you to do, and the most helpful.
|
|
|
|
Keep in mind that the purpose of a bug report is to enable us to fix the bug if
|
|
it is new to us. Therefore, always write your bug reports on the assumption
|
|
that the bug has not been reported previously.
|
|
|
|
Sometimes people give a few sketchy facts and ask, ``Does this ring a
|
|
bell?'' Those bug reports are useless, and we urge everyone to
|
|
@emph{refuse to respond to them} except to chide the sender to report
|
|
bugs properly.
|
|
|
|
To enable us to fix the bug, you should include all these things:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The version of @code{ld}. @code{ld} announces it if you start it with
|
|
the @samp{--version} argument.
|
|
|
|
Without this, we will not know whether there is any point in looking for
|
|
the bug in the current version of @code{ld}.
|
|
|
|
@item
|
|
Any patches you may have applied to the @code{ld} source, including any
|
|
patches made to the @code{BFD} library.
|
|
|
|
@item
|
|
The type of machine you are using, and the operating system name and
|
|
version number.
|
|
|
|
@item
|
|
What compiler (and its version) was used to compile @code{ld}---e.g.
|
|
``@code{gcc-2.7}''.
|
|
|
|
@item
|
|
The command arguments you gave the linker to link your example and
|
|
observe the bug. To guarantee you will not omit something important,
|
|
list them all. A copy of the Makefile (or the output from make) is
|
|
sufficient.
|
|
|
|
If we were to try to guess the arguments, we would probably guess wrong
|
|
and then we might not encounter the bug.
|
|
|
|
@item
|
|
A complete input file, or set of input files, that will reproduce the
|
|
bug. It is generally most helpful to send the actual object files,
|
|
uuencoded if necessary to get them through the mail system. Making them
|
|
available for anonymous FTP is not as good, but may be the only
|
|
reasonable choice for large object files.
|
|
|
|
If the source files were assembled using @code{gas} or compiled using
|
|
@code{gcc}, then it may be OK to send the source files rather than the
|
|
object files. In this case, be sure to say exactly what version of
|
|
@code{gas} or @code{gcc} was used to produce the object files. Also say
|
|
how @code{gas} or @code{gcc} were configured.
|
|
|
|
@item
|
|
A description of what behavior you observe that you believe is
|
|
incorrect. For example, ``It gets a fatal signal.''
|
|
|
|
Of course, if the bug is that @code{ld} gets a fatal signal, then we
|
|
will certainly notice it. But if the bug is incorrect output, we might
|
|
not notice unless it is glaringly wrong. You might as well not give us
|
|
a chance to make a mistake.
|
|
|
|
Even if the problem you experience is a fatal signal, you should still
|
|
say so explicitly. Suppose something strange is going on, such as, your
|
|
copy of @code{ld} is out of synch, or you have encountered a bug in the
|
|
C library on your system. (This has happened!) Your copy might crash
|
|
and ours would not. If you told us to expect a crash, then when ours
|
|
fails to crash, we would know that the bug was not happening for us. If
|
|
you had not told us to expect a crash, then we would not be able to draw
|
|
any conclusion from our observations.
|
|
|
|
@item
|
|
If you wish to suggest changes to the @code{ld} source, send us context
|
|
diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or
|
|
@samp{-p} option. Always send diffs from the old file to the new file.
|
|
If you even discuss something in the @code{ld} source, refer to it by
|
|
context, not by line number.
|
|
|
|
The line numbers in our development sources will not match those in your
|
|
sources. Your line numbers would convey no useful information to us.
|
|
@end itemize
|
|
|
|
Here are some things that are not necessary:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
A description of the envelope of the bug.
|
|
|
|
Often people who encounter a bug spend a lot of time investigating
|
|
which changes to the input file will make the bug go away and which
|
|
changes will not affect it.
|
|
|
|
This is often time consuming and not very useful, because the way we
|
|
will find the bug is by running a single example under the debugger
|
|
with breakpoints, not by pure deduction from a series of examples.
|
|
We recommend that you save your time for something else.
|
|
|
|
Of course, if you can find a simpler example to report @emph{instead}
|
|
of the original one, that is a convenience for us. Errors in the
|
|
output will be easier to spot, running under the debugger will take
|
|
less time, and so on.
|
|
|
|
However, simplification is not vital; if you do not want to do this,
|
|
report the bug anyway and send us the entire test case you used.
|
|
|
|
@item
|
|
A patch for the bug.
|
|
|
|
A patch for the bug does help us if it is a good one. But do not omit
|
|
the necessary information, such as the test case, on the assumption that
|
|
a patch is all we need. We might see problems with your patch and decide
|
|
to fix the problem another way, or we might not understand it at all.
|
|
|
|
Sometimes with a program as complicated as @code{ld} it is very hard to
|
|
construct an example that will make the program follow a certain path
|
|
through the code. If you do not send us the example, we will not be
|
|
able to construct one, so we will not be able to verify that the bug is
|
|
fixed.
|
|
|
|
And if we cannot understand what bug you are trying to fix, or why your
|
|
patch should be an improvement, we will not install it. A test case will
|
|
help us to understand.
|
|
|
|
@item
|
|
A guess about what the bug is or what it depends on.
|
|
|
|
Such guesses are usually wrong. Even we cannot guess right about such
|
|
things without first using the debugger to find the facts.
|
|
@end itemize
|
|
|
|
@node MRI
|
|
@appendix MRI Compatible Script Files
|
|
@cindex MRI compatibility
|
|
To aid users making the transition to @sc{gnu} @code{ld} from the MRI
|
|
linker, @code{ld} can use MRI compatible linker scripts as an
|
|
alternative to the more general-purpose linker scripting language
|
|
described in @ref{Commands,,Command Language}. MRI compatible linker
|
|
scripts have a much simpler command set than the scripting language
|
|
otherwise used with @code{ld}. @sc{gnu} @code{ld} supports the most
|
|
commonly used MRI linker commands; these commands are described here.
|
|
|
|
In general, MRI scripts aren't of much use with the @code{a.out} object
|
|
file format, since it only has three sections and MRI scripts lack some
|
|
features to make use of them.
|
|
|
|
You can specify a file containing an MRI-compatible script using the
|
|
@samp{-c} command-line option.
|
|
|
|
Each command in an MRI-compatible script occupies its own line; each
|
|
command line starts with the keyword that identifies the command (though
|
|
blank lines are also allowed for punctuation). If a line of an
|
|
MRI-compatible script begins with an unrecognized keyword, @code{ld}
|
|
issues a warning message, but continues processing the script.
|
|
|
|
Lines beginning with @samp{*} are comments.
|
|
|
|
You can write these commands using all upper-case letters, or all
|
|
lower case; for example, @samp{chip} is the same as @samp{CHIP}.
|
|
The following list shows only the upper-case form of each command.
|
|
|
|
@table @code
|
|
@cindex @code{ABSOLUTE} (MRI)
|
|
@item ABSOLUTE @var{secname}
|
|
@itemx ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname}
|
|
Normally, @code{ld} includes in the output file all sections from all
|
|
the input files. However, in an MRI-compatible script, you can use the
|
|
@code{ABSOLUTE} command to restrict the sections that will be present in
|
|
your output program. If the @code{ABSOLUTE} command is used at all in a
|
|
script, then only the sections named explicitly in @code{ABSOLUTE}
|
|
commands will appear in the linker output. You can still use other
|
|
input sections (whatever you select on the command line, or using
|
|
@code{LOAD}) to resolve addresses in the output file.
|
|
|
|
@cindex @code{ALIAS} (MRI)
|
|
@item ALIAS @var{out-secname}, @var{in-secname}
|
|
Use this command to place the data from input section @var{in-secname}
|
|
in a section called @var{out-secname} in the linker output file.
|
|
|
|
@var{in-secname} may be an integer.
|
|
|
|
@cindex @code{ALIGN} (MRI)
|
|
@item ALIGN @var{secname} = @var{expression}
|
|
Align the section called @var{secname} to @var{expression}. The
|
|
@var{expression} should be a power of two.
|
|
|
|
@cindex @code{BASE} (MRI)
|
|
@item BASE @var{expression}
|
|
Use the value of @var{expression} as the lowest address (other than
|
|
absolute addresses) in the output file.
|
|
|
|
@cindex @code{CHIP} (MRI)
|
|
@item CHIP @var{expression}
|
|
@itemx CHIP @var{expression}, @var{expression}
|
|
This command does nothing; it is accepted only for compatibility.
|
|
|
|
@cindex @code{END} (MRI)
|
|
@item END
|
|
This command does nothing whatever; it's only accepted for compatibility.
|
|
|
|
@cindex @code{FORMAT} (MRI)
|
|
@item FORMAT @var{output-format}
|
|
Similar to the @code{OUTPUT_FORMAT} command in the more general linker
|
|
language, but restricted to one of these output formats:
|
|
|
|
@enumerate
|
|
@item
|
|
S-records, if @var{output-format} is @samp{S}
|
|
|
|
@item
|
|
IEEE, if @var{output-format} is @samp{IEEE}
|
|
|
|
@item
|
|
COFF (the @samp{coff-m68k} variant in BFD), if @var{output-format} is
|
|
@samp{COFF}
|
|
@end enumerate
|
|
|
|
@cindex @code{LIST} (MRI)
|
|
@item LIST @var{anything}@dots{}
|
|
Print (to the standard output file) a link map, as produced by the
|
|
@code{ld} command-line option @samp{-M}.
|
|
|
|
The keyword @code{LIST} may be followed by anything on the
|
|
same line, with no change in its effect.
|
|
|
|
@cindex @code{LOAD} (MRI)
|
|
@item LOAD @var{filename}
|
|
@itemx LOAD @var{filename}, @var{filename}, @dots{} @var{filename}
|
|
Include one or more object file @var{filename} in the link; this has the
|
|
same effect as specifying @var{filename} directly on the @code{ld}
|
|
command line.
|
|
|
|
@cindex @code{NAME} (MRI)
|
|
@item NAME @var{output-name}
|
|
@var{output-name} is the name for the program produced by @code{ld}; the
|
|
MRI-compatible command @code{NAME} is equivalent to the command-line
|
|
option @samp{-o} or the general script language command @code{OUTPUT}.
|
|
|
|
@cindex @code{ORDER} (MRI)
|
|
@item ORDER @var{secname}, @var{secname}, @dots{} @var{secname}
|
|
@itemx ORDER @var{secname} @var{secname} @var{secname}
|
|
Normally, @code{ld} orders the sections in its output file in the
|
|
order in which they first appear in the input files. In an MRI-compatible
|
|
script, you can override this ordering with the @code{ORDER} command. The
|
|
sections you list with @code{ORDER} will appear first in your output
|
|
file, in the order specified.
|
|
|
|
@cindex @code{PUBLIC} (MRI)
|
|
@item PUBLIC @var{name}=@var{expression}
|
|
@itemx PUBLIC @var{name},@var{expression}
|
|
@itemx PUBLIC @var{name} @var{expression}
|
|
Supply a value (@var{expression}) for external symbol
|
|
@var{name} used in the linker input files.
|
|
|
|
@cindex @code{SECT} (MRI)
|
|
@item SECT @var{secname}, @var{expression}
|
|
@itemx SECT @var{secname}=@var{expression}
|
|
@itemx SECT @var{secname} @var{expression}
|
|
You can use any of these three forms of the @code{SECT} command to
|
|
specify the start address (@var{expression}) for section @var{secname}.
|
|
If you have more than one @code{SECT} statement for the same
|
|
@var{secname}, only the @emph{first} sets the start address.
|
|
@end table
|
|
|
|
@node Index
|
|
@unnumbered Index
|
|
|
|
@printindex cp
|
|
|
|
@tex
|
|
% I think something like @colophon should be in texinfo. In the
|
|
% meantime:
|
|
\long\def\colophon{\hbox to0pt{}\vfill
|
|
\centerline{The body of this manual is set in}
|
|
\centerline{\fontname\tenrm,}
|
|
\centerline{with headings in {\bf\fontname\tenbf}}
|
|
\centerline{and examples in {\tt\fontname\tentt}.}
|
|
\centerline{{\it\fontname\tenit\/} and}
|
|
\centerline{{\sl\fontname\tensl\/}}
|
|
\centerline{are used for emphasis.}\vfill}
|
|
\page\colophon
|
|
% Blame: doc@cygnus.com, 28mar91.
|
|
@end tex
|
|
|
|
|
|
@contents
|
|
@bye
|
|
|
|
|