1669 lines
67 KiB
Groff
1669 lines
67 KiB
Groff
.rn '' }`
|
|
''' $RCSfile$$Revision$$Date$
|
|
'''
|
|
''' $Log$
|
|
''' Revision 1.9 2001/03/25 20:32:31 nickc
|
|
''' Automate generate on man pages
|
|
'''
|
|
'''
|
|
.de Sh
|
|
.br
|
|
.if t .Sp
|
|
.ne 5
|
|
.PP
|
|
\fB\\$1\fR
|
|
.PP
|
|
..
|
|
.de Sp
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Ip
|
|
.br
|
|
.ie \\n(.$>=3 .ne \\$3
|
|
.el .ne 3
|
|
.IP "\\$1" \\$2
|
|
..
|
|
.de Vb
|
|
.ft CW
|
|
.nf
|
|
.ne \\$1
|
|
..
|
|
.de Ve
|
|
.ft R
|
|
|
|
.fi
|
|
..
|
|
'''
|
|
'''
|
|
''' Set up \*(-- to give an unbreakable dash;
|
|
''' string Tr holds user defined translation string.
|
|
''' Bell System Logo is used as a dummy character.
|
|
'''
|
|
.tr \(*W-|\(bv\*(Tr
|
|
.ie n \{\
|
|
.ds -- \(*W-
|
|
.ds PI pi
|
|
.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
|
.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
|
.ds L" ""
|
|
.ds R" ""
|
|
''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
|
|
''' \*(L" and \*(R", except that they are used on ".xx" lines,
|
|
''' such as .IP and .SH, which do another additional levels of
|
|
''' double-quote interpretation
|
|
.ds M" """
|
|
.ds S" """
|
|
.ds N" """""
|
|
.ds T" """""
|
|
.ds L' '
|
|
.ds R' '
|
|
.ds M' '
|
|
.ds S' '
|
|
.ds N' '
|
|
.ds T' '
|
|
'br\}
|
|
.el\{\
|
|
.ds -- \(em\|
|
|
.tr \*(Tr
|
|
.ds L" ``
|
|
.ds R" ''
|
|
.ds M" ``
|
|
.ds S" ''
|
|
.ds N" ``
|
|
.ds T" ''
|
|
.ds L' `
|
|
.ds R' '
|
|
.ds M' `
|
|
.ds S' '
|
|
.ds N' `
|
|
.ds T' '
|
|
.ds PI \(*p
|
|
'br\}
|
|
.\" If the F register is turned on, we'll generate
|
|
.\" index entries out stderr for the following things:
|
|
.\" TH Title
|
|
.\" SH Header
|
|
.\" Sh Subsection
|
|
.\" Ip Item
|
|
.\" X<> Xref (embedded
|
|
.\" Of course, you have to process the output yourself
|
|
.\" in some meaninful fashion.
|
|
.if \nF \{
|
|
.de IX
|
|
.tm Index:\\$1\t\\n%\t"\\$2"
|
|
..
|
|
.nr % 0
|
|
.rr F
|
|
.\}
|
|
.TH LD 1 "binutils-2.11.90" "23/Mar/101" "GNU"
|
|
.UC
|
|
.if n .hy 0
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
|
.de CQ \" put $1 in typewriter font
|
|
.ft CW
|
|
'if n "\c
|
|
'if t \\&\\$1\c
|
|
'if n \\&\\$1\c
|
|
'if n \&"
|
|
\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
|
|
'.ft R
|
|
..
|
|
.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
|
|
. \" AM - accent mark definitions
|
|
.bd B 3
|
|
. \" fudge factors for nroff and troff
|
|
.if n \{\
|
|
. ds #H 0
|
|
. ds #V .8m
|
|
. ds #F .3m
|
|
. ds #[ \f1
|
|
. ds #] \fP
|
|
.\}
|
|
.if t \{\
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
|
. ds #V .6m
|
|
. ds #F 0
|
|
. ds #[ \&
|
|
. ds #] \&
|
|
.\}
|
|
. \" simple accents for nroff and troff
|
|
.if n \{\
|
|
. ds ' \&
|
|
. ds ` \&
|
|
. ds ^ \&
|
|
. ds , \&
|
|
. ds ~ ~
|
|
. ds ? ?
|
|
. ds ! !
|
|
. ds /
|
|
. ds q
|
|
.\}
|
|
.if t \{\
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
|
. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
|
|
. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
|
. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
|
|
.\}
|
|
. \" troff and (daisy-wheel) nroff accents
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
|
.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
|
|
.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
|
|
.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
|
|
.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
|
.ds oe o\h'-(\w'o'u*4/10)'e
|
|
.ds Oe O\h'-(\w'O'u*4/10)'E
|
|
. \" corrections for vroff
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
|
. \" for low resolution devices (crt and lpr)
|
|
.if \n(.H>23 .if \n(.V>19 \
|
|
\{\
|
|
. ds : e
|
|
. ds 8 ss
|
|
. ds v \h'-1'\o'\(aa\(ga'
|
|
. ds _ \h'-1'^
|
|
. ds . \h'-1'.
|
|
. ds 3 3
|
|
. ds o a
|
|
. ds d- d\h'-1'\(ga
|
|
. ds D- D\h'-1'\(hy
|
|
. ds th \o'bp'
|
|
. ds Th \o'LP'
|
|
. ds ae ae
|
|
. ds Ae AE
|
|
. ds oe oe
|
|
. ds Oe OE
|
|
.\}
|
|
.rm #[ #] #H #V #F C
|
|
.SH "NAME"
|
|
ld \- Using LD, the GNU linker
|
|
.SH "SYNOPSIS"
|
|
ld [ options ] objfile...
|
|
.SH "DESCRIPTION"
|
|
\f(CWld\fR 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 \f(CWld\fR.
|
|
.PP
|
|
\f(CWld\fR 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.
|
|
.PP
|
|
This man page does not describe the command language; see the
|
|
\f(CWld\fR entry in \f(CWinfo\fR, or the manual
|
|
ld: the GNU linker, for full details on the command language and
|
|
on other aspects of the GNU linker.
|
|
.PP
|
|
This version of \f(CWld\fR uses the general purpose BFD libraries
|
|
to operate on object files. This allows \f(CWld\fR to read, combine, and
|
|
write object files in many different formats---for example, COFF or
|
|
\f(CWa.out\fR. Different formats may be linked together to produce any
|
|
available kind of object file.
|
|
.PP
|
|
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,
|
|
\f(CWld\fR continues executing, allowing you to identify other errors
|
|
(or, in some cases, to get an output file in spite of the error).
|
|
.PP
|
|
The GNU linker \f(CWld\fR 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.
|
|
.SH "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 \f(CWld\fR is to link standard Unix
|
|
object files on a standard, supported Unix system. On such a system, to
|
|
link a file \f(CWhello.o\fR:
|
|
.PP
|
|
.Vb 2
|
|
\&
|
|
\& ld -o I<output> /lib/crt0.o hello.o -lc
|
|
.Ve
|
|
This tells \f(CWld\fR to produce a file called \fIoutput\fR as the
|
|
result of linking the file \f(CW/lib/crt0.o\fR with \f(CWhello.o\fR and
|
|
the library \f(CWlibc.a\fR, which will come from the standard search
|
|
directories. (See the discussion of the \fB\-l\fR option below.)
|
|
.PP
|
|
Some of the command-line options to \f(CWld\fR may be specified at any
|
|
point in the command line. However, options which refer to files, such
|
|
as \fB\-l\fR or \fB\-T\fR, 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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
Usually the linker is invoked with at least one object file, but you can
|
|
specify other forms of binary input files using \fB\-l\fR, \fB\-R\fR,
|
|
and the script command language. If \fIno\fR binary input files at all
|
|
are specified, the linker does not produce any output, and issues the
|
|
message \fBNo input files\fR.
|
|
.PP
|
|
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 \fB\-T\fR). 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
|
|
\f(CWINPUT\fR or \f(CWGROUP\fR 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 \f(CWSECTIONS\fR or \f(CWMEMORY\fR command, you
|
|
must replace the default linker script using the \fB\-T\fR option.
|
|
.PP
|
|
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.
|
|
.PP
|
|
For options whose names are multiple letters, either one dash or two can
|
|
precede the option name; for example, \fB\-trace-symbol\fR and
|
|
\fB--trace-symbol\fR are equivalent. Note \- there is one exception to
|
|
this rule. Multiple letter options that start with a lower case \*(L'o\*(R' can
|
|
only be preceeded by two dashes. This is to reduce confusion with the
|
|
\fB\-o\fR option. So for example \fB\-omagic\fR sets the output file
|
|
name to \fBmagic\fR whereas \fB--omagic\fR sets the NMAGIC flag on the
|
|
output.
|
|
.PP
|
|
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,
|
|
\fB--trace-symbol foo\fR and \fB--trace-symbol=foo\fR are equivalent.
|
|
Unique abbreviations of the names of multiple-letter options are
|
|
accepted.
|
|
.PP
|
|
Note \- if the linker is being invoked indirectly, via a compiler driver
|
|
(eg \fBgcc\fR) then all the linker command line options should be
|
|
prefixed by \fB\-Wl,\fR (or whatever is appropriate for the particular
|
|
compiler driver) like this:
|
|
.PP
|
|
.Vb 2
|
|
\&
|
|
\& gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
|
|
.Ve
|
|
This is important, because otherwise the compiler driver program may
|
|
silently drop the linker options, resulting in a bad link.
|
|
.PP
|
|
Here is a table of the generic command line switches accepted by the GNU
|
|
linker:
|
|
.Ip "\f(CW-a\fIkeyword\fR\fR" 4
|
|
This option is supported for \s-1HP/UX\s0 compatibility. The \fIkeyword\fR
|
|
argument must be one of the strings \fBarchive\fR, \fBshared\fR, or
|
|
\fBdefault\fR. \fB\-aarchive\fR is functionally equivalent to
|
|
\fB\-Bstatic\fR, and the other two keywords are functionally equivalent
|
|
to \fB\-Bdynamic\fR. This option may be used any number of times.
|
|
.Ip "\f(CW-A\fIarchitecture\fR\fR" 4
|
|
.Ip "\f(CW--architecture=\fIarchitecture\fR\fR" 4
|
|
In the current release of \f(CWld\fR, this option is useful only for the
|
|
Intel 960 family of architectures. In that \f(CWld\fR configuration, the
|
|
\fIarchitecture\fR argument identifies the particular architecture in
|
|
the 960 family, enabling some safeguards and modifying the
|
|
archive-library search path.
|
|
.Sp
|
|
Future releases of \f(CWld\fR may support similar functionality for
|
|
other architecture families.
|
|
.Ip "\f(CW-b \fIinput-format\fR\fR" 4
|
|
.Ip "\f(CW--format=\fIinput-format\fR\fR" 4
|
|
\f(CWld\fR may be configured to support more than one kind of object
|
|
file. If your \f(CWld\fR is configured this way, you can use the
|
|
\fB\-b\fR option to specify the binary format for input object files
|
|
that follow this option on the command line. Even when \f(CWld\fR is
|
|
configured to support alternative object formats, you don't usually need
|
|
to specify this, as \f(CWld\fR should be configured to expect as a
|
|
default input format the most usual format on each machine.
|
|
\fIinput-format\fR is a text string, the name of a particular format
|
|
supported by the \s-1BFD\s0 libraries. (You can list the available binary
|
|
formats with \fBobjdump \-i\fR.)
|
|
.Sp
|
|
You may want to use this option if you are linking files with an unusual
|
|
binary format. You can also use \fB\-b\fR to switch formats explicitly (when
|
|
linking object files of different formats), by including
|
|
\fB\-b\fR \fIinput-format\fR before each group of object files in a
|
|
particular format.
|
|
.Sp
|
|
The default format is taken from the environment variable
|
|
\f(CWGNUTARGET\fR.
|
|
.Sp
|
|
You can also define the input format from a script, using the command
|
|
\f(CWTARGET\fR;
|
|
.Ip "\f(CW-c \fIMRI-commandfile\fR\fR" 4
|
|
.Ip "\f(CW--mri-script=\fIMRI-commandfile\fR\fR" 4
|
|
For compatibility with linkers produced by \s-1MRI\s0, \f(CWld\fR accepts script
|
|
files written in an alternate, restricted command language, described in
|
|
the \s-1MRI\s0 Compatible Script Files section of \s-1GNU\s0 ld documentation.
|
|
Introduce \s-1MRI\s0 script files with
|
|
the option \fB\-c\fR; use the \fB\-T\fR option to run linker
|
|
scripts written in the general-purpose \f(CWld\fR scripting language.
|
|
If \fI\s-1MRI\s0\-cmdfile\fR does not exist, \f(CWld\fR looks for it in the directories
|
|
specified by any \fB\-L\fR options.
|
|
.Ip "\f(CW-d\fR" 4
|
|
.Ip "\f(CW-dc\fR" 4
|
|
.Ip "\f(CW-dp\fR" 4
|
|
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 \fB\-r\fR). The
|
|
script command \f(CWFORCE_COMMON_ALLOCATION\fR has the same effect.
|
|
.Ip "\f(CW-e \fIentry\fR\fR" 4
|
|
.Ip "\f(CW--entry=\fIentry\fR\fR" 4
|
|
Use \fIentry\fR as the explicit symbol for beginning execution of your
|
|
program, rather than the default entry point. If there is no symbol
|
|
named \fIentry\fR, the linker will try to parse \fIentry\fR as a number,
|
|
and use that as the entry address (the number will be interpreted in
|
|
base 10; you may use a leading \fB0x\fR for base 16, or a leading
|
|
\fB0\fR for base 8).
|
|
.Ip "\f(CW-E\fR" 4
|
|
.Ip "\f(CW--export-dynamic\fR" 4
|
|
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.
|
|
.Sp
|
|
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.
|
|
.Sp
|
|
If you use \f(CWdlopen\fR 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.
|
|
.Ip "\f(CW-EB\fR" 4
|
|
Link big-endian objects. This affects the default output format.
|
|
.Ip "\f(CW-EL\fR" 4
|
|
Link little-endian objects. This affects the default output format.
|
|
.Ip "\f(CW-f\fR" 4
|
|
.Ip "\f(CW--auxiliary \fIname\fR\fR" 4
|
|
When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_AUXILIARY\s0 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 \fIname\fR.
|
|
.Sp
|
|
If you later link a program against this filter object, then, when you
|
|
run the program, the dynamic linker will see the \s-1DT_AUXILIARY\s0 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
|
|
\fIname\fR. If there is one, it will be used instead of the definition
|
|
in the filter object. The shared object \fIname\fR need not exist.
|
|
Thus the shared object \fIname\fR may be used to provide an alternative
|
|
implementation of certain functions, perhaps for debugging or for
|
|
machine specific performance.
|
|
.Sp
|
|
This option may be specified more than once. The \s-1DT_AUXILIARY\s0 entries
|
|
will be created in the order in which they appear on the command line.
|
|
.Ip "\f(CW-F \fIname\fR\fR" 4
|
|
.Ip "\f(CW--filter \fIname\fR\fR" 4
|
|
When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_FILTER\s0 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 \fIname\fR.
|
|
.Sp
|
|
If you later link a program against this filter object, then, when you
|
|
run the program, the dynamic linker will see the \s-1DT_FILTER\s0 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 \fIname\fR. Thus the filter object can be
|
|
used to select a subset of the symbols provided by the object
|
|
\fIname\fR.
|
|
.Sp
|
|
Some older linkers used the \f(CW-F\fR option throughout a compilation
|
|
toolchain for specifying object-file format for both input and output
|
|
object files. The \s-1GNU\s0 linker uses other mechanisms for this
|
|
purpose: the \f(CW-b\fR, \f(CW--format\fR, \f(CW--oformat\fR options, the
|
|
\f(CWTARGET\fR command in linker scripts, and the \f(CWGNUTARGET\fR
|
|
environment variable. The \s-1GNU\s0 linker will ignore the \f(CW-F\fR
|
|
option when not creating an \s-1ELF\s0 shared object.
|
|
.Ip "\f(CW-fini \fIname\fR\fR" 4
|
|
When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the
|
|
executable or shared object is unloaded, by setting \s-1DT_FINI\s0 to the
|
|
address of the function. By default, the linker uses \f(CW_fini\fR as
|
|
the function to call.
|
|
.Ip "\f(CW-g\fR" 4
|
|
Ignored. Provided for compatibility with other tools.
|
|
.Ip "\f(CW-G\fIvalue\fR\fR" 4
|
|
.Ip "\f(CW--gpsize=\fIvalue\fR\fR" 4
|
|
Set the maximum size of objects to be optimized using the \s-1GP\s0 register to
|
|
\fIsize\fR. This is only meaningful for object file formats such as
|
|
\s-1MIPS\s0 \s-1ECOFF\s0 which supports putting large and small objects into different
|
|
sections. This is ignored for other object file formats.
|
|
.Ip "\f(CW-h\fIname\fR\fR" 4
|
|
.Ip "\f(CW-soname=\fIname\fR\fR" 4
|
|
When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_SONAME\s0 field to
|
|
the specified name. When an executable is linked with a shared object
|
|
which has a \s-1DT_SONAME\s0 field, then when the executable is run the dynamic
|
|
linker will attempt to load the shared object specified by the \s-1DT_SONAME\s0
|
|
field rather than the using the file name given to the linker.
|
|
.Ip "\f(CW-i\fR" 4
|
|
Perform an incremental link (same as option \fB\-r\fR).
|
|
.Ip "\f(CW-init \fIname\fR\fR" 4
|
|
When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the
|
|
executable or shared object is loaded, by setting \s-1DT_INIT\s0 to the address
|
|
of the function. By default, the linker uses \f(CW_init\fR as the
|
|
function to call.
|
|
.Ip "\f(CW-l\fIarchive\fR\fR" 4
|
|
.Ip "\f(CW--library=\fIarchive\fR\fR" 4
|
|
Add archive file \fIarchive\fR to the list of files to link. This
|
|
option may be used any number of times. \f(CWld\fR will search its
|
|
path-list for occurrences of \f(CWlib\fIarchive\fR.a\fR for every
|
|
\fIarchive\fR specified.
|
|
.Sp
|
|
On systems which support shared libraries, \f(CWld\fR may also search for
|
|
libraries with extensions other than \f(CW.a\fR. Specifically, on \s-1ELF\s0
|
|
and SunOS systems, \f(CWld\fR will search a directory for a library with
|
|
an extension of \f(CW.so\fR before searching for one with an extension of
|
|
\&\f(CW.a\fR. By convention, a \f(CW.so\fR extension indicates a shared
|
|
library.
|
|
.Sp
|
|
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 \fIfile\fR\|(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.
|
|
.Sp
|
|
See the \f(CW-(\fR option for a way to force the linker to search
|
|
archives multiple times.
|
|
.Sp
|
|
You may list the same archive multiple times on the command line.
|
|
.Sp
|
|
This type of archive searching is standard for Unix linkers. However,
|
|
if you are using \f(CWld\fR on \s-1AIX\s0, note that it is different from the
|
|
behaviour of the \s-1AIX\s0 linker.
|
|
.Ip "\f(CW-L\fIsearchdir\fR\fR" 4
|
|
.Ip "\f(CW--library-path=\fIsearchdir\fR\fR" 4
|
|
Add path \fIsearchdir\fR to the list of paths that \f(CWld\fR will search
|
|
for archive libraries and \f(CWld\fR 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
|
|
\f(CW-L\fR options apply to all \f(CW-l\fR options, regardless of the
|
|
order in which the options appear.
|
|
.Sp
|
|
The default set of paths searched (without being specified with
|
|
\fB\-L\fR) depends on which emulation mode \f(CWld\fR is using, and in
|
|
some cases also on how it was configured.
|
|
.Sp
|
|
The paths can also be specified in a link script with the
|
|
\f(CWSEARCH_DIR\fR command. Directories specified this way are searched
|
|
at the point in which the linker script appears in the command line.
|
|
.Ip "\f(CW-m\fIemulation\fR\fR" 4
|
|
Emulate the \fIemulation\fR linker. You can list the available
|
|
emulations with the \fB--verbose\fR or \fB\-V\fR options.
|
|
.Sp
|
|
If the \fB\-m\fR option is not used, the emulation is taken from the
|
|
\f(CWLDEMULATION\fR environment variable, if that is defined.
|
|
.Sp
|
|
Otherwise, the default emulation depends upon how the linker was
|
|
configured.
|
|
.Ip "\f(CW-M\fR" 4
|
|
.Ip "\f(CW--print-map\fR" 4
|
|
Print a link map to the standard output. A link map provides
|
|
information about the link, including the following:
|
|
.Ip "\(bu" 8
|
|
Where object files and symbols are mapped into memory.
|
|
.Ip "\(bu" 8
|
|
How common symbols are allocated.
|
|
.Ip "\(bu" 8
|
|
All archive members included in the link, with a mention of the symbol
|
|
which caused the archive member to be brought in.
|
|
.Ip "\f(CW-n\fR" 4
|
|
.Ip "\f(CW--nmagic\fR" 4
|
|
Turn off page alignment of sections, and mark the output as
|
|
\f(CWNMAGIC\fR if possible.
|
|
.Ip "\f(CW-N\fR" 4
|
|
.Ip "\f(CW--omagic\fR" 4
|
|
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 \f(CWOMAGIC\fR.
|
|
.Ip "\f(CW-o \fIoutput\fR\fR" 4
|
|
.Ip "\f(CW--output=\fIoutput\fR\fR" 4
|
|
Use \fIoutput\fR as the name for the program produced by \f(CWld\fR; if this
|
|
option is not specified, the name \fIa.out\fR is used by default. The
|
|
script command \f(CWOUTPUT\fR can also specify the output file name.
|
|
.Ip "\f(CW-O \fIlevel\fR\fR" 4
|
|
If \fIlevel\fR is a numeric values greater than zero \f(CWld\fR optimizes
|
|
the output. This might take significantly longer and therefore probably
|
|
should only be enabled for the final binary.
|
|
.Ip "\f(CW-q\fR" 4
|
|
.Ip "\f(CW--emit-relocs\fR" 4
|
|
Leave relocation sections and contents in fully linked exececutables.
|
|
Post link analysis and optimization tools may need this information in
|
|
order to perform correct modifications of executables. This results
|
|
in larger executables.
|
|
.Ip "\f(CW-r\fR" 4
|
|
.Ip "\f(CW--relocateable\fR" 4
|
|
Generate relocatable output---i.e., generate an output file that can in
|
|
turn serve as input to \f(CWld\fR. This is often called \fIpartial
|
|
linking\fR. As a side effect, in environments that support standard Unix
|
|
magic numbers, this option also sets the output file's magic number to
|
|
\f(CWOMAGIC\fR.
|
|
If this option is not specified, an absolute file is produced. When
|
|
linking \*(C+ programs, this option \fIwill not\fR resolve references to
|
|
constructors; to do that, use \fB\-Ur\fR.
|
|
.Sp
|
|
This option does the same thing as \fB\-i\fR.
|
|
.Ip "\f(CW-R \fIfilename\fR\fR" 4
|
|
.Ip "\f(CW--just-symbols=\fIfilename\fR\fR" 4
|
|
Read symbol names and their addresses from \fIfilename\fR, 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.
|
|
.Sp
|
|
For compatibility with other \s-1ELF\s0 linkers, if the \f(CW-R\fR option is
|
|
followed by a directory name, rather than a file name, it is treated as
|
|
the \f(CW-rpath\fR option.
|
|
.Ip "\f(CW-s\fR" 4
|
|
.Ip "\f(CW--strip-all\fR" 4
|
|
Omit all symbol information from the output file.
|
|
.Ip "\f(CW-S\fR" 4
|
|
.Ip "\f(CW--strip-debug\fR" 4
|
|
Omit debugger symbol information (but not all symbols) from the output file.
|
|
.Ip "\f(CW-t\fR" 4
|
|
.Ip "\f(CW--trace\fR" 4
|
|
Print the names of the input files as \f(CWld\fR processes them.
|
|
.Ip "\f(CW-T \fIscriptfile\fR\fR" 4
|
|
.Ip "\f(CW--script=\fIscriptfile\fR\fR" 4
|
|
Use \fIscriptfile\fR as the linker script. This script replaces
|
|
\f(CWld\fR's default linker script (rather than adding to it), so
|
|
\fIcommandfile\fR 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
|
|
\f(CWSECTIONS\fR or \f(CWMEMORY\fR command. If
|
|
\fIscriptfile\fR does not exist in the current directory, \f(CWld\fR
|
|
looks for it in the directories specified by any preceding \fB\-L\fR
|
|
options. Multiple \fB\-T\fR options accumulate.
|
|
.Ip "\f(CW-u \fIsymbol\fR\fR" 4
|
|
.Ip "\f(CW--undefined=\fIsymbol\fR\fR" 4
|
|
Force \fIsymbol\fR to be entered in the output file as an undefined
|
|
symbol. Doing this may, for example, trigger linking of additional
|
|
modules from standard libraries. \fB\-u\fR may be repeated with
|
|
different option arguments to enter additional undefined symbols. This
|
|
option is equivalent to the \f(CWEXTERN\fR linker script command.
|
|
.Ip "\f(CW-Ur\fR" 4
|
|
For anything other than \*(C+ programs, this option is equivalent to
|
|
\fB\-r\fR: it generates relocatable output---i.e., an output file that can in
|
|
turn serve as input to \f(CWld\fR. When linking \*(C+ programs, \fB\-Ur\fR
|
|
\fIdoes\fR resolve references to constructors, unlike \fB\-r\fR.
|
|
It does not work to use \fB\-Ur\fR on files that were themselves linked
|
|
with \fB\-Ur\fR; once the constructor table has been built, it cannot
|
|
be added to. Use \fB\-Ur\fR only for the last partial link, and
|
|
\fB\-r\fR for the others.
|
|
.Ip "\f(CW--unique[=\fISECTION\fR]\fR" 4
|
|
Creates a separate output section for every input section matching
|
|
\fI\s-1SECTION\s0\fR, or if the optional wildcard \fI\s-1SECTION\s0\fR argument is
|
|
missing, for every orphan input section. An orphan section is one not
|
|
specifically mentioned in a linker script. You may use this option
|
|
multiple times on the command line; It prevents the normal merging of
|
|
input sections with the same name, overriding output section assignments
|
|
in a linker script.
|
|
.Ip "\f(CW-v\fR" 4
|
|
.Ip "\f(CW--version\fR" 4
|
|
.Ip "\f(CW-V\fR" 4
|
|
Display the version number for \f(CWld\fR. The \f(CW-V\fR option also
|
|
lists the supported emulations.
|
|
.Ip "\f(CW-x\fR" 4
|
|
.Ip "\f(CW--discard-all\fR" 4
|
|
Delete all local symbols.
|
|
.Ip "\f(CW-X\fR" 4
|
|
.Ip "\f(CW--discard-locals\fR" 4
|
|
Delete all temporary local symbols. For most targets, this is all local
|
|
symbols whose names begin with \fBL\fR.
|
|
.Ip "\f(CW-y \fIsymbol\fR\fR" 4
|
|
.Ip "\f(CW--trace-symbol=\fIsymbol\fR\fR" 4
|
|
Print the name of each linked file in which \fIsymbol\fR appears. This
|
|
option may be given any number of times. On many systems it is necessary
|
|
to prepend an underscore.
|
|
.Sp
|
|
This option is useful when you have an undefined symbol in your link but
|
|
don't know where the reference is coming from.
|
|
.Ip "\f(CW-Y \fIpath\fR\fR" 4
|
|
Add \fIpath\fR to the default library search path. This option exists
|
|
for Solaris compatibility.
|
|
.Ip "\f(CW-z \fIkeyword\fR\fR" 4
|
|
The recognized keywords are \f(CWinitfirst\fR, \f(CWinterpose\fR,
|
|
\f(CWloadfltr\fR, \f(CWnodefaultlib\fR, \f(CWnodelete\fR, \f(CWnodlopen\fR,
|
|
\f(CWnodump\fR, \f(CWnow\fR and \f(CWorigin\fR. The other keywords are
|
|
ignored for Solaris compatibility. \f(CWinitfirst\fR marks the object
|
|
to be initialized first at runtime before any other objects.
|
|
\f(CWinterpose\fR marks the object that its symbol table interposes
|
|
before all symbols but the primary executable. \f(CWloadfltr\fR marks
|
|
the object that its filtees be processed immediately at runtime.
|
|
\f(CWnodefaultlib\fR marks the object that the search for dependencies
|
|
of this object will ignore any default library search paths.
|
|
\f(CWnodelete\fR marks the object shouldn't be unloaded at runtime.
|
|
\f(CWnodlopen\fR marks the object not available to \f(CWdlopen\fR.
|
|
\f(CWnodump\fR marks the object can not be dumped by \f(CWdldump\fR.
|
|
\f(CWnow\fR marks the object with the non-lazy runtime binding.
|
|
\f(CWorigin\fR marks the object may contain \f(CW$ORIGIN\fR.
|
|
\f(CWdefs\fR disallows undefined symbols.
|
|
.Ip "\f(CW-( \fIarchives\fR -)\fR" 4
|
|
.Ip "\f(CW--start-group \fIarchives\fR --end-group\fR" 4
|
|
The \fIarchives\fR should be a list of archive files. They may be
|
|
either explicit file names, or \fB\-l\fR options.
|
|
.Sp
|
|
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.
|
|
.Sp
|
|
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.
|
|
.Ip "\f(CW-assert \fIkeyword\fR\fR" 4
|
|
This option is ignored for SunOS compatibility.
|
|
.Ip "\f(CW-Bdynamic\fR" 4
|
|
.Ip "\f(CW-dy\fR" 4
|
|
.Ip "\f(CW-call_shared\fR" 4
|
|
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
|
|
\f(CW-l\fR options which follow it.
|
|
.Ip "\f(CW-Bgroup\fR" 4
|
|
Set the \f(CWDF_1_GROUP\fR flag in the \f(CWDT_FLAGS_1\fR entry in the dynamic
|
|
section. This causes the runtime linker to handle lookups in this
|
|
object and its dependencies to be performed only inside the group.
|
|
\f(CW--no-undefined\fR is implied. This option is only meaningful on \s-1ELF\s0
|
|
platforms which support shared libraries.
|
|
.Ip "\f(CW-Bstatic\fR" 4
|
|
.Ip "\f(CW-dn\fR" 4
|
|
.Ip "\f(CW-non_shared\fR" 4
|
|
.Ip "\f(CW-static\fR" 4
|
|
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 \f(CW-l\fR options which follow it.
|
|
.Ip "\f(CW-Bsymbolic\fR" 4
|
|
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 \s-1ELF\s0
|
|
platforms which support shared libraries.
|
|
.Ip "\f(CW--check-sections\fR" 4
|
|
.Ip "\f(CW--no-check-sections\fR" 4
|
|
Asks the linker \fInot\fR 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 \fB--check-sections\fR.
|
|
.Ip "\f(CW--cref\fR" 4
|
|
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.
|
|
.Sp
|
|
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.
|
|
.Ip "\f(CW--defsym \fIsymbol\fR=\fIexpression\fR\fR" 4
|
|
Create a global symbol in the output file, containing the absolute
|
|
address given by \fIexpression\fR. 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 \fIexpression\fR in this
|
|
context: you may give a hexadecimal constant or the name of an existing
|
|
symbol, or use \f(CW+\fR and \f(CW-\fR to add or subtract hexadecimal
|
|
constants or symbols. If you need more elaborate expressions, consider
|
|
using the linker command language from a script. \fINote:\fR there should be no white
|
|
space between \fIsymbol\fR, the equals sign (``\fB=\fR''), and
|
|
\fIexpression\fR.
|
|
.Ip "\f(CW--demangle[=\fIstyle\fR]\fR" 4
|
|
.Ip "\f(CW--no-demangle\fR" 4
|
|
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. Different compilers have
|
|
different mangling styles. The optional demangling style argument can be used
|
|
to choose an appropriate demangling style for your compiler. The linker will
|
|
demangle by default unless the environment variable \fB\s-1COLLECT_NO_DEMANGLE\s0\fR
|
|
is set. These options may be used to override the default.
|
|
.Ip "\f(CW--dynamic-linker \fIfile\fR\fR" 4
|
|
Set the name of the dynamic linker. This is only meaningful when
|
|
generating dynamically linked \s-1ELF\s0 executables. The default dynamic
|
|
linker is normally correct; don't use this unless you know what you are
|
|
doing.
|
|
.Ip "\f(CW--embedded-relocs\fR" 4
|
|
This option is only meaningful when linking \s-1MIPS\s0 embedded \s-1PIC\s0 code,
|
|
generated by the \-membedded-pic option to the \s-1GNU\s0 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.
|
|
.Ip "\f(CW--force-exe-suffix\fR" 4
|
|
Make sure that an output file has a .exe suffix.
|
|
.Sp
|
|
If a successfully built fully linked output file does not have a
|
|
\&\f(CW.exe\fR or \f(CW.dll\fR suffix, this option forces the linker to copy
|
|
the output file to one of the same name with a \f(CW.exe\fR 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 \f(CW.exe\fR suffix.
|
|
.Ip "\f(CW--no-gc-sections\fR" 4
|
|
.Ip "\f(CW--gc-sections\fR" 4
|
|
Enable garbage collection of unused input sections. It is ignored on
|
|
targets that do not support this option. This option is not compatible
|
|
with \fB\-r\fR, nor should it be used with dynamic linking. The default
|
|
behaviour (of not performing this garbage collection) can be restored by
|
|
specifying \fB--no-gc-sections\fR on the command line.
|
|
.Ip "\f(CW--help\fR" 4
|
|
Print a summary of the command-line options on the standard output and exit.
|
|
.Ip "\f(CW--target-help\fR" 4
|
|
Print a summary of all target specific options on the standard output and exit.
|
|
.Ip "\f(CW-Map \fImapfile\fR\fR" 4
|
|
Print a link map to the file \fImapfile\fR. See the description of the
|
|
\fB\-M\fR option, above.
|
|
.Ip "\f(CW--no-keep-memory\fR" 4
|
|
\f(CWld\fR normally optimizes for speed over memory usage by caching the
|
|
symbol tables of input files in memory. This option tells \f(CWld\fR to
|
|
instead optimize for memory usage, by rereading the symbol tables as
|
|
necessary. This may be required if \f(CWld\fR runs out of memory space
|
|
while linking a large executable.
|
|
.Ip "\f(CW--no-undefined\fR" 4
|
|
.Ip "\f(CW-z defs\fR" 4
|
|
Normally when creating a non-symbolic shared library, undefined symbols
|
|
are allowed and left to be resolved by the runtime loader. These options
|
|
disallows such undefined symbols.
|
|
.Ip "\f(CW--allow-shlib-undefined\fR" 4
|
|
Allow undefined symbols in shared objects even when --no-undefined is
|
|
set. The net result will be that undefined symbols in regular objects
|
|
will still trigger an error, but undefined symbols in shared objects
|
|
will be ignored. The implementation of no_undefined makes the
|
|
assumption that the runtime linker will choke on undefined symbols.
|
|
However there is at least one system (BeOS) where undefined symbols in
|
|
shared libraries is normal since the kernel patches them at load time to
|
|
select which function is most appropriate for the current architecture.
|
|
I.E. dynamically select an appropriate memset function. Apparently it
|
|
is also normal for \s-1HPPA\s0 shared libraries to have undefined symbols.
|
|
.Ip "\f(CW--no-warn-mismatch\fR" 4
|
|
Normally \f(CWld\fR 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 \f(CWld\fR 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.
|
|
.Ip "\f(CW--no-whole-archive\fR" 4
|
|
Turn off the effect of the \f(CW--whole-archive\fR option for subsequent
|
|
archive files.
|
|
.Ip "\f(CW--noinhibit-exec\fR" 4
|
|
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.
|
|
.Ip "\f(CW--oformat \fIoutput-format\fR\fR" 4
|
|
\f(CWld\fR may be configured to support more than one kind of object
|
|
file. If your \f(CWld\fR is configured this way, you can use the
|
|
\fB--oformat\fR option to specify the binary format for the output
|
|
object file. Even when \f(CWld\fR is configured to support alternative
|
|
object formats, you don't usually need to specify this, as \f(CWld\fR
|
|
should be configured to produce as a default output format the most
|
|
usual format on each machine. \fIoutput-format\fR is a text string, the
|
|
name of a particular format supported by the \s-1BFD\s0 libraries. (You can
|
|
list the available binary formats with \fBobjdump \-i\fR.) The script
|
|
command \f(CWOUTPUT_FORMAT\fR can also specify the output format, but
|
|
this option overrides it.
|
|
.Ip "\f(CW-qmagic\fR" 4
|
|
This option is ignored for Linux compatibility.
|
|
.Ip "\f(CW-Qy\fR" 4
|
|
This option is ignored for \s-1SVR4\s0 compatibility.
|
|
.Ip "\f(CW--relax\fR" 4
|
|
An option with machine dependent effects.
|
|
This option is only supported on a few targets.
|
|
.Sp
|
|
On some platforms, the \fB--relax\fR 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.
|
|
.Sp
|
|
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 \s-1MN10200\s0 and \s-1MN10300\s0 family of processors.
|
|
.Sp
|
|
On platforms where this is not supported, \fB--relax\fR is accepted,
|
|
but ignored.
|
|
.Ip "\f(CW--retain-symbols-file \fIfilename\fR\fR" 4
|
|
Retain \fIonly\fR the symbols listed in the file \fIfilename\fR,
|
|
discarding all others. \fIfilename\fR 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.
|
|
.Sp
|
|
\fB--retain-symbols-file\fR does \fInot\fR discard undefined symbols,
|
|
or symbols needed for relocations.
|
|
.Sp
|
|
You may only specify \fB--retain-symbols-file\fR once in the command
|
|
line. It overrides \fB\-s\fR and \fB\-S\fR.
|
|
.Ip "\f(CW-rpath \fIdir\fR\fR" 4
|
|
Add a directory to the runtime library search path. This is used when
|
|
linking an \s-1ELF\s0 executable with shared objects. All \f(CW-rpath\fR
|
|
arguments are concatenated and passed to the runtime linker, which uses
|
|
them to locate shared objects at runtime. The \f(CW-rpath\fR option is
|
|
also used when locating shared objects which are needed by shared
|
|
objects explicitly included in the link; see the description of the
|
|
\f(CW-rpath-link\fR option. If \f(CW-rpath\fR is not used when linking an
|
|
\s-1ELF\s0 executable, the contents of the environment variable
|
|
\f(CWLD_RUN_PATH\fR will be used if it is defined.
|
|
.Sp
|
|
The \f(CW-rpath\fR option may also be used on SunOS. By default, on
|
|
SunOS, the linker will form a runtime search patch out of all the
|
|
\f(CW-L\fR options it is given. If a \f(CW-rpath\fR option is used, the
|
|
runtime search path will be formed exclusively using the \f(CW-rpath\fR
|
|
options, ignoring the \f(CW-L\fR options. This can be useful when using
|
|
gcc, which adds many \f(CW-L\fR options which may be on \s-1NFS\s0 mounted
|
|
filesystems.
|
|
.Sp
|
|
For compatibility with other \s-1ELF\s0 linkers, if the \f(CW-R\fR option is
|
|
followed by a directory name, rather than a file name, it is treated as
|
|
the \f(CW-rpath\fR option.
|
|
.Ip "\f(CW-rpath-link \fIDIR\fR\fR" 4
|
|
When using \s-1ELF\s0 or SunOS, one shared library may require another. This
|
|
happens when an \f(CWld -shared\fR link includes a shared library as one
|
|
of the input files.
|
|
.Sp
|
|
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 \f(CW-rpath-link\fR option
|
|
specifies the first set of directories to search. The
|
|
\f(CW-rpath-link\fR option may specify a sequence of directory names
|
|
either by specifying a list of names separated by colons, or by
|
|
appearing multiple times.
|
|
.Sp
|
|
This option should be used with caution as it overrides the search path
|
|
that may have been hard compiled into a shared library. In such a case it
|
|
is possible to use unintentionally a different search path than the
|
|
runtime linker would do.
|
|
.Sp
|
|
The linker uses the following search paths to locate required shared
|
|
libraries.
|
|
.Ip "1." 8
|
|
Any directories specified by \f(CW-rpath-link\fR options.
|
|
.Ip "2." 8
|
|
Any directories specified by \f(CW-rpath\fR options. The difference
|
|
between \f(CW-rpath\fR and \f(CW-rpath-link\fR is that directories
|
|
specified by \f(CW-rpath\fR options are included in the executable and
|
|
used at runtime, whereas the \f(CW-rpath-link\fR option is only effective
|
|
at link time. It is for the native linker only.
|
|
.Ip "3." 8
|
|
On an \s-1ELF\s0 system, if the \f(CW-rpath\fR and \f(CWrpath-link\fR options
|
|
were not used, search the contents of the environment variable
|
|
\f(CWLD_RUN_PATH\fR. It is for the native linker only.
|
|
.Ip "4." 8
|
|
On SunOS, if the \f(CW-rpath\fR option was not used, search any
|
|
directories specified using \f(CW-L\fR options.
|
|
.Ip "5." 8
|
|
For a native linker, the contents of the environment variable
|
|
\f(CWLD_LIBRARY_PATH\fR.
|
|
.Ip "6." 8
|
|
For a native \s-1ELF\s0 linker, the directories in \f(CWDT_RUNPATH\fR or
|
|
\f(CWDT_RPATH\fR of a shared library are searched for shared
|
|
libraries needed by it. The \f(CWDT_RPATH\fR entries are ignored if
|
|
\f(CWDT_RUNPATH\fR entries exist.
|
|
.Ip "7." 8
|
|
The default directories, normally \fI/lib\fR and \fI/usr/lib\fR.
|
|
.Ip "8." 8
|
|
For a native linker on an \s-1ELF\s0 system, if the file \fI/etc/ld.so.conf\fR
|
|
exists, the list of directories found in that file.
|
|
.Sp
|
|
If the required shared library is not found, the linker will issue a
|
|
warning and continue with the link.
|
|
.Ip "\f(CW-shared\fR" 4
|
|
.Ip "\f(CW-Bshareable\fR" 4
|
|
Create a shared library. This is currently only supported on \s-1ELF\s0, \s-1XCOFF\s0
|
|
and SunOS platforms. On SunOS, the linker will automatically create a
|
|
shared library if the \f(CW-e\fR option is not used and there are
|
|
undefined symbols in the link.
|
|
.Ip "\f(CW--sort-common\fR" 4
|
|
This option tells \f(CWld\fR 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.
|
|
.Ip "\f(CW--split-by-file [\fIsize\fR]\fR" 4
|
|
Similar to \f(CW--split-by-reloc\fR but creates a new output section for
|
|
each input file when \fIsize\fR is reached. \fIsize\fR defaults to a
|
|
size of 1 if not given.
|
|
.Ip "\f(CW--split-by-reloc [\fIcount\fR]\fR" 4
|
|
Tries to creates extra sections in the output file so that no single
|
|
output section in the file contains more than \fIcount\fR relocations.
|
|
This is useful when generating huge relocatable files for downloading into
|
|
certain real time kernels with the \s-1COFF\s0 object file format; since \s-1COFF\s0
|
|
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 \fIcount\fR relocations one output section will contain that
|
|
many relocations. \fIcount\fR defaults to a value of 32768.
|
|
.Ip "\f(CW--stats\fR" 4
|
|
Compute and display statistics about the operation of the linker, such
|
|
as execution time and memory usage.
|
|
.Ip "\f(CW--traditional-format\fR" 4
|
|
For some targets, the output of \f(CWld\fR is different in some ways from
|
|
the output of some existing linker. This switch requests \f(CWld\fR to
|
|
use the traditional format instead.
|
|
.Sp
|
|
For example, on SunOS, \f(CWld\fR 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
|
|
\f(CWdbx\fR program can not read the resulting program (\f(CWgdb\fR has no
|
|
trouble). The \fB--traditional-format\fR switch tells \f(CWld\fR to not
|
|
combine duplicate entries.
|
|
.Ip "\f(CW--section-start \fIsectionname\fR=\fIorg\fR\fR" 4
|
|
Locate a section in the output file at the absolute
|
|
address given by \fIorg\fR. You may use this option as many
|
|
times as necessary to locate multiple sections in the command
|
|
line.
|
|
\fIorg\fR must be a single hexadecimal integer;
|
|
for compatibility with other linkers, you may omit the leading
|
|
\fB0x\fR usually associated with hexadecimal values. \fINote:\fR there
|
|
should be no white space between \fIsectionname\fR, the equals
|
|
sign (``\fB=\fR''), and \fIorg\fR.
|
|
.Ip "\f(CW-Tbss \fIorg\fR\fR" 4
|
|
.Ip "\f(CW-Tdata \fIorg\fR\fR" 4
|
|
.Ip "\f(CW-Ttext \fIorg\fR\fR" 4
|
|
Use \fIorg\fR as the starting address for---respectively---the
|
|
\f(CWbss\fR, \f(CWdata\fR, or the \f(CWtext\fR segment of the output file.
|
|
\fIorg\fR must be a single hexadecimal integer;
|
|
for compatibility with other linkers, you may omit the leading
|
|
\fB0x\fR usually associated with hexadecimal values.
|
|
.Ip "\f(CW--dll-verbose\fR" 4
|
|
.Ip "\f(CW--verbose\fR" 4
|
|
Display the version number for \f(CWld\fR 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.
|
|
.Ip "\f(CW--version-script=\fIversion-scriptfile\fR\fR" 4
|
|
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 \s-1ELF\s0 platforms which support shared libraries.
|
|
.Ip "\f(CW--warn-common\fR" 4
|
|
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.
|
|
.Sp
|
|
There are three kinds of global symbols, illustrated here by C examples:
|
|
.Ip "\fBint i = 1;\fR" 8
|
|
A definition, which goes in the initialized data section of the output
|
|
file.
|
|
.Ip "\fBextern int i;\fR" 8
|
|
An undefined reference, which does not allocate space.
|
|
There must be either a definition or a common symbol for the
|
|
variable somewhere.
|
|
.Ip "\fBint i;\fR" 8
|
|
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.
|
|
.Sp
|
|
The \fB--warn-common\fR 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.
|
|
.Ip "1." 8
|
|
Turning a common symbol into a reference, because there is already a
|
|
definition for the symbol.
|
|
|
|
\fIfile\fR(\fIsection\fR): warning: common of `\fIsymbol\fR\*(R'
|
|
overridden by definition
|
|
\fIfile\fR(\fIsection\fR): warning: defined here
|
|
.Ip "2." 8
|
|
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.
|
|
|
|
\fIfile\fR(\fIsection\fR): warning: definition of `\fIsymbol\fR\*(R'
|
|
overriding common
|
|
\fIfile\fR(\fIsection\fR): warning: common is here
|
|
.Ip "3." 8
|
|
Merging a common symbol with a previous same-sized common symbol.
|
|
|
|
\fIfile\fR(\fIsection\fR): warning: multiple common
|
|
of `\fIsymbol\fR\*(R'
|
|
\fIfile\fR(\fIsection\fR): warning: previous common is here
|
|
.Ip "4." 8
|
|
Merging a common symbol with a previous larger common symbol.
|
|
|
|
\fIfile\fR(\fIsection\fR): warning: common of `\fIsymbol\fR\*(R'
|
|
overridden by larger common
|
|
\fIfile\fR(\fIsection\fR): warning: larger common is here
|
|
.Ip "5." 8
|
|
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.
|
|
|
|
\fIfile\fR(\fIsection\fR): warning: common of `\fIsymbol\fR\*(R'
|
|
overriding smaller common
|
|
\fIfile\fR(\fIsection\fR): warning: smaller common is here
|
|
.Ip "\f(CW--warn-constructors\fR" 4
|
|
Warn if any global constructors are used. This is only useful for a few
|
|
object file formats. For formats like \s-1COFF\s0 or \s-1ELF\s0, the linker can not
|
|
detect the use of global constructors.
|
|
.Ip "\f(CW--warn-multiple-gp\fR" 4
|
|
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.
|
|
.Ip "\f(CW--warn-once\fR" 4
|
|
Only warn once for each undefined symbol, rather than once per module
|
|
which refers to it.
|
|
.Ip "\f(CW--warn-section-align\fR" 4
|
|
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 \f(CWSECTIONS\fR command does not specify a start address for
|
|
the section.
|
|
.Ip "\f(CW--whole-archive\fR" 4
|
|
For each archive mentioned on the command line after the
|
|
\f(CW--whole-archive\fR 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.
|
|
.Sp
|
|
Two notes when using this option from gcc: First, gcc doesn't know
|
|
about this option, so you have to use \f(CW-Wl,-whole-archive\fR.
|
|
Second, don't forget to use \f(CW-Wl,-no-whole-archive\fR after your
|
|
list of archives, because gcc will add its own list of archives to
|
|
your link and you may not want this flag to affect those as well.
|
|
.Ip "\f(CW--wrap \fIsymbol\fR\fR" 4
|
|
Use a wrapper function for \fIsymbol\fR. Any undefined reference to
|
|
\fIsymbol\fR will be resolved to \f(CW__wrap_\fIsymbol\fR\fR. Any
|
|
undefined reference to \f(CW__real_\fIsymbol\fR\fR will be resolved to
|
|
\fIsymbol\fR.
|
|
.Sp
|
|
This can be used to provide a wrapper for a system function. The
|
|
wrapper function should be called \f(CW__wrap_\fIsymbol\fR\fR. If it
|
|
wishes to call the system function, it should call
|
|
\f(CW__real_\fIsymbol\fR\fR.
|
|
.Sp
|
|
Here is a trivial example:
|
|
.Sp
|
|
.Vb 7
|
|
\&
|
|
\& void *
|
|
\& __wrap_malloc (int c)
|
|
\& {
|
|
\& printf ("malloc called with %ld\en", c);
|
|
\& return __real_malloc (c);
|
|
\& }
|
|
.Ve
|
|
If you link other code with this file using \f(CW--wrap malloc\fR, then
|
|
all calls to \f(CWmalloc\fR will call the function \f(CW__wrap_malloc\fR
|
|
instead. The call to \f(CW__real_malloc\fR in \f(CW__wrap_malloc\fR will
|
|
call the real \f(CWmalloc\fR function.
|
|
.Sp
|
|
You may wish to provide a \f(CW__real_malloc\fR function as well, so that
|
|
links without the \f(CW--wrap\fR option will succeed. If you do this,
|
|
you should not put the definition of \f(CW__real_malloc\fR in the same
|
|
file as \f(CW__wrap_malloc\fR; if you do, the assembler may resolve the
|
|
call before the linker has a chance to wrap it to \f(CWmalloc\fR.
|
|
.Ip "\f(CW--enable-new-dtags\fR" 4
|
|
.Ip "\f(CW--disable-new-dtags\fR" 4
|
|
This linker can create the new dynamic tags in \s-1ELF\s0. But the older \s-1ELF\s0
|
|
systems may not understand them. If you specify
|
|
\f(CW--enable-new-dtags\fR, the dynamic tags will be created as needed.
|
|
If you specify \f(CW--disable-new-dtags\fR, no new dynamic tags will be
|
|
created. By default, the new dynamic tags are not created. Note that
|
|
those options are only available for \s-1ELF\s0 systems.
|
|
.PP
|
|
The i386 \s-1PE\s0 linker supports the \f(CW-shared\fR option, which causes
|
|
the output to be a dynamically linked library (\s-1DLL\s0) instead of a
|
|
normal executable. You should name the output \f(CW*.dll\fR when you
|
|
use this option. In addition, the linker fully supports the standard
|
|
\f(CW*.def\fR 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).
|
|
.PP
|
|
In addition to the options common to all targets, the i386 \s-1PE\s0 linker
|
|
support additional command line options that are specific to the i386
|
|
\s-1PE\s0 target. Options that take values may be separated from their
|
|
values by either a space or an equals sign.
|
|
.Ip "\f(CW--add-stdcall-alias\fR" 4
|
|
If given, symbols with a stdcall suffix (@\fInn\fR) will be exported
|
|
as-is and also with the suffix stripped.
|
|
.Ip "\f(CW--base-file \fIfile\fR\fR" 4
|
|
Use \fIfile\fR as the name of a file in which to save the base
|
|
addresses of all the relocations needed for generating DLLs with
|
|
\fIdlltool\fR.
|
|
.Ip "\f(CW--dll\fR" 4
|
|
Create a \s-1DLL\s0 instead of a regular executable. You may also use
|
|
\f(CW-shared\fR or specify a \f(CWLIBRARY\fR in a given \f(CW.def\fR
|
|
file.
|
|
.Ip "\f(CW--enable-stdcall-fixup\fR" 4
|
|
.Ip "\f(CW--disable-stdcall-fixup\fR" 4
|
|
If the link finds a symbol that it cannot resolve, it will attempt to
|
|
do \*(L"fuzzy linking\*(R" 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 \f(CW_foo\fR might be linked to the function
|
|
\f(CW_foo@12\fR, or the undefined symbol \f(CW_bar@16\fR might be linked
|
|
to the function \f(CW_bar\fR. 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 \f(CW--enable-stdcall-fixup\fR, this
|
|
feature is fully enabled and warnings are not printed. If you specify
|
|
\f(CW--disable-stdcall-fixup\fR, this feature is disabled and such
|
|
mismatches are considered to be errors.
|
|
.Ip "\f(CW--export-all-symbols\fR" 4
|
|
If given, all global symbols in the objects used to build a \s-1DLL\s0 will
|
|
be exported by the \s-1DLL\s0. Note that this is the default if there
|
|
otherwise wouldn't be any exported symbols. When symbols are
|
|
explicitly exported via \s-1DEF\s0 files or implicitly exported via function
|
|
attributes, the default is to not export anything else unless this
|
|
option is given. Note that the symbols \f(CWDllMain@12\fR,
|
|
\f(CWDllEntryPoint@0\fR, and \f(CWimpure_ptr\fR will not be automatically
|
|
exported.
|
|
.Ip "\f(CW--exclude-symbols \fIsymbol\fR,\fIsymbol\fR,...\fR" 4
|
|
Specifies a list of symbols which should not be automatically
|
|
exported. The symbol names may be delimited by commas or colons.
|
|
.Ip "\f(CW--file-alignment\fR" 4
|
|
Specify the file alignment. Sections in the file will always begin at
|
|
file offsets which are multiples of this number. This defaults to
|
|
512.
|
|
.Ip "\f(CW--heap \fIreserve\fR\fR" 4
|
|
.Ip "\f(CW--heap \fIreserve\fR,\fIcommit\fR\fR" 4
|
|
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.
|
|
.Ip "\f(CW--image-base \fIvalue\fR\fR" 4
|
|
Use \fIvalue\fR 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.
|
|
.Ip "\f(CW--kill-at\fR" 4
|
|
If given, the stdcall suffixes (@\fInn\fR) will be stripped from
|
|
symbols before they are exported.
|
|
.Ip "\f(CW--major-image-version \fIvalue\fR\fR" 4
|
|
Sets the major number of the \*(L"image version\*(R". Defaults to 1.
|
|
.Ip "\f(CW--major-os-version \fIvalue\fR\fR" 4
|
|
Sets the major number of the \*(L"os version\*(R". Defaults to 4.
|
|
.Ip "\f(CW--major-subsystem-version \fIvalue\fR\fR" 4
|
|
Sets the major number of the \*(L"subsystem version\*(R". Defaults to 4.
|
|
.Ip "\f(CW--minor-image-version \fIvalue\fR\fR" 4
|
|
Sets the minor number of the \*(L"image version\*(R". Defaults to 0.
|
|
.Ip "\f(CW--minor-os-version \fIvalue\fR\fR" 4
|
|
Sets the minor number of the \*(L"os version\*(R". Defaults to 0.
|
|
.Ip "\f(CW--minor-subsystem-version \fIvalue\fR\fR" 4
|
|
Sets the minor number of the \*(L"subsystem version\*(R". Defaults to 0.
|
|
.Ip "\f(CW--output-def \fIfile\fR\fR" 4
|
|
The linker will create the file \fIfile\fR which will contain a \s-1DEF\s0
|
|
file corresponding to the \s-1DLL\s0 the linker is generating. This \s-1DEF\s0 file
|
|
(which should be called \f(CW*.def\fR) may be used to create an import
|
|
library with \f(CWdlltool\fR or may be used as a reference to
|
|
automatically or implicitly exported symbols.
|
|
.Ip "\f(CW--section-alignment\fR" 4
|
|
Sets the section alignment. Sections in memory will always begin at
|
|
addresses which are a multiple of this number. Defaults to 0x1000.
|
|
.Ip "\f(CW--stack \fIreserve\fR\fR" 4
|
|
.Ip "\f(CW--stack \fIreserve\fR,\fIcommit\fR\fR" 4
|
|
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.
|
|
.Ip "\f(CW--subsystem \fIwhich\fR\fR" 4
|
|
.Ip "\f(CW--subsystem \fIwhich\fR:\fImajor\fR\fR" 4
|
|
.Ip "\f(CW--subsystem \fIwhich\fR:\fImajor\fR.\fIminor\fR\fR" 4
|
|
Specifies the subsystem under which your program will execute. The
|
|
legal values for \fIwhich\fR are \f(CWnative\fR, \f(CWwindows\fR,
|
|
\f(CWconsole\fR, and \f(CWposix\fR. You may optionally set the
|
|
subsystem version also.
|
|
.SH "ENVIRONMENT"
|
|
You can change the behavior of \f(CWld\fR with the environment variables
|
|
\f(CWGNUTARGET\fR, \f(CWLDEMULATION\fR, and \f(CWCOLLECT_NO_DEMANGLE\fR.
|
|
.PP
|
|
\f(CWGNUTARGET\fR determines the input-file object format if you don't
|
|
use \fB\-b\fR (or its synonym \fB--format\fR). Its value should be one
|
|
of the BFD names for an input format. If there is no
|
|
\f(CWGNUTARGET\fR in the environment, \f(CWld\fR uses the natural format
|
|
of the target. If \f(CWGNUTARGET\fR is set to \f(CWdefault\fR 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.
|
|
.PP
|
|
\f(CWLDEMULATION\fR determines the default emulation if you don't use the
|
|
\fB\-m\fR option. The emulation can affect various aspects of linker
|
|
behaviour, particularly the default linker script. You can list the
|
|
available emulations with the \fB--verbose\fR or \fB\-V\fR options. If
|
|
the \fB\-m\fR option is not used, and the \f(CWLDEMULATION\fR environment
|
|
variable is not defined, the default emulation depends upon how the
|
|
linker was configured.
|
|
.PP
|
|
Normally, the linker will default to demangling symbols. However, if
|
|
\f(CWCOLLECT_NO_DEMANGLE\fR is set in the environment, then it will
|
|
default to not demangling symbols. This environment variable is used in
|
|
a similar fashion by the \f(CWgcc\fR linker wrapper program. The default
|
|
may be overridden by the \fB--demangle\fR and \fB--no-demangle\fR
|
|
options.
|
|
.SH "SEE ALSO"
|
|
\fIar\fR\|(1), \fInm\fR\|(1), \fIobjcopy\fR\|(1), \fIobjdump\fR\|(1), \fIreadelf\fR\|(1) and
|
|
the Info entries for \fIbinutils\fR and
|
|
\fIld\fR.
|
|
.SH "COPYRIGHT"
|
|
Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free Software Foundation, Inc.
|
|
.PP
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.1
|
|
or any later version published by the Free Software Foundation;
|
|
with no Invariant Sections, with no Front-Cover Texts, and with no
|
|
Back-Cover Texts. A copy of the license is included in the
|
|
section entitled \*(L"GNU Free Documentation License\*(R".
|
|
|
|
.rn }` ''
|
|
.IX Title "LD 1"
|
|
.IX Name "ld - Using LD, the GNU linker"
|
|
|
|
.IX Header "NAME"
|
|
|
|
.IX Header "SYNOPSIS"
|
|
|
|
.IX Header "DESCRIPTION"
|
|
|
|
.IX Header "OPTIONS"
|
|
|
|
.IX Item "\f(CW-a\fIkeyword\fR\fR"
|
|
|
|
.IX Item "\f(CW-A\fIarchitecture\fR\fR"
|
|
|
|
.IX Item "\f(CW--architecture=\fIarchitecture\fR\fR"
|
|
|
|
.IX Item "\f(CW-b \fIinput-format\fR\fR"
|
|
|
|
.IX Item "\f(CW--format=\fIinput-format\fR\fR"
|
|
|
|
.IX Item "\f(CW-c \fIMRI-commandfile\fR\fR"
|
|
|
|
.IX Item "\f(CW--mri-script=\fIMRI-commandfile\fR\fR"
|
|
|
|
.IX Item "\f(CW-d\fR"
|
|
|
|
.IX Item "\f(CW-dc\fR"
|
|
|
|
.IX Item "\f(CW-dp\fR"
|
|
|
|
.IX Item "\f(CW-e \fIentry\fR\fR"
|
|
|
|
.IX Item "\f(CW--entry=\fIentry\fR\fR"
|
|
|
|
.IX Item "\f(CW-E\fR"
|
|
|
|
.IX Item "\f(CW--export-dynamic\fR"
|
|
|
|
.IX Item "\f(CW-EB\fR"
|
|
|
|
.IX Item "\f(CW-EL\fR"
|
|
|
|
.IX Item "\f(CW-f\fR"
|
|
|
|
.IX Item "\f(CW--auxiliary \fIname\fR\fR"
|
|
|
|
.IX Item "\f(CW-F \fIname\fR\fR"
|
|
|
|
.IX Item "\f(CW--filter \fIname\fR\fR"
|
|
|
|
.IX Item "\f(CW-fini \fIname\fR\fR"
|
|
|
|
.IX Item "\f(CW-g\fR"
|
|
|
|
.IX Item "\f(CW-G\fIvalue\fR\fR"
|
|
|
|
.IX Item "\f(CW--gpsize=\fIvalue\fR\fR"
|
|
|
|
.IX Item "\f(CW-h\fIname\fR\fR"
|
|
|
|
.IX Item "\f(CW-soname=\fIname\fR\fR"
|
|
|
|
.IX Item "\f(CW-i\fR"
|
|
|
|
.IX Item "\f(CW-init \fIname\fR\fR"
|
|
|
|
.IX Item "\f(CW-l\fIarchive\fR\fR"
|
|
|
|
.IX Item "\f(CW--library=\fIarchive\fR\fR"
|
|
|
|
.IX Item "\f(CW-L\fIsearchdir\fR\fR"
|
|
|
|
.IX Item "\f(CW--library-path=\fIsearchdir\fR\fR"
|
|
|
|
.IX Item "\f(CW-m\fIemulation\fR\fR"
|
|
|
|
.IX Item "\f(CW-M\fR"
|
|
|
|
.IX Item "\f(CW--print-map\fR"
|
|
|
|
.IX Item "\(bu"
|
|
|
|
.IX Item "\(bu"
|
|
|
|
.IX Item "\(bu"
|
|
|
|
.IX Item "\f(CW-n\fR"
|
|
|
|
.IX Item "\f(CW--nmagic\fR"
|
|
|
|
.IX Item "\f(CW-N\fR"
|
|
|
|
.IX Item "\f(CW--omagic\fR"
|
|
|
|
.IX Item "\f(CW-o \fIoutput\fR\fR"
|
|
|
|
.IX Item "\f(CW--output=\fIoutput\fR\fR"
|
|
|
|
.IX Item "\f(CW-O \fIlevel\fR\fR"
|
|
|
|
.IX Item "\f(CW-q\fR"
|
|
|
|
.IX Item "\f(CW--emit-relocs\fR"
|
|
|
|
.IX Item "\f(CW-r\fR"
|
|
|
|
.IX Item "\f(CW--relocateable\fR"
|
|
|
|
.IX Item "\f(CW-R \fIfilename\fR\fR"
|
|
|
|
.IX Item "\f(CW--just-symbols=\fIfilename\fR\fR"
|
|
|
|
.IX Item "\f(CW-s\fR"
|
|
|
|
.IX Item "\f(CW--strip-all\fR"
|
|
|
|
.IX Item "\f(CW-S\fR"
|
|
|
|
.IX Item "\f(CW--strip-debug\fR"
|
|
|
|
.IX Item "\f(CW-t\fR"
|
|
|
|
.IX Item "\f(CW--trace\fR"
|
|
|
|
.IX Item "\f(CW-T \fIscriptfile\fR\fR"
|
|
|
|
.IX Item "\f(CW--script=\fIscriptfile\fR\fR"
|
|
|
|
.IX Item "\f(CW-u \fIsymbol\fR\fR"
|
|
|
|
.IX Item "\f(CW--undefined=\fIsymbol\fR\fR"
|
|
|
|
.IX Item "\f(CW-Ur\fR"
|
|
|
|
.IX Item "\f(CW--unique[=\fISECTION\fR]\fR"
|
|
|
|
.IX Item "\f(CW-v\fR"
|
|
|
|
.IX Item "\f(CW--version\fR"
|
|
|
|
.IX Item "\f(CW-V\fR"
|
|
|
|
.IX Item "\f(CW-x\fR"
|
|
|
|
.IX Item "\f(CW--discard-all\fR"
|
|
|
|
.IX Item "\f(CW-X\fR"
|
|
|
|
.IX Item "\f(CW--discard-locals\fR"
|
|
|
|
.IX Item "\f(CW-y \fIsymbol\fR\fR"
|
|
|
|
.IX Item "\f(CW--trace-symbol=\fIsymbol\fR\fR"
|
|
|
|
.IX Item "\f(CW-Y \fIpath\fR\fR"
|
|
|
|
.IX Item "\f(CW-z \fIkeyword\fR\fR"
|
|
|
|
.IX Item "\f(CW-( \fIarchives\fR -)\fR"
|
|
|
|
.IX Item "\f(CW--start-group \fIarchives\fR --end-group\fR"
|
|
|
|
.IX Item "\f(CW-assert \fIkeyword\fR\fR"
|
|
|
|
.IX Item "\f(CW-Bdynamic\fR"
|
|
|
|
.IX Item "\f(CW-dy\fR"
|
|
|
|
.IX Item "\f(CW-call_shared\fR"
|
|
|
|
.IX Item "\f(CW-Bgroup\fR"
|
|
|
|
.IX Item "\f(CW-Bstatic\fR"
|
|
|
|
.IX Item "\f(CW-dn\fR"
|
|
|
|
.IX Item "\f(CW-non_shared\fR"
|
|
|
|
.IX Item "\f(CW-static\fR"
|
|
|
|
.IX Item "\f(CW-Bsymbolic\fR"
|
|
|
|
.IX Item "\f(CW--check-sections\fR"
|
|
|
|
.IX Item "\f(CW--no-check-sections\fR"
|
|
|
|
.IX Item "\f(CW--cref\fR"
|
|
|
|
.IX Item "\f(CW--defsym \fIsymbol\fR=\fIexpression\fR\fR"
|
|
|
|
.IX Item "\f(CW--demangle[=\fIstyle\fR]\fR"
|
|
|
|
.IX Item "\f(CW--no-demangle\fR"
|
|
|
|
.IX Item "\f(CW--dynamic-linker \fIfile\fR\fR"
|
|
|
|
.IX Item "\f(CW--embedded-relocs\fR"
|
|
|
|
.IX Item "\f(CW--force-exe-suffix\fR"
|
|
|
|
.IX Item "\f(CW--no-gc-sections\fR"
|
|
|
|
.IX Item "\f(CW--gc-sections\fR"
|
|
|
|
.IX Item "\f(CW--help\fR"
|
|
|
|
.IX Item "\f(CW--target-help\fR"
|
|
|
|
.IX Item "\f(CW-Map \fImapfile\fR\fR"
|
|
|
|
.IX Item "\f(CW--no-keep-memory\fR"
|
|
|
|
.IX Item "\f(CW--no-undefined\fR"
|
|
|
|
.IX Item "\f(CW-z defs\fR"
|
|
|
|
.IX Item "\f(CW--allow-shlib-undefined\fR"
|
|
|
|
.IX Item "\f(CW--no-warn-mismatch\fR"
|
|
|
|
.IX Item "\f(CW--no-whole-archive\fR"
|
|
|
|
.IX Item "\f(CW--noinhibit-exec\fR"
|
|
|
|
.IX Item "\f(CW--oformat \fIoutput-format\fR\fR"
|
|
|
|
.IX Item "\f(CW-qmagic\fR"
|
|
|
|
.IX Item "\f(CW-Qy\fR"
|
|
|
|
.IX Item "\f(CW--relax\fR"
|
|
|
|
.IX Item "\f(CW--retain-symbols-file \fIfilename\fR\fR"
|
|
|
|
.IX Item "\f(CW-rpath \fIdir\fR\fR"
|
|
|
|
.IX Item "\f(CW-rpath-link \fIDIR\fR\fR"
|
|
|
|
.IX Item "1."
|
|
|
|
.IX Item "2."
|
|
|
|
.IX Item "3."
|
|
|
|
.IX Item "4."
|
|
|
|
.IX Item "5."
|
|
|
|
.IX Item "6."
|
|
|
|
.IX Item "7."
|
|
|
|
.IX Item "8."
|
|
|
|
.IX Item "\f(CW-shared\fR"
|
|
|
|
.IX Item "\f(CW-Bshareable\fR"
|
|
|
|
.IX Item "\f(CW--sort-common\fR"
|
|
|
|
.IX Item "\f(CW--split-by-file [\fIsize\fR]\fR"
|
|
|
|
.IX Item "\f(CW--split-by-reloc [\fIcount\fR]\fR"
|
|
|
|
.IX Item "\f(CW--stats\fR"
|
|
|
|
.IX Item "\f(CW--traditional-format\fR"
|
|
|
|
.IX Item "\f(CW--section-start \fIsectionname\fR=\fIorg\fR\fR"
|
|
|
|
.IX Item "\f(CW-Tbss \fIorg\fR\fR"
|
|
|
|
.IX Item "\f(CW-Tdata \fIorg\fR\fR"
|
|
|
|
.IX Item "\f(CW-Ttext \fIorg\fR\fR"
|
|
|
|
.IX Item "\f(CW--dll-verbose\fR"
|
|
|
|
.IX Item "\f(CW--verbose\fR"
|
|
|
|
.IX Item "\f(CW--version-script=\fIversion-scriptfile\fR\fR"
|
|
|
|
.IX Item "\f(CW--warn-common\fR"
|
|
|
|
.IX Item "\fBint i = 1;\fR"
|
|
|
|
.IX Item "\fBextern int i;\fR"
|
|
|
|
.IX Item "\fBint i;\fR"
|
|
|
|
.IX Item "1."
|
|
|
|
.IX Item "2."
|
|
|
|
.IX Item "3."
|
|
|
|
.IX Item "4."
|
|
|
|
.IX Item "5."
|
|
|
|
.IX Item "\f(CW--warn-constructors\fR"
|
|
|
|
.IX Item "\f(CW--warn-multiple-gp\fR"
|
|
|
|
.IX Item "\f(CW--warn-once\fR"
|
|
|
|
.IX Item "\f(CW--warn-section-align\fR"
|
|
|
|
.IX Item "\f(CW--whole-archive\fR"
|
|
|
|
.IX Item "\f(CW--wrap \fIsymbol\fR\fR"
|
|
|
|
.IX Item "\f(CW--enable-new-dtags\fR"
|
|
|
|
.IX Item "\f(CW--disable-new-dtags\fR"
|
|
|
|
.IX Item "\f(CW--add-stdcall-alias\fR"
|
|
|
|
.IX Item "\f(CW--base-file \fIfile\fR\fR"
|
|
|
|
.IX Item "\f(CW--dll\fR"
|
|
|
|
.IX Item "\f(CW--enable-stdcall-fixup\fR"
|
|
|
|
.IX Item "\f(CW--disable-stdcall-fixup\fR"
|
|
|
|
.IX Item "\f(CW--export-all-symbols\fR"
|
|
|
|
.IX Item "\f(CW--exclude-symbols \fIsymbol\fR,\fIsymbol\fR,...\fR"
|
|
|
|
.IX Item "\f(CW--file-alignment\fR"
|
|
|
|
.IX Item "\f(CW--heap \fIreserve\fR\fR"
|
|
|
|
.IX Item "\f(CW--heap \fIreserve\fR,\fIcommit\fR\fR"
|
|
|
|
.IX Item "\f(CW--image-base \fIvalue\fR\fR"
|
|
|
|
.IX Item "\f(CW--kill-at\fR"
|
|
|
|
.IX Item "\f(CW--major-image-version \fIvalue\fR\fR"
|
|
|
|
.IX Item "\f(CW--major-os-version \fIvalue\fR\fR"
|
|
|
|
.IX Item "\f(CW--major-subsystem-version \fIvalue\fR\fR"
|
|
|
|
.IX Item "\f(CW--minor-image-version \fIvalue\fR\fR"
|
|
|
|
.IX Item "\f(CW--minor-os-version \fIvalue\fR\fR"
|
|
|
|
.IX Item "\f(CW--minor-subsystem-version \fIvalue\fR\fR"
|
|
|
|
.IX Item "\f(CW--output-def \fIfile\fR\fR"
|
|
|
|
.IX Item "\f(CW--section-alignment\fR"
|
|
|
|
.IX Item "\f(CW--stack \fIreserve\fR\fR"
|
|
|
|
.IX Item "\f(CW--stack \fIreserve\fR,\fIcommit\fR\fR"
|
|
|
|
.IX Item "\f(CW--subsystem \fIwhich\fR\fR"
|
|
|
|
.IX Item "\f(CW--subsystem \fIwhich\fR:\fImajor\fR\fR"
|
|
|
|
.IX Item "\f(CW--subsystem \fIwhich\fR:\fImajor\fR.\fIminor\fR\fR"
|
|
|
|
.IX Header "ENVIRONMENT"
|
|
|
|
.IX Header "SEE ALSO"
|
|
|
|
.IX Header "COPYRIGHT"
|
|
|