mirror of
https://sourceware.org/git/binutils-gdb.git
synced 2024-11-29 04:53:56 +08:00
e3d73386d7
* ldmain.c (main): Initialize link_info.wrap_hash. * ldexp.c (fold_name): Use bfd_wrapped_link_hash_lookup in DEFINED and NAME cases. * ld.texinfo, ld.1: Document --wrap.
1034 lines
24 KiB
Groff
1034 lines
24 KiB
Groff
.\" Copyright (c) 1991, 92, 93, 94, 95, 1996 Free Software Foundation
|
|
.\" See section COPYING for conditions for redistribution
|
|
.TH ld 1 "17 August 1992" "cygnus support" "GNU Development Tools"
|
|
.de BP
|
|
.sp
|
|
.ti \-.2i
|
|
\(**
|
|
..
|
|
|
|
.SH NAME
|
|
ld \- the GNU linker
|
|
|
|
.SH SYNOPSIS
|
|
.hy 0
|
|
.na
|
|
.TP
|
|
.B ld
|
|
.RB "[\|" \-o "
|
|
.I output\c
|
|
\&\|] \c
|
|
.I objfile\c
|
|
\&.\|.\|.
|
|
.br
|
|
.RB "[\|" \-A\c
|
|
.I architecture\c
|
|
\&\|]
|
|
.RB "[\|" "\-b\ "\c
|
|
.I input-format\c
|
|
\&\|]
|
|
.RB "[\|" \-Bstatic "\|]"
|
|
.RB "[\|" \-Bdynamic "\|]"
|
|
.RB "[\|" \-Bsymbolic "\|]"
|
|
.RB "[\|" "\-c\ "\c
|
|
.I commandfile\c
|
|
\&\|]
|
|
.RB "[\|" \-d | \-dc | \-dp\c
|
|
\|]
|
|
.br
|
|
.RB "[\|" "\-defsym\ "\c
|
|
.I symbol\c
|
|
\& = \c
|
|
.I expression\c
|
|
\&\|]
|
|
.RB "[\|" "\-e\ "\c
|
|
.I entry\c
|
|
\&\|]
|
|
.RB "[\|" \-embedded\-relocs "\|]"
|
|
.RB "[\|" \-export\-dynamic "\|]"
|
|
.RB "[\|" \-F "\|]"
|
|
.RB "[\|" "\-F\ "\c
|
|
.I format\c
|
|
\&\|]
|
|
.RB "[\|" "\-format\ "\c
|
|
.I input-format\c
|
|
\&\|]
|
|
.RB "[\|" \-g "\|]"
|
|
.RB "[\|" \-G
|
|
.I size\c
|
|
\&\|]
|
|
.RB "[\|" \-\-help "\|]"
|
|
.RB "[\|" \-i "\|]"
|
|
.RB "[\|" \-l\c
|
|
.I ar\c
|
|
\&\|]
|
|
.RB "[\|" \-L\c
|
|
.I searchdir\c
|
|
\&\|]
|
|
.RB "[\|" \-M "\|]"
|
|
.RB "[\|" \-Map
|
|
.I mapfile\c
|
|
\&\|]
|
|
.RB "[\|" \-m
|
|
.I emulation\c
|
|
\&\|]
|
|
.RB "[\|" \-n | \-N "\|]"
|
|
.RB "[\|" \-noinhibit-exec "\|]"
|
|
.RB "[\|" \-no\-keep\-memory "\|]"
|
|
.RB "[\|" "\-oformat\ "\c
|
|
.I output-format\c
|
|
\&\|]
|
|
.RB "[\|" "\-R\ "\c
|
|
.I filename\c
|
|
\&\|]
|
|
.RB "[\|" \-relax "\|]"
|
|
.RB "[\|" \-r | \-Ur "\|]"
|
|
.RB "[\|" "\-rpath\ "\c
|
|
.I directory\c
|
|
\&\|]
|
|
.RB "[\|" "\-rpath\-link\ "\c
|
|
.I directory\c
|
|
\&\|]
|
|
.RB "[\|" \-S "\|]"
|
|
.RB "[\|" \-s "\|]"
|
|
.RB "[\|" \-shared "\|]"
|
|
.RB "[\|" \-sort\-common "\|]"
|
|
.RB "[\|" "\-split\-by\-reloc\ "\c
|
|
.I count\c
|
|
\&\|]
|
|
.RB "[\|" \-split\-by\-file "\|]"
|
|
.RB "[\|" "\-T\ "\c
|
|
.I commandfile\c
|
|
\&\|]
|
|
.RB "[\|" "\-Ttext\ "\c
|
|
.I textorg\c
|
|
\&\|]
|
|
.RB "[\|" "\-Tdata\ "\c
|
|
.I dataorg\c
|
|
\&\|]
|
|
.RB "[\|" "\-Tbss\ "\c
|
|
.I bssorg\c
|
|
\&\|]
|
|
.RB "[\|" \-t "\|]"
|
|
.RB "[\|" "\-u\ "\c
|
|
.I sym\c
|
|
\&]
|
|
.RB "[\|" \-V "\|]"
|
|
.RB "[\|" \-v "\|]"
|
|
.RB "[\|" \-\-verbose "\|]"
|
|
.RB "[\|" \-\-version "\|]"
|
|
.RB "[\|" \-warn\-common "\|]"
|
|
.RB "[\|" \-warn\-constructors "\|]"
|
|
.RB "[\|" \-warn\-multiple\-gp "\|]"
|
|
.RB "[\|" \-warn\-once "\|]"
|
|
.RB "[\|" \-\-whole\-archive "\|]"
|
|
.RB "[\|" \-\-no\-whole\-archive "\|]"
|
|
.RB "[\|" "\-\-wrap\ "\c
|
|
.I symbol\c
|
|
\&\|]
|
|
.RB "[\|" \-X "\|]"
|
|
.RB "[\|" \-x "\|]"
|
|
.ad b
|
|
.hy 1
|
|
.SH DESCRIPTION
|
|
\c
|
|
.B ld\c
|
|
\& combines a number of object and archive files, relocates
|
|
their data and ties up symbol references. Often the last step in
|
|
building a new compiled program to run is a call to \c
|
|
.B ld\c
|
|
\&.
|
|
|
|
\c
|
|
.B ld\c
|
|
\& accepts Linker Command Language files
|
|
to provide explicit and total control over the linking process.
|
|
This man page does not describe the command language; see the `\|\c
|
|
.B ld\c
|
|
\|' entry in `\|\c
|
|
.B info\c
|
|
\|', or the manual
|
|
.I
|
|
ld: the GNU linker
|
|
\&, for full details on the command language and on other aspects of
|
|
the GNU linker.
|
|
|
|
This version of \c
|
|
.B ld\c
|
|
\& uses the general purpose BFD libraries
|
|
to operate on object files. This allows \c
|
|
.B ld\c
|
|
\& to read, combine, and
|
|
write object files in many different formats\(em\&for example, COFF or
|
|
\c
|
|
.B a.out\c
|
|
\&. Different formats may be linked together to produce any
|
|
available kind of object file. You can use `\|\c
|
|
.B objdump \-i\c
|
|
\|' to get a list of formats supported on various architectures; see
|
|
.BR objdump ( 1 ).
|
|
|
|
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,
|
|
\c
|
|
.B ld\c
|
|
\& continues executing, allowing you to identify other errors
|
|
(or, in some cases, to get an output file in spite of the error).
|
|
|
|
The GNU linker \c
|
|
.B ld\c
|
|
\& 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 through the command line,
|
|
and through environment variables.
|
|
|
|
.SH OPTIONS
|
|
The plethora of command-line options may seem intimidating, but in
|
|
actual practice few of them are used in any particular context.
|
|
For instance, a frequent use of \c
|
|
.B ld\c
|
|
\& is to link standard Unix
|
|
object files on a standard, supported Unix system. On such a system, to
|
|
link a file \c
|
|
.B hello.o\c
|
|
\&:
|
|
.sp
|
|
.br
|
|
$\ ld\ \-o\ output\ /lib/crt0.o\ hello.o\ \-lc
|
|
.br
|
|
.sp
|
|
This tells \c
|
|
.B ld\c
|
|
\& to produce a file called \c
|
|
.B output\c
|
|
\& as the
|
|
result of linking the file \c
|
|
.B /lib/crt0.o\c
|
|
\& with \c
|
|
.B hello.o\c
|
|
\& and
|
|
the library \c
|
|
.B libc.a\c
|
|
\& which will come from the standard search
|
|
directories.
|
|
|
|
The command-line options to \c
|
|
.B ld\c
|
|
\& may be specified in any order, and
|
|
may be repeated at will. For the most part, repeating an option with a
|
|
different argument will either have no further effect, or override prior
|
|
occurrences (those further to the left on the command line) of an
|
|
option.
|
|
|
|
The exceptions\(em\&which may meaningfully be used more than once\(em\&are
|
|
\c
|
|
.B \-A\c
|
|
\&, \c
|
|
.B \-b\c
|
|
\& (or its synonym \c
|
|
.B \-format\c
|
|
\&), \c
|
|
.B \-defsym\c
|
|
\&,
|
|
\c
|
|
.B \-L\c
|
|
\&, \c
|
|
.B \-l\c
|
|
\&, \c
|
|
.B \-R\c
|
|
\&, and \c
|
|
.B \-u\c
|
|
\&.
|
|
|
|
The list of object files to be linked together, shown as \c
|
|
.I objfile\c
|
|
\&,
|
|
may follow, precede, or be mixed in with command-line options; save that
|
|
an \c
|
|
.I objfile\c
|
|
\& argument may not be placed between an option flag and
|
|
its argument.
|
|
|
|
Usually the linker is invoked with at least one object file, but other
|
|
forms of binary input files can also be specified with \c
|
|
.B \-l\c
|
|
\&,
|
|
\c
|
|
.B \-R\c
|
|
\&, and the script command language. If \c
|
|
.I no\c
|
|
\& binary input
|
|
files at all are specified, the linker does not produce any output, and
|
|
issues the message `\|\c
|
|
.B No input files\c
|
|
\|'.
|
|
|
|
Option arguments must either follow the option letter without intervening
|
|
whitespace, or be given as separate arguments immediately following the
|
|
option that requires them.
|
|
|
|
.TP
|
|
.BI "-A" "architecture"
|
|
In the current release of \c
|
|
.B ld\c
|
|
\&, this option is useful only for the
|
|
Intel 960 family of architectures. In that \c
|
|
.B ld\c
|
|
\& configuration, the
|
|
\c
|
|
.I architecture\c
|
|
\& argument is 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 \c
|
|
.B ld\c
|
|
\& command line included `\|\c
|
|
.B \-ACA\c
|
|
\|' as
|
|
well as `\|\c
|
|
.B \-ltry\c
|
|
\|', the linker would look (in its built-in search
|
|
paths, and in any paths you specify with \c
|
|
.B \-L\c
|
|
\&) for a library with
|
|
the names
|
|
.sp
|
|
.br
|
|
try
|
|
.br
|
|
libtry.a
|
|
.br
|
|
tryca
|
|
.br
|
|
libtryca.a
|
|
.br
|
|
.sp
|
|
|
|
The first two possibilities would be considered in any event; the last
|
|
two are due to the use of `\|\c
|
|
.B \-ACA\c
|
|
\|'.
|
|
|
|
Future releases of \c
|
|
.B ld\c
|
|
\& may support similar functionality for
|
|
other architecture families.
|
|
|
|
You can meaningfully use \c
|
|
.B \-A\c
|
|
\& more than once on a command line, if
|
|
an architecture family allows combination of target architectures; each
|
|
use will add another pair of name variants to search for when \c
|
|
.B \-l
|
|
specifies a library.
|
|
|
|
.TP
|
|
.BI "\-b " "input-format"
|
|
Specify the binary format for input object files that follow this option
|
|
on the command line. You don't usually need to specify this, as
|
|
\c
|
|
.B ld\c
|
|
\& is configured to expect as a default input format the most
|
|
usual format on each machine. \c
|
|
.I input-format\c
|
|
\& is a text string, the
|
|
name of a particular format supported by the BFD libraries.
|
|
\c
|
|
.B \-format \c
|
|
.I input-format\c
|
|
\&\c
|
|
\& has the same effect, as does the script command
|
|
.BR TARGET .
|
|
|
|
You may want to use this option if you are linking files with an unusual
|
|
binary format. You can also use \c
|
|
.B \-b\c
|
|
\& to switch formats explicitly (when
|
|
linking object files of different formats), by including
|
|
\c
|
|
.B \-b \c
|
|
.I input-format\c
|
|
\&\c
|
|
\& before each group of object files in a
|
|
particular format.
|
|
|
|
The default format is taken from the environment variable
|
|
.B GNUTARGET\c
|
|
\&. You can also define the input
|
|
format from a script, using the command \c
|
|
.B TARGET\c
|
|
\&.
|
|
|
|
.TP
|
|
.B \-Bstatic
|
|
Do not link against shared libraries. This is only meaningful on
|
|
platforms for which shared libraries are supported.
|
|
|
|
.TP
|
|
.B \-Bdynamic
|
|
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.
|
|
|
|
.TP
|
|
.B \-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.
|
|
|
|
.TP
|
|
.BI "\-c " "commandfile"
|
|
Directs \c
|
|
.B ld\c
|
|
\& to read link commands from the file
|
|
\c
|
|
.I commandfile\c
|
|
\&. These commands will completely override \c
|
|
.B ld\c
|
|
\&'s
|
|
default link format (rather than adding to it); \c
|
|
.I commandfile\c
|
|
\& must
|
|
specify everything necessary to describe the target format.
|
|
|
|
|
|
You may also include a script of link commands directly in the command
|
|
line by bracketing it between `\|\c
|
|
.B {\c
|
|
\|' and `\|\c
|
|
.B }\c
|
|
\|' characters.
|
|
|
|
.TP
|
|
.B \-d
|
|
.TP
|
|
.B \-dc
|
|
.TP
|
|
.B \-dp
|
|
These three options are equivalent; multiple forms are supported for
|
|
compatibility with other linkers. Use any of them to make \c
|
|
.B ld
|
|
assign space to common symbols even if a relocatable output file is
|
|
specified (\c
|
|
.B \-r\c
|
|
\&). The script command
|
|
\c
|
|
.B FORCE_COMMON_ALLOCATION\c
|
|
\& has the same effect.
|
|
|
|
.TP
|
|
.BI "-defsym " "symbol" "\fR = \fP" expression
|
|
Create a global symbol in the output file, containing the absolute
|
|
address given by \c
|
|
.I expression\c
|
|
\&. 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 \c
|
|
.I expression\c
|
|
\& in this
|
|
context: you may give a hexadecimal constant or the name of an existing
|
|
symbol, or use \c
|
|
.B +\c
|
|
\& and \c
|
|
.B \-\c
|
|
\& to add or subtract hexadecimal
|
|
constants or symbols. If you need more elaborate expressions, consider
|
|
using the linker command language from a script.
|
|
|
|
.TP
|
|
.BI "-e " "entry"\c
|
|
\&
|
|
Use \c
|
|
.I entry\c
|
|
\& as the explicit symbol for beginning execution of your
|
|
program, rather than the default entry point. for a
|
|
discussion of defaults and other ways of specifying the
|
|
entry point.
|
|
|
|
.TP
|
|
.B \-embedded\-relocs
|
|
This option is only meaningful when linking MIPS embedded PIC code,
|
|
generated by the
|
|
.B \-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.
|
|
|
|
.TP
|
|
.B \-export\-dynamic
|
|
When creating an ELF file, 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
|
|
.I dlopen.
|
|
|
|
.TP
|
|
.B \-F
|
|
.TP
|
|
.BI "-F" "format"
|
|
Some older linkers used this option throughout a compilation toolchain
|
|
for specifying object-file format for both input and output object
|
|
files. \c
|
|
.B ld\c
|
|
\&'s mechanisms (the \c
|
|
.B \-b\c
|
|
\& or \c
|
|
.B \-format\c
|
|
\& options
|
|
for input files, the \c
|
|
.B TARGET\c
|
|
\& command in linker scripts for output
|
|
files, the \c
|
|
.B GNUTARGET\c
|
|
\& environment variable) are more flexible, but
|
|
but it accepts (and ignores) the \c
|
|
.B \-F\c
|
|
\& option flag for compatibility
|
|
with scripts written to call the old linker.
|
|
|
|
.TP
|
|
.BI "\-format " "input\-format"
|
|
Synonym for \c
|
|
.B \-b\c
|
|
\& \c
|
|
.I input\-format\c
|
|
\&.
|
|
|
|
.TP
|
|
.B \-g
|
|
Accepted, but ignored; provided for compatibility with other tools.
|
|
|
|
.TP
|
|
.BI "\-G " "size"\c
|
|
Set the maximum size of objects to be optimized using the GP register
|
|
to
|
|
.I size
|
|
under MIPS ECOFF. Ignored for other object file formats.
|
|
|
|
.TP
|
|
.B \-\-help
|
|
Print a summary of the command-line options on the standard output and exit.
|
|
This option and
|
|
.B \-\-version
|
|
begin with two dashes instead of one
|
|
for compatibility with other GNU programs. The other options start with
|
|
only one dash for compatibility with other linkers.
|
|
|
|
.TP
|
|
.B \-i
|
|
Perform an incremental link (same as option \c
|
|
.B \-r\c
|
|
\&).
|
|
|
|
.TP
|
|
.BI "\-l" "ar"\c
|
|
\&
|
|
Add an archive file \c
|
|
.I ar\c
|
|
\& to the list of files to link. This
|
|
option may be used any number of times. \c
|
|
.B ld\c
|
|
\& will search its
|
|
path-list for occurrences of \c
|
|
.B lib\c
|
|
.I ar\c
|
|
\&.a\c
|
|
\& for every \c
|
|
.I ar
|
|
specified.
|
|
|
|
.TP
|
|
.BI "\-L" "searchdir"
|
|
This command adds path \c
|
|
.I searchdir\c
|
|
\& to the list of paths that
|
|
\c
|
|
.B ld\c
|
|
\& will search for archive libraries. You may use this option
|
|
any number of times.
|
|
|
|
The default set of paths searched (without being specified with
|
|
\c
|
|
.B \-L\c
|
|
\&) depends on what emulation mode \c
|
|
.B ld\c
|
|
\& is using, and in
|
|
some cases also on how it was configured. The
|
|
paths can also be specified in a link script with the \c
|
|
.B SEARCH_DIR
|
|
command.
|
|
|
|
.TP
|
|
.B \-M
|
|
Print (to the standard output file) a link map\(em\&diagnostic information
|
|
about where symbols are mapped by \c
|
|
.B ld\c
|
|
\&, and information on global
|
|
common storage allocation.
|
|
|
|
.TP
|
|
.BI "\-Map " "mapfile"\c
|
|
Print to the file
|
|
.I mapfile
|
|
a link map\(em\&diagnostic information
|
|
about where symbols are mapped by \c
|
|
.B ld\c
|
|
\&, and information on global
|
|
common storage allocation.
|
|
|
|
.TP
|
|
.BI "\-m " "emulation"\c
|
|
Emulate the
|
|
.I emulation
|
|
linker. You can list the available emulations with the
|
|
.I \-\-verbose
|
|
or
|
|
.I \-V
|
|
options. This option overrides the compiled-in default, which is the
|
|
system for which you configured
|
|
.BR ld .
|
|
|
|
.TP
|
|
.B \-N
|
|
specifies readable and writable \c
|
|
.B text\c
|
|
\& and \c
|
|
.B data\c
|
|
\& sections. If
|
|
the output format supports Unix style magic numbers, the output is
|
|
marked as \c
|
|
.B OMAGIC\c
|
|
\&.
|
|
|
|
When you use the `\|\c
|
|
.B \-N\c
|
|
\&\|' option, the linker does not page-align the
|
|
data segment.
|
|
|
|
.TP
|
|
.B \-n
|
|
sets the text segment to be read only, and \c
|
|
.B NMAGIC\c
|
|
\& is written
|
|
if possible.
|
|
|
|
.TP
|
|
.B \-noinhibit\-exec
|
|
Normally, the linker will not produce an output file if it encounters
|
|
errors during the link process. With this flag, you can specify that
|
|
you wish the output file retained even after non-fatal errors.
|
|
|
|
.TP
|
|
.B \-no\-keep\-memory
|
|
The linker normally optimizes for speed over memory usage by caching
|
|
the symbol tables of input files in memory. This option tells the
|
|
linker to instead optimize for memory usage, by rereading the symbol
|
|
tables as necessary. This may be required if the linker runs out of
|
|
memory space while linking a large executable.
|
|
|
|
.TP
|
|
.BI "\-o " "output"
|
|
.I output\c
|
|
\& is a name for the program produced by \c
|
|
.B ld\c
|
|
\&; if this
|
|
option is not specified, the name `\|\c
|
|
.B a.out\c
|
|
\|' is used by default. The
|
|
script command \c
|
|
.B OUTPUT\c
|
|
\& can also specify the output file name.
|
|
|
|
.TP
|
|
.BI "\-oformat " "output\-format"
|
|
Specify the binary format for the output object file.
|
|
You don't usually need to specify this, as
|
|
\c
|
|
.B ld\c
|
|
\& is configured to produce as a default output format the most
|
|
usual format on each machine. \c
|
|
.I output-format\c
|
|
\& is a text string, the
|
|
name of a particular format supported by the BFD libraries.
|
|
The script command
|
|
.B OUTPUT_FORMAT
|
|
can also specify the output format, but this option overrides it.
|
|
|
|
.TP
|
|
.BI "\-R " "filename"
|
|
Read symbol names and their addresses from \c
|
|
.I filename\c
|
|
\&, 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.
|
|
|
|
.TP
|
|
.B \-relax
|
|
An option with machine dependent effects. Currently this option is only
|
|
supported on the H8/300.
|
|
|
|
On some platforms, use this option to perform global optimizations that
|
|
become possible when the linker resolves addressing in your program, such
|
|
as relaxing address modes and synthesizing new instructions in the
|
|
output object file.
|
|
|
|
On platforms where this is not supported, `\|\c
|
|
.B \-relax\c
|
|
\&\|' is accepted, but has no effect.
|
|
|
|
.TP
|
|
.B \-r
|
|
Generates relocatable output\(em\&i.e., generate an output file that can in
|
|
turn serve as input to \c
|
|
.B ld\c
|
|
\&. This is often called \c
|
|
.I partial
|
|
linking\c
|
|
\&. As a side effect, in environments that support standard Unix
|
|
magic numbers, this option also sets the output file's magic number to
|
|
\c
|
|
.B OMAGIC\c
|
|
\&.
|
|
If this option is not specified, an absolute file is produced. When
|
|
linking C++ programs, this option \c
|
|
.I will not\c
|
|
\& resolve references to
|
|
constructors; \c
|
|
.B \-Ur\c
|
|
\& is an alternative.
|
|
|
|
This option does the same as \c
|
|
.B \-i\c
|
|
\&.
|
|
|
|
.TP
|
|
.B \-rpath\ \fIdirectory
|
|
Add a directory to the runtime library search path. This is used when
|
|
linking an ELF executable with shared objects. All
|
|
.B \-rpath
|
|
arguments are concatenated and passed to the runtime linker, which uses
|
|
them to locate shared objects at runtime. The
|
|
.B \-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
|
|
.B \-rpath\-link
|
|
option. If
|
|
.B \-rpath
|
|
is not used when linking an ELF executable, the contents of the
|
|
environment variable
|
|
.B LD_RUN_PATH
|
|
will be used if it is defined.
|
|
|
|
The
|
|
.B \-rpath
|
|
option may also be used on SunOS. By default, on SunOS, the linker
|
|
will form a runtime search patch out of all the
|
|
.B \-L
|
|
options it is given. If a
|
|
.B \-rpath
|
|
option is used, the runtime search path will be formed exclusively
|
|
using the
|
|
.B \-rpath
|
|
options, ignoring
|
|
the
|
|
.B \-L
|
|
options. This can be useful when using gcc, which adds many
|
|
.B \-L
|
|
options which may be on NFS mounted filesystems.
|
|
|
|
.TP
|
|
.B \-rpath\-link\ \fIdirectory
|
|
When using ELF or SunOS, one shared library may require another. This
|
|
happens when an
|
|
.B 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
|
|
.B \-rpath\-link
|
|
option specifies the first set of directories to search. The
|
|
.B \-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.
|
|
|
|
If the required shared library is not found, the linker will issue a
|
|
warning and continue with the link.
|
|
|
|
.TP
|
|
.B \-S
|
|
Omits debugger symbol information (but not all symbols) from the output file.
|
|
|
|
.TP
|
|
.B \-s
|
|
Omits all symbol information from the output file.
|
|
|
|
.TP
|
|
.B \-shared
|
|
Create a shared library. This is currently only supported on ELF and
|
|
SunOS platforms (on SunOS it is not required, as the linker will
|
|
automatically create a shared library when there are undefined symbols
|
|
and the
|
|
.B \-e
|
|
option is not used).
|
|
|
|
.TP
|
|
.B \-sort\-common
|
|
Normally, when
|
|
.B ld
|
|
places the global common symbols in the appropriate output sections,
|
|
it sorts them by size. 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. This option disables that sorting.
|
|
|
|
.TP
|
|
.B \-split\-by\-reloc\ \fIcount
|
|
Trys to creates extra sections in the output file so that no single
|
|
output section in the file contains more than
|
|
.I 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
|
|
.I count
|
|
relocations one output section will contain that many relocations.
|
|
|
|
.TP
|
|
.B \-split\-by\-file
|
|
Similar to
|
|
.B \-split\-by\-reloc
|
|
but creates a new output section for each input file.
|
|
|
|
.TP
|
|
.BI "\-Tbss " "org"\c
|
|
.TP
|
|
.BI "\-Tdata " "org"\c
|
|
.TP
|
|
.BI "\-Ttext " "org"\c
|
|
Use \c
|
|
.I org\c
|
|
\& as the starting address for\(em\&respectively\(em\&the
|
|
\c
|
|
.B bss\c
|
|
\&, \c
|
|
.B data\c
|
|
\&, or the \c
|
|
.B text\c
|
|
\& segment of the output file.
|
|
\c
|
|
.I textorg\c
|
|
\& must be a hexadecimal integer.
|
|
|
|
.TP
|
|
.BI "\-T " "commandfile"
|
|
Equivalent to \c
|
|
.B \-c \c
|
|
.I commandfile\c
|
|
\&\c
|
|
\&; supported for compatibility with
|
|
other tools.
|
|
|
|
.TP
|
|
.B \-t
|
|
Prints names of input files as \c
|
|
.B ld\c
|
|
\& processes them.
|
|
|
|
.TP
|
|
.BI "\-u " "sym"
|
|
Forces \c
|
|
.I sym\c
|
|
\& to be entered in the output file as an undefined symbol.
|
|
This may, for example, trigger linking of additional modules from
|
|
standard libraries. \c
|
|
.B \-u\c
|
|
\& may be repeated with different option
|
|
arguments to enter additional undefined symbols.
|
|
|
|
.TP
|
|
.B \-Ur
|
|
For anything other than C++ programs, this option is equivalent to
|
|
\c
|
|
.B \-r\c
|
|
\&: it generates relocatable output\(em\&i.e., an output file that can in
|
|
turn serve as input to \c
|
|
.B ld\c
|
|
\&. When linking C++ programs, \c
|
|
.B \-Ur
|
|
.I will\c
|
|
\& resolve references to constructors, unlike \c
|
|
.B \-r\c
|
|
\&.
|
|
|
|
.TP
|
|
.B \-\-verbose
|
|
Display the version number for \c
|
|
.B ld
|
|
and list the supported emulations.
|
|
Display which input files can and can not be opened.
|
|
|
|
.TP
|
|
.B \-v, \-V
|
|
Display the version number for \c
|
|
.B ld\c
|
|
\&.
|
|
The
|
|
.B \-V
|
|
option also lists the supported emulations.
|
|
|
|
.TP
|
|
.B \-\-version
|
|
Display the version number for \c
|
|
.B ld
|
|
and exit.
|
|
|
|
.TP
|
|
.B \-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.
|
|
|
|
.TP
|
|
.B \-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.
|
|
|
|
.TP
|
|
.B \-warn\-multiple\-gp
|
|
Warn if the output file requires multiple global-pointer values. This
|
|
option is only meaningful for certain processors, such as the Alpha.
|
|
|
|
.TP
|
|
.B \-warn\-once
|
|
Only warn once for each undefined symbol, rather than once per module
|
|
which refers to it.
|
|
|
|
.TP
|
|
.B \-\-whole\-archive
|
|
For each archive mentioned on the command line after the
|
|
.B \-\-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.
|
|
|
|
.TP
|
|
.B \-\-no\-whole\-archive
|
|
Turn off the effect of the
|
|
.B \-\-whole\-archive
|
|
option for archives which appear later on the command line.
|
|
|
|
.TP
|
|
.BI "--wrap " "symbol"
|
|
Use a wrapper function for
|
|
.I symbol.
|
|
Any undefined reference to
|
|
.I symbol
|
|
will be resolved to
|
|
.BI "__wrap_" "symbol".
|
|
Any undefined reference to
|
|
.BI "__real_" "symbol"
|
|
will be resolved to
|
|
.I symbol.
|
|
|
|
.TP
|
|
.B \-X
|
|
Delete all temporary local symbols. For most targets, this is all local
|
|
symbols whose names begin with `\|\c
|
|
.B L\c
|
|
\|'.
|
|
|
|
.TP
|
|
.B \-x
|
|
Delete all local symbols.
|
|
|
|
.PP
|
|
|
|
.SH ENVIRONMENT
|
|
\c
|
|
You can change the behavior of
|
|
.B ld\c
|
|
\& with the environment variable \c
|
|
.B GNUTARGET\c
|
|
\&.
|
|
|
|
\c
|
|
.B GNUTARGET\c
|
|
\& determines the input-file object format if you don't
|
|
use \c
|
|
.B \-b\c
|
|
\& (or its synonym \c
|
|
.B \-format\c
|
|
\&). Its value should be one
|
|
of the BFD names for an input format. If there is no
|
|
\c
|
|
.B GNUTARGET\c
|
|
\& in the environment, \c
|
|
.B ld\c
|
|
\& uses the natural format
|
|
of the host. If \c
|
|
.B GNUTARGET\c
|
|
\& is set to \c
|
|
.B default\c
|
|
\& 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 flag 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.
|
|
|
|
.PP
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR objdump ( 1 )
|
|
.br
|
|
.br
|
|
.RB "`\|" ld "\|' and `\|" binutils "\|'"
|
|
entries in
|
|
.B info\c
|
|
.br
|
|
.I
|
|
ld: the GNU linker\c
|
|
, Steve Chamberlain and Roland Pesch;
|
|
.I
|
|
The GNU Binary Utilities\c
|
|
, Roland H. Pesch.
|
|
|
|
.SH COPYING
|
|
Copyright (c) 1991, 1992 Free Software Foundation, Inc.
|
|
.PP
|
|
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.
|
|
.PP
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided that the
|
|
entire resulting derived work is distributed under the terms of a
|
|
permission notice identical to this one.
|
|
.PP
|
|
Permission is granted to copy and distribute translations of this
|
|
manual into another language, under the above conditions for modified
|
|
versions, except that this permission notice may be included in
|
|
translations approved by the Free Software Foundation instead of in
|
|
the original English.
|