1142 lines
49 KiB
Plaintext
1142 lines
49 KiB
Plaintext
This is ld.info, produced by makeinfo version 4.0 from ./ld.texinfo.
|
||
|
||
START-INFO-DIR-ENTRY
|
||
* Ld: (ld). The GNU linker.
|
||
END-INFO-DIR-ENTRY
|
||
|
||
This file documents the GNU linker LD version 2.10.
|
||
|
||
Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 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.
|
||
|
||
|
||
File: ld.info, Node: Top, Next: Overview, Up: (dir)
|
||
|
||
Using ld
|
||
********
|
||
|
||
This file documents the GNU linker ld version 2.10.
|
||
|
||
* Menu:
|
||
|
||
* Overview:: Overview
|
||
* Invocation:: Invocation
|
||
* Scripts:: Linker Scripts
|
||
|
||
* Machine Dependent:: Machine Dependent Features
|
||
|
||
* BFD:: BFD
|
||
|
||
* Reporting Bugs:: Reporting Bugs
|
||
* MRI:: MRI Compatible Script Files
|
||
* Index:: Index
|
||
|
||
|
||
File: ld.info, Node: Overview, Next: Invocation, Prev: Top, Up: Top
|
||
|
||
Overview
|
||
********
|
||
|
||
`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 `ld'.
|
||
|
||
`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.
|
||
|
||
This version of `ld' uses the general purpose BFD libraries to
|
||
operate on object files. This allows `ld' to read, combine, and write
|
||
object files in many different formats--for example, COFF or `a.out'.
|
||
Different formats may be linked together to produce any available kind
|
||
of object file. *Note BFD::, for more information.
|
||
|
||
Aside from its flexibility, the GNU linker is more helpful than other
|
||
linkers in providing diagnostic information. Many linkers abandon
|
||
execution immediately upon encountering an error; whenever possible,
|
||
`ld' continues executing, allowing you to identify other errors (or, in
|
||
some cases, to get an output file in spite of the error).
|
||
|
||
|
||
File: ld.info, Node: Invocation, Next: Scripts, Prev: Overview, Up: Top
|
||
|
||
Invocation
|
||
**********
|
||
|
||
The GNU linker `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.
|
||
|
||
* Menu:
|
||
|
||
* Options:: Command Line Options
|
||
* Environment:: Environment Variables
|
||
|
||
|
||
File: ld.info, Node: Options, Next: Environment, Up: Invocation
|
||
|
||
Command Line Options
|
||
====================
|
||
|
||
The linker supports a plethora of command-line options, but in actual
|
||
practice few of them are used in any particular context. For instance,
|
||
a frequent use of `ld' is to link standard Unix object files on a
|
||
standard, supported Unix system. On such a system, to link a file
|
||
`hello.o':
|
||
|
||
ld -o OUTPUT /lib/crt0.o hello.o -lc
|
||
|
||
This tells `ld' to produce a file called OUTPUT as the result of
|
||
linking the file `/lib/crt0.o' with `hello.o' and the library `libc.a',
|
||
which will come from the standard search directories. (See the
|
||
discussion of the `-l' option below.)
|
||
|
||
Some of the command-line options to `ld' may be specified at any
|
||
point in the command line. However, options which refer to files, such
|
||
as `-l' or `-T', cause the file to be read at the point at which the
|
||
option appears in the command line, relative to the object files and
|
||
other file options. Repeating non-file 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.
|
||
|
||
Non-option arguments are object files or archives 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 `-l', `-R', and the
|
||
script command language. If _no_ binary input files at all are
|
||
specified, the linker does not produce any output, and issues the
|
||
message `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 `-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
|
||
`INPUT' or `GROUP' to load other objects. Note that specifying a
|
||
script in this way should only be used to augment the main linker
|
||
script; if you want to use some command that logically can only appear
|
||
once, such as the `SECTIONS' or `MEMORY' command, you must replace the
|
||
default linker script using the `-T' option. *Note Scripts::.
|
||
|
||
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, `--oformat' and `--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, `--oformat srec' and `--oformat=srec' are equivalent.
|
||
Unique abbreviations of the names of multiple-letter options are
|
||
accepted.
|
||
|
||
Note - if the linker is being invoked indirectly, via a compiler
|
||
driver (eg `gcc') then all the linker command line options should be
|
||
prefixed by `-Wl,' (or whatever is appropriate for the particular
|
||
compiler driver) like this:
|
||
|
||
gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
|
||
|
||
This is important, because otherwise the compiler driver program may
|
||
silently drop the linker options, resulting in a bad link.
|
||
|
||
Here is a table of the generic command line switches accepted by the
|
||
GNU linker:
|
||
|
||
`-aKEYWORD'
|
||
This option is supported for HP/UX compatibility. The KEYWORD
|
||
argument must be one of the strings `archive', `shared', or
|
||
`default'. `-aarchive' is functionally equivalent to `-Bstatic',
|
||
and the other two keywords are functionally equivalent to
|
||
`-Bdynamic'. This option may be used any number of times.
|
||
|
||
`-AARCHITECTURE'
|
||
`--architecture=ARCHITECTURE'
|
||
In the current release of `ld', this option is useful only for the
|
||
Intel 960 family of architectures. In that `ld' configuration, the
|
||
ARCHITECTURE argument identifies the particular architecture in
|
||
the 960 family, enabling some safeguards and modifying the
|
||
archive-library search path. *Note `ld' and the Intel 960 family:
|
||
i960, for details.
|
||
|
||
Future releases of `ld' may support similar functionality for
|
||
other architecture families.
|
||
|
||
`-b INPUT-FORMAT'
|
||
`--format=INPUT-FORMAT'
|
||
`ld' may be configured to support more than one kind of object
|
||
file. If your `ld' is configured this way, you can use the `-b'
|
||
option to specify the binary format for input object files that
|
||
follow this option on the command line. Even when `ld' is
|
||
configured to support alternative object formats, you don't
|
||
usually need to specify this, as `ld' should be configured to
|
||
expect as a default input format the most usual format on each
|
||
machine. 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 `objdump -i'.) *Note BFD::.
|
||
|
||
You may want to use this option if you are linking files with an
|
||
unusual binary format. You can also use `-b' to switch formats
|
||
explicitly (when linking object files of different formats), by
|
||
including `-b INPUT-FORMAT' before each group of object files in a
|
||
particular format.
|
||
|
||
The default format is taken from the environment variable
|
||
`GNUTARGET'. *Note Environment::. You can also define the input
|
||
format from a script, using the command `TARGET'; see *Note Format
|
||
Commands::.
|
||
|
||
`-c MRI-COMMANDFILE'
|
||
`--mri-script=MRI-COMMANDFILE'
|
||
For compatibility with linkers produced by MRI, `ld' accepts script
|
||
files written in an alternate, restricted command language,
|
||
described in *Note MRI Compatible Script Files: MRI. Introduce
|
||
MRI script files with the option `-c'; use the `-T' option to run
|
||
linker scripts written in the general-purpose `ld' scripting
|
||
language. If MRI-CMDFILE does not exist, `ld' looks for it in the
|
||
directories specified by any `-L' options.
|
||
|
||
`-d'
|
||
`-dc'
|
||
`-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
|
||
`-r'). The script command `FORCE_COMMON_ALLOCATION' has the same
|
||
effect. *Note Miscellaneous Commands::.
|
||
|
||
`-e ENTRY'
|
||
`--entry=ENTRY'
|
||
Use ENTRY as the explicit symbol for beginning execution of your
|
||
program, rather than the default entry point. If there is no
|
||
symbol named ENTRY, the linker will try to parse ENTRY as a number,
|
||
and use that as the entry address (the number will be interpreted
|
||
in base 10; you may use a leading `0x' for base 16, or a leading
|
||
`0' for base 8). *Note Entry Point::, for a discussion of defaults
|
||
and other ways of specifying the entry point.
|
||
|
||
`-E'
|
||
`--export-dynamic'
|
||
When creating a dynamically linked executable, add all symbols to
|
||
the dynamic symbol table. The dynamic symbol table is the set of
|
||
symbols which are visible from dynamic objects at run time.
|
||
|
||
If you do not use this option, the dynamic symbol table will
|
||
normally contain only those symbols which are referenced by some
|
||
dynamic object mentioned in the link.
|
||
|
||
If you use `dlopen' to load a dynamic object which needs to refer
|
||
back to the symbols defined by the program, rather than some other
|
||
dynamic object, then you will probably need to use this option when
|
||
linking the program itself.
|
||
|
||
`-EB'
|
||
Link big-endian objects. This affects the default output format.
|
||
|
||
`-EL'
|
||
Link little-endian objects. This affects the default output
|
||
format.
|
||
|
||
`-f'
|
||
`--auxiliary 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 NAME.
|
||
|
||
If you later link a program against this filter object, then, when
|
||
you run the program, the dynamic linker will see the DT_AUXILIARY
|
||
field. If the dynamic linker resolves any symbols from the filter
|
||
object, it will first check whether there is a definition in the
|
||
shared object NAME. If there is one, it will be used instead of
|
||
the definition in the filter object. The shared object NAME need
|
||
not exist. Thus the shared object NAME may be used to provide an
|
||
alternative implementation of certain functions, perhaps for
|
||
debugging or for machine specific performance.
|
||
|
||
This option may be specified more than once. The DT_AUXILIARY
|
||
entries will be created in the order in which they appear on the
|
||
command line.
|
||
|
||
`-F NAME'
|
||
`--filter 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 which is being created
|
||
should be used as a filter on the symbol table of the shared
|
||
object NAME.
|
||
|
||
If you later link a program against this filter object, then, when
|
||
you run the program, the dynamic linker will see the DT_FILTER
|
||
field. The dynamic linker will resolve symbols according to the
|
||
symbol table of the filter object as usual, but it will actually
|
||
link to the definitions found in the shared object NAME. Thus the
|
||
filter object can be used to select a subset of the symbols
|
||
provided by the object NAME.
|
||
|
||
Some older linkers used the `-F' option throughout a compilation
|
||
toolchain for specifying object-file format for both input and
|
||
output object files. The GNU linker uses other mechanisms for this
|
||
purpose: the `-b', `--format', `--oformat' options, the `TARGET'
|
||
command in linker scripts, and the `GNUTARGET' environment
|
||
variable. The GNU linker will ignore the `-F' option when not
|
||
creating an ELF shared object.
|
||
|
||
`-fini NAME'
|
||
When creating an ELF executable or shared object, call NAME when
|
||
the executable or shared object is unloaded, by setting DT_FINI to
|
||
the address of the function. By default, the linker uses `_fini'
|
||
as the function to call.
|
||
|
||
`-g'
|
||
Ignored. Provided for compatibility with other tools.
|
||
|
||
`-GVALUE'
|
||
`--gpsize=VALUE'
|
||
Set the maximum size of objects to be optimized using the GP
|
||
register to 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.
|
||
|
||
`-hNAME'
|
||
`-soname=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.
|
||
|
||
`-i'
|
||
Perform an incremental link (same as option `-r').
|
||
|
||
`-init NAME'
|
||
When creating an ELF executable or shared object, call NAME when
|
||
the executable or shared object is loaded, by setting DT_INIT to
|
||
the address of the function. By default, the linker uses `_init'
|
||
as the function to call.
|
||
|
||
`-lARCHIVE'
|
||
`--library=ARCHIVE'
|
||
Add archive file ARCHIVE to the list of files to link. This
|
||
option may be used any number of times. `ld' will search its
|
||
path-list for occurrences of `libARCHIVE.a' for every ARCHIVE
|
||
specified.
|
||
|
||
On systems which support shared libraries, `ld' may also search for
|
||
libraries with extensions other than `.a'. Specifically, on ELF
|
||
and SunOS systems, `ld' will search a directory for a library with
|
||
an extension of `.so' before searching for one with an extension of
|
||
`.a'. By convention, a `.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 `-(' 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.
|
||
|
||
This type of archive searching is standard for Unix linkers.
|
||
However, if you are using `ld' on AIX, note that it is different
|
||
from the behaviour of the AIX linker.
|
||
|
||
`-LSEARCHDIR'
|
||
`--library-path=SEARCHDIR'
|
||
Add path SEARCHDIR to the list of paths that `ld' will search for
|
||
archive libraries and `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 `-L' options apply to all `-l' options,
|
||
regardless of the order in which the options appear.
|
||
|
||
The default set of paths searched (without being specified with
|
||
`-L') depends on which emulation mode `ld' is using, and in some
|
||
cases also on how it was configured. *Note Environment::.
|
||
|
||
The paths can also be specified in a link script with the
|
||
`SEARCH_DIR' command. Directories specified this way are searched
|
||
at the point in which the linker script appears in the command
|
||
line.
|
||
|
||
`-mEMULATION'
|
||
Emulate the EMULATION linker. You can list the available
|
||
emulations with the `--verbose' or `-V' options.
|
||
|
||
If the `-m' option is not used, the emulation is taken from the
|
||
`LDEMULATION' environment variable, if that is defined.
|
||
|
||
Otherwise, the default emulation depends upon how the linker was
|
||
configured.
|
||
|
||
`-M'
|
||
`--print-map'
|
||
Print a link map to the standard output. A link map provides
|
||
information about the link, including the following:
|
||
|
||
* Where object files and symbols are mapped into memory.
|
||
|
||
* How common symbols are allocated.
|
||
|
||
* All archive members included in the link, with a mention of
|
||
the symbol which caused the archive member to be brought in.
|
||
|
||
`-n'
|
||
`--nmagic'
|
||
Turn off page alignment of sections, and mark the output as
|
||
`NMAGIC' if possible.
|
||
|
||
`-N'
|
||
`--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 `OMAGIC'.
|
||
|
||
`-o OUTPUT'
|
||
`--output=OUTPUT'
|
||
Use OUTPUT as the name for the program produced by `ld'; if this
|
||
option is not specified, the name `a.out' is used by default. The
|
||
script command `OUTPUT' can also specify the output file name.
|
||
|
||
`-O LEVEL'
|
||
If LEVEL is a numeric values greater than zero `ld' optimizes the
|
||
output. This might take significantly longer and therefore
|
||
probably should only be enabled for the final binary.
|
||
|
||
`-r'
|
||
`--relocateable'
|
||
Generate relocatable output--i.e., generate an output file that
|
||
can in turn serve as input to `ld'. This is often called "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 `OMAGIC'. If this option is not specified, an absolute
|
||
file is produced. When linking C++ programs, this option _will
|
||
not_ resolve references to constructors; to do that, use `-Ur'.
|
||
|
||
This option does the same thing as `-i'.
|
||
|
||
`-R FILENAME'
|
||
`--just-symbols=FILENAME'
|
||
Read symbol names and their addresses from 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 `-R' option is
|
||
followed by a directory name, rather than a file name, it is
|
||
treated as the `-rpath' option.
|
||
|
||
`-s'
|
||
`--strip-all'
|
||
Omit all symbol information from the output file.
|
||
|
||
`-S'
|
||
`--strip-debug'
|
||
Omit debugger symbol information (but not all symbols) from the
|
||
output file.
|
||
|
||
`-t'
|
||
`--trace'
|
||
Print the names of the input files as `ld' processes them.
|
||
|
||
`-T SCRIPTFILE'
|
||
`--script=SCRIPTFILE'
|
||
Use SCRIPTFILE as the linker script. This script replaces `ld''s
|
||
default linker script (rather than adding to it), so COMMANDFILE
|
||
must specify everything necessary to describe the output file.
|
||
You must use this option if you want to use a command which can
|
||
only appear once in a linker script, such as the `SECTIONS' or
|
||
`MEMORY' command. *Note Scripts::. If SCRIPTFILE does not exist
|
||
in the current directory, `ld' looks for it in the directories
|
||
specified by any preceding `-L' options. Multiple `-T' options
|
||
accumulate.
|
||
|
||
`-u SYMBOL'
|
||
`--undefined=SYMBOL'
|
||
Force 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. `-u' may be repeated with
|
||
different option arguments to enter additional undefined symbols.
|
||
This option is equivalent to the `EXTERN' linker script command.
|
||
|
||
`-Ur'
|
||
For anything other than C++ programs, this option is equivalent to
|
||
`-r': it generates relocatable output--i.e., an output file that
|
||
can in turn serve as input to `ld'. When linking C++ programs,
|
||
`-Ur' _does_ resolve references to constructors, unlike `-r'. It
|
||
does not work to use `-Ur' on files that were themselves linked
|
||
with `-Ur'; once the constructor table has been built, it cannot
|
||
be added to. Use `-Ur' only for the last partial link, and `-r'
|
||
for the others.
|
||
|
||
`-v'
|
||
`--version'
|
||
`-V'
|
||
Display the version number for `ld'. The `-V' option also lists
|
||
the supported emulations.
|
||
|
||
`-x'
|
||
`--discard-all'
|
||
Delete all local symbols.
|
||
|
||
`-X'
|
||
`--discard-locals'
|
||
Delete all temporary local symbols. For most targets, this is all
|
||
local symbols whose names begin with `L'.
|
||
|
||
`-y SYMBOL'
|
||
`--trace-symbol=SYMBOL'
|
||
Print the name of each linked file in which 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.
|
||
|
||
`-Y PATH'
|
||
Add PATH to the default library search path. This option exists
|
||
for Solaris compatibility.
|
||
|
||
`-z KEYWORD'
|
||
This option is ignored for Solaris compatibility.
|
||
|
||
`-( ARCHIVES -)'
|
||
`--start-group ARCHIVES --end-group'
|
||
The ARCHIVES should be a list of archive files. They may be
|
||
either explicit file names, or `-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.
|
||
|
||
`-assert KEYWORD'
|
||
This option is ignored for SunOS compatibility.
|
||
|
||
`-Bdynamic'
|
||
`-dy'
|
||
`-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 `-l' options which follow it.
|
||
|
||
`-Bstatic'
|
||
`-dn'
|
||
`-non_shared'
|
||
`-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 `-l' options which follow
|
||
it.
|
||
|
||
`-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.
|
||
|
||
`--check-sections'
|
||
`--no-check-sections'
|
||
Asks the linker _not_ to check section addresses after they have
|
||
been assigned to see if there any overlaps. Normally the linker
|
||
will perform this check, and if it finds any overlaps it will
|
||
produce suitable error messages. The linker does know about, and
|
||
does make allowances for sections in overlays. The default
|
||
behaviour can be restored by using the command line switch
|
||
`--check-sections'.
|
||
|
||
`--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.
|
||
|
||
`--defsym SYMBOL=EXPRESSION'
|
||
Create a global symbol in the output file, containing the absolute
|
||
address given by 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 EXPRESSION in
|
||
this context: you may give a hexadecimal constant or the name of
|
||
an existing symbol, or use `+' and `-' to add or subtract
|
||
hexadecimal constants or symbols. If you need more elaborate
|
||
expressions, consider using the linker command language from a
|
||
script (*note Assignment: Symbol Definitions: Assignments.).
|
||
_Note:_ there should be no white space between SYMBOL, the equals
|
||
sign ("<=>"), and EXPRESSION.
|
||
|
||
`--demangle'
|
||
`--no-demangle'
|
||
These options control whether to demangle symbol names in error
|
||
messages and other output. When the linker is told to demangle,
|
||
it tries to present symbol names in a readable fashion: it strips
|
||
leading underscores if they are used by the object file format,
|
||
and converts C++ mangled symbol names into user readable names.
|
||
The linker will demangle by default unless the environment
|
||
variable `COLLECT_NO_DEMANGLE' is set. These options may be used
|
||
to override the default.
|
||
|
||
`--dynamic-linker 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.
|
||
|
||
`--embedded-relocs'
|
||
This option is only meaningful when linking MIPS embedded PIC code,
|
||
generated by the -membedded-pic option to the 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.
|
||
|
||
`--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
|
||
`.exe' or `.dll' suffix, this option forces the linker to copy the
|
||
output file to one of the same name with a `.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 `.exe' suffix.
|
||
|
||
`--no-gc-sections'
|
||
`--gc-sections'
|
||
Enable garbage collection of unused input sections. It is ignored
|
||
on targets that do not support this option. This option is not
|
||
compatible with `-r', nor should it be used with dynamic linking.
|
||
The default behaviour (of not performing this garbage collection)
|
||
can be restored by specifying `--no-gc-sections' on the command
|
||
line.
|
||
|
||
`--help'
|
||
Print a summary of the command-line options on the standard output
|
||
and exit.
|
||
|
||
`-Map MAPFILE'
|
||
Print a link map to the file MAPFILE. See the description of the
|
||
`-M' option, above.
|
||
|
||
`--no-keep-memory'
|
||
`ld' normally optimizes for speed over memory usage by caching the
|
||
symbol tables of input files in memory. This option tells `ld' to
|
||
instead optimize for memory usage, by rereading the symbol tables
|
||
as necessary. This may be required if `ld' runs out of memory
|
||
space while linking a large executable.
|
||
|
||
`--no-undefined'
|
||
Normally when creating a non-symbolic shared library, undefined
|
||
symbols are allowed and left to be resolved by the runtime loader.
|
||
This option disallows such undefined symbols.
|
||
|
||
`--no-warn-mismatch'
|
||
Normally `ld' will give an error if you try to link together input
|
||
files that are mismatched for some reason, perhaps because they
|
||
have been compiled for different processors or for different
|
||
endiannesses. This option tells `ld' that it should silently
|
||
permit such possible errors. This option should only be used with
|
||
care, in cases when you have taken some special action that
|
||
ensures that the linker errors are inappropriate.
|
||
|
||
`--no-whole-archive'
|
||
Turn off the effect of the `--whole-archive' option for subsequent
|
||
archive files.
|
||
|
||
`--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.
|
||
|
||
`--oformat OUTPUT-FORMAT'
|
||
`ld' may be configured to support more than one kind of object
|
||
file. If your `ld' is configured this way, you can use the
|
||
`--oformat' option to specify the binary format for the output
|
||
object file. Even when `ld' is configured to support alternative
|
||
object formats, you don't usually need to specify this, as `ld'
|
||
should be configured to produce as a default output format the most
|
||
usual format on each machine. 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 `objdump -i'.) The
|
||
script command `OUTPUT_FORMAT' can also specify the output format,
|
||
but this option overrides it. *Note BFD::.
|
||
|
||
`-qmagic'
|
||
This option is ignored for Linux compatibility.
|
||
|
||
`-Qy'
|
||
This option is ignored for SVR4 compatibility.
|
||
|
||
`--relax'
|
||
An option with machine dependent effects. This option is only
|
||
supported on a few targets. *Note `ld' and the H8/300: H8/300.
|
||
*Note `ld' and the Intel 960 family: i960.
|
||
|
||
On some platforms, the `--relax' option performs global
|
||
optimizations that become possible when the linker resolves
|
||
addressing in the program, such as relaxing address modes and
|
||
synthesizing new instructions in the output object file.
|
||
|
||
On some platforms these link time global optimizations may make
|
||
symbolic debugging of the resulting executable impossible. This
|
||
is known to be the case for the Matsushita MN10200 and MN10300
|
||
family of processors.
|
||
|
||
On platforms where this is not supported, `--relax' is accepted,
|
||
but ignored.
|
||
|
||
`--retain-symbols-file FILENAME'
|
||
Retain _only_ the symbols listed in the file FILENAME, discarding
|
||
all others. FILENAME is simply a flat file, with one symbol name
|
||
per line. This option is especially useful in environments (such
|
||
as VxWorks) where a large global symbol table is accumulated
|
||
gradually, to conserve run-time memory.
|
||
|
||
`--retain-symbols-file' does _not_ discard undefined symbols, or
|
||
symbols needed for relocations.
|
||
|
||
You may only specify `--retain-symbols-file' once in the command
|
||
line. It overrides `-s' and `-S'.
|
||
|
||
`-rpath DIR'
|
||
Add a directory to the runtime library search path. This is used
|
||
when linking an ELF executable with shared objects. All `-rpath'
|
||
arguments are concatenated and passed to the runtime linker, which
|
||
uses them to locate shared objects at runtime. The `-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 `-rpath-link' option. If `-rpath' is not used
|
||
when linking an ELF executable, the contents of the environment
|
||
variable `LD_RUN_PATH' will be used if it is defined.
|
||
|
||
The `-rpath' option may also be used on SunOS. By default, on
|
||
SunOS, the linker will form a runtime search patch out of all the
|
||
`-L' options it is given. If a `-rpath' option is used, the
|
||
runtime search path will be formed exclusively using the `-rpath'
|
||
options, ignoring the `-L' options. This can be useful when using
|
||
gcc, which adds many `-L' options which may be on NFS mounted
|
||
filesystems.
|
||
|
||
For compatibility with other ELF linkers, if the `-R' option is
|
||
followed by a directory name, rather than a file name, it is
|
||
treated as the `-rpath' option.
|
||
|
||
`-rpath-link DIR'
|
||
When using ELF or SunOS, one shared library may require another.
|
||
This happens when an `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-relocatable 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 `-rpath-link'
|
||
option specifies the first set of directories to search. The
|
||
`-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.
|
||
1. Any directories specified by `-rpath-link' options.
|
||
|
||
2. Any directories specified by `-rpath' options. The difference
|
||
between `-rpath' and `-rpath-link' is that directories
|
||
specified by `-rpath' options are included in the executable
|
||
and used at runtime, whereas the `-rpath-link' option is only
|
||
effective at link time.
|
||
|
||
3. On an ELF system, if the `-rpath' and `rpath-link' options
|
||
were not used, search the contents of the environment variable
|
||
`LD_RUN_PATH'.
|
||
|
||
4. On SunOS, if the `-rpath' option was not used, search any
|
||
directories specified using `-L' options.
|
||
|
||
5. For a native linker, the contents of the environment variable
|
||
`LD_LIBRARY_PATH'.
|
||
|
||
6. The default directories, normally `/lib' and `/usr/lib'.
|
||
|
||
7. For a native linker on an ELF system, if the file
|
||
`/etc/ld.so.conf' exists, the list of directories found in
|
||
that file.
|
||
|
||
If the required shared library is not found, the linker will issue
|
||
a warning and continue with the link.
|
||
|
||
`-shared'
|
||
`-Bshareable'
|
||
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 `-e' option is not
|
||
used and there are undefined symbols in the link.
|
||
|
||
`--sort-common'
|
||
This option tells `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.
|
||
|
||
`--split-by-file'
|
||
Similar to `--split-by-reloc' but creates a new output section for
|
||
each input file.
|
||
|
||
`--split-by-reloc COUNT'
|
||
Trys to creates extra sections in the output file so that no single
|
||
output section in the file contains more than 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 COUNT relocations one
|
||
output section will contain that many relocations.
|
||
|
||
`--stats'
|
||
Compute and display statistics about the operation of the linker,
|
||
such as execution time and memory usage.
|
||
|
||
`--traditional-format'
|
||
For some targets, the output of `ld' is different in some ways from
|
||
the output of some existing linker. This switch requests `ld' to
|
||
use the traditional format instead.
|
||
|
||
For example, on SunOS, `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 `dbx' program can not read the resulting
|
||
program (`gdb' has no trouble). The `--traditional-format' switch
|
||
tells `ld' to not combine duplicate entries.
|
||
|
||
`-Tbss ORG'
|
||
`-Tdata ORG'
|
||
`-Ttext ORG'
|
||
Use ORG as the starting address for--respectively--the `bss',
|
||
`data', or the `text' segment of the output file. ORG must be a
|
||
single hexadecimal integer; for compatibility with other linkers,
|
||
you may omit the leading `0x' usually associated with hexadecimal
|
||
values.
|
||
|
||
`--dll-verbose'
|
||
`--verbose'
|
||
Display the version number for `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.
|
||
|
||
`--version-script=VERSION-SCRIPTFILE'
|
||
Specify the name of a version script to the linker. This is
|
||
typically used when creating shared libraries to specify
|
||
additional information about the version heirarchy for the library
|
||
being created. This option is only meaningful on ELF platforms
|
||
which support shared libraries. *Note VERSION::.
|
||
|
||
`--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:
|
||
|
||
`int i = 1;'
|
||
A definition, which goes in the initialized data section of
|
||
the output file.
|
||
|
||
`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.
|
||
|
||
`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.
|
||
|
||
The `--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.
|
||
|
||
1. Turning a common symbol into a reference, because there is
|
||
already a definition for the symbol.
|
||
FILE(SECTION): warning: common of `SYMBOL'
|
||
overridden by definition
|
||
FILE(SECTION): warning: defined here
|
||
|
||
2. 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.
|
||
FILE(SECTION): warning: definition of `SYMBOL'
|
||
overriding common
|
||
FILE(SECTION): warning: common is here
|
||
|
||
3. Merging a common symbol with a previous same-sized common
|
||
symbol.
|
||
FILE(SECTION): warning: multiple common
|
||
of `SYMBOL'
|
||
FILE(SECTION): warning: previous common is here
|
||
|
||
4. Merging a common symbol with a previous larger common symbol.
|
||
FILE(SECTION): warning: common of `SYMBOL'
|
||
overridden by larger common
|
||
FILE(SECTION): warning: larger common is here
|
||
|
||
5. 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.
|
||
FILE(SECTION): warning: common of `SYMBOL'
|
||
overriding smaller common
|
||
FILE(SECTION): warning: smaller common is here
|
||
|
||
`--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.
|
||
|
||
`--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.
|
||
|
||
`--warn-once'
|
||
Only warn once for each undefined symbol, rather than once per
|
||
module which refers to it.
|
||
|
||
`--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 `SECTIONS' command does not specify a
|
||
start address for the section (*note SECTIONS::).
|
||
|
||
`--whole-archive'
|
||
For each archive mentioned on the command line after the
|
||
`--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.
|
||
|
||
`--wrap SYMBOL'
|
||
Use a wrapper function for SYMBOL. Any undefined reference to
|
||
SYMBOL will be resolved to `__wrap_SYMBOL'. Any undefined
|
||
reference to `__real_SYMBOL' will be resolved to SYMBOL.
|
||
|
||
This can be used to provide a wrapper for a system function. The
|
||
wrapper function should be called `__wrap_SYMBOL'. If it wishes
|
||
to call the system function, it should call `__real_SYMBOL'.
|
||
|
||
Here is a trivial example:
|
||
|
||
void *
|
||
__wrap_malloc (int c)
|
||
{
|
||
printf ("malloc called with %ld\n", c);
|
||
return __real_malloc (c);
|
||
}
|
||
|
||
If you link other code with this file using `--wrap malloc', then
|
||
all calls to `malloc' will call the function `__wrap_malloc'
|
||
instead. The call to `__real_malloc' in `__wrap_malloc' will call
|
||
the real `malloc' function.
|
||
|
||
You may wish to provide a `__real_malloc' function as well, so that
|
||
links without the `--wrap' option will succeed. If you do this,
|
||
you should not put the definition of `__real_malloc' in the same
|
||
file as `__wrap_malloc'; if you do, the assembler may resolve the
|
||
call before the linker has a chance to wrap it to `malloc'.
|
||
|
||
Options specific to i386 PE targets
|
||
-----------------------------------
|
||
|
||
The i386 PE linker supports the `-shared' option, which causes the
|
||
output to be a dynamically linked library (DLL) instead of a normal
|
||
executable. You should name the output `*.dll' when you use this
|
||
option. In addition, the linker fully supports the standard `*.def'
|
||
files, which may be specified on the linker command line like an object
|
||
file (in fact, it should precede archives it exports symbols from, to
|
||
ensure that they get linked in, just like a normal object file).
|
||
|
||
In addition to the options common to all targets, the i386 PE linker
|
||
support additional command line options that are specific to the i386
|
||
PE target. Options that take values may be separated from their values
|
||
by either a space or an equals sign.
|
||
|
||
`--add-stdcall-alias'
|
||
If given, symbols with a stdcall suffix (@NN) will be exported
|
||
as-is and also with the suffix stripped.
|
||
|
||
`--base-file FILE'
|
||
Use FILE as the name of a file in which to save the base addresses
|
||
of all the relocations needed for generating DLLs with `dlltool'.
|
||
|
||
`--dll'
|
||
Create a DLL instead of a regular executable. You may also use
|
||
`-shared' or specify a `LIBRARY' in a given `.def' file.
|
||
|
||
`--enable-stdcall-fixup'
|
||
`--disable-stdcall-fixup'
|
||
If the link finds a symbol that it cannot resolve, it will attempt
|
||
to do "fuzzy linking" by looking for another defined symbol that
|
||
differs only in the format of the symbol name (cdecl vs stdcall)
|
||
and will resolve that symbol by linking to the match. For
|
||
example, the undefined symbol `_foo' might be linked to the
|
||
function `_foo@12', or the undefined symbol `_bar@16' might be
|
||
linked to the function `_bar'. When the linker does this, it
|
||
prints a warning, since it normally should have failed to link,
|
||
but sometimes import libraries generated from third-party dlls may
|
||
need this feature to be usable. If you specify
|
||
`--enable-stdcall-fixup', this feature is fully enabled and
|
||
warnings are not printed. If you specify
|
||
`--disable-stdcall-fixup', this feature is disabled and such
|
||
mismatches are considered to be errors.
|
||
|
||
`--export-all-symbols'
|
||
If given, all global symbols in the objects used to build a DLL
|
||
will be exported by the DLL. Note that this is the default if
|
||
there otherwise wouldn't be any exported symbols. When symbols are
|
||
explicitly exported via DEF files or implicitly exported via
|
||
function attributes, the default is to not export anything else
|
||
unless this option is given. Note that the symbols `DllMain@12',
|
||
`DllEntryPoint@0', and `impure_ptr' will not be automatically
|
||
exported.
|
||
|
||
`--exclude-symbols SYMBOL,SYMBOL,...'
|
||
Specifies a list of symbols which should not be automatically
|
||
exported. The symbol names may be delimited by commas or colons.
|
||
|
||
`--file-alignment'
|
||
Specify the file alignment. Sections in the file will always
|
||
begin at file offsets which are multiples of this number. This
|
||
defaults to 512.
|
||
|
||
`--heap RESERVE'
|
||
`--heap RESERVE,COMMIT'
|
||
Specify the amount of memory to reserve (and optionally commit) to
|
||
be used as heap for this program. The default is 1Mb reserved, 4K
|
||
committed.
|
||
|
||
`--image-base VALUE'
|
||
Use VALUE as the base address of your program or dll. This is the
|
||
lowest memory location that will be used when your program or dll
|
||
is loaded. To reduce the need to relocate and improve performance
|
||
of your dlls, each should have a unique base address and not
|
||
overlap any other dlls. The default is 0x400000 for executables,
|
||
and 0x10000000 for dlls.
|
||
|
||
`--kill-at'
|
||
If given, the stdcall suffixes (@NN) will be stripped from symbols
|
||
before they are exported.
|
||
|
||
`--major-image-version VALUE'
|
||
Sets the major number of the "image version". Defaults to 1.
|
||
|
||
`--major-os-version VALUE'
|
||
Sets the major number of the "os version". Defaults to 4.
|
||
|
||
`--major-subsystem-version VALUE'
|
||
Sets the major number of the "subsystem version". Defaults to 4.
|
||
|
||
`--minor-image-version VALUE'
|
||
Sets the minor number of the "image version". Defaults to 0.
|
||
|
||
`--minor-os-version VALUE'
|
||
Sets the minor number of the "os version". Defaults to 0.
|
||
|
||
`--minor-subsystem-version VALUE'
|
||
Sets the minor number of the "subsystem version". Defaults to 0.
|
||
|
||
`--output-def FILE'
|
||
The linker will create the file FILE which will contain a DEF file
|
||
corresponding to the DLL the linker is generating. This DEF file
|
||
(which should be called `*.def') may be used to create an import
|
||
library with `dlltool' or may be used as a reference to
|
||
automatically or implicitly exported symbols.
|
||
|
||
`--section-alignment'
|
||
Sets the section alignment. Sections in memory will always begin
|
||
at addresses which are a multiple of this number. Defaults to
|
||
0x1000.
|
||
|
||
`--stack RESERVE'
|
||
`--stack RESERVE,COMMIT'
|
||
Specify the amount of memory to reserve (and optionally commit) to
|
||
be used as stack for this program. The default is 32Mb reserved,
|
||
4K committed.
|
||
|
||
`--subsystem WHICH'
|
||
`--subsystem WHICH:MAJOR'
|
||
`--subsystem WHICH:MAJOR.MINOR'
|
||
Specifies the subsystem under which your program will execute. The
|
||
legal values for WHICH are `native', `windows', `console', and
|
||
`posix'. You may optionally set the subsystem version also.
|
||
|