mirror of
https://github.com/autc04/Retro68.git
synced 2024-11-23 15:32:26 +00:00
2813 lines
126 KiB
Groff
2813 lines
126 KiB
Groff
.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
|
|
.\"
|
|
.\" Standard preamble:
|
|
.\" ========================================================================
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Vb \" Begin verbatim text
|
|
.ft CW
|
|
.nf
|
|
.ne \\$1
|
|
..
|
|
.de Ve \" End verbatim text
|
|
.ft R
|
|
.fi
|
|
..
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
|
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
|
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
|
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
|
.\" nothing in troff, for use with C<>.
|
|
.tr \(*W-
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
|
.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" ""
|
|
. ds C` ""
|
|
. ds C' ""
|
|
'br\}
|
|
.el\{\
|
|
. ds -- \|\(em\|
|
|
. ds PI \(*p
|
|
. ds L" ``
|
|
. ds R" ''
|
|
. ds C`
|
|
. ds C'
|
|
'br\}
|
|
.\"
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\"
|
|
.\" If the F register is turned on, we'll generate index entries on stderr for
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
|
.\" output yourself in some meaningful fashion.
|
|
.\"
|
|
.\" Avoid warning from groff about undefined register 'F'.
|
|
.de IX
|
|
..
|
|
.nr rF 0
|
|
.if \n(.g .if rF .nr rF 1
|
|
.if (\n(rF:(\n(.g==0)) \{
|
|
. if \nF \{
|
|
. de IX
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
|
..
|
|
. if !\nF==2 \{
|
|
. nr % 0
|
|
. nr F 2
|
|
. \}
|
|
. \}
|
|
.\}
|
|
.rr rF
|
|
.\"
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
|
. \" 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 /
|
|
.\}
|
|
.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 / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
|
.\}
|
|
. \" 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 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
|
|
. \" 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 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
|
|
.\}
|
|
.rm #[ #] #H #V #F C
|
|
.\" ========================================================================
|
|
.\"
|
|
.IX Title "LD 1"
|
|
.TH LD 1 "2017-07-24" "binutils-2.29" "GNU Development Tools"
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
|
.\" way too many mistakes in technical documents.
|
|
.if n .ad l
|
|
.nh
|
|
.SH "NAME"
|
|
ld \- The GNU linker
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
ld [\fBoptions\fR] \fIobjfile\fR ...
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
\&\fBld\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 \fBld\fR.
|
|
.PP
|
|
\&\fBld\fR accepts Linker Command Language files written in
|
|
a superset of \s-1AT&T\s0'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
|
|
\&\fBld\fR entry in \f(CW\*(C`info\*(C'\fR for full details on the command
|
|
language and on other aspects of the \s-1GNU\s0 linker.
|
|
.PP
|
|
This version of \fBld\fR uses the general purpose \s-1BFD\s0 libraries
|
|
to operate on object files. This allows \fBld\fR to read, combine, and
|
|
write object files in many different formats\-\-\-for example, \s-1COFF\s0 or
|
|
\&\f(CW\*(C`a.out\*(C'\fR. Different formats may be linked together to produce any
|
|
available kind of object file.
|
|
.PP
|
|
Aside from its flexibility, the \s-1GNU\s0 linker is more helpful than other
|
|
linkers in providing diagnostic information. Many linkers abandon
|
|
execution immediately upon encountering an error; whenever possible,
|
|
\&\fBld\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 \s-1GNU\s0 linker \fBld\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"
|
|
.IX Header "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 \fBld\fR is to link standard Unix
|
|
object files on a standard, supported Unix system. On such a system, to
|
|
link a file \f(CW\*(C`hello.o\*(C'\fR:
|
|
.PP
|
|
.Vb 1
|
|
\& ld \-o <output> /lib/crt0.o hello.o \-lc
|
|
.Ve
|
|
.PP
|
|
This tells \fBld\fR to produce a file called \fIoutput\fR as the
|
|
result of linking the file \f(CW\*(C`/lib/crt0.o\*(C'\fR with \f(CW\*(C`hello.o\*(C'\fR and
|
|
the library \f(CW\*(C`libc.a\*(C'\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 \fBld\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 cannot 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(CW\*(C`INPUT\*(C'\fR or \f(CW\*(C`GROUP\*(C'\fR to load other objects. Specifying a
|
|
script in this way merely augments the main linker script, with the
|
|
extra commands placed after the main script; use the \fB\-T\fR option
|
|
to replace the default linker script entirely, but note the effect of
|
|
the \f(CW\*(C`INSERT\*(C'\fR command.
|
|
.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 'o' can
|
|
only be preceded 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 \s-1NMAGIC\s0 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
|
|
(e.g. \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 1
|
|
\& gcc \-Wl,\-\-start\-group foo.o bar.o \-Wl,\-\-end\-group
|
|
.Ve
|
|
.PP
|
|
This is important, because otherwise the compiler driver program may
|
|
silently drop the linker options, resulting in a bad link. Confusion
|
|
may also arise when passing options that require values through a
|
|
driver, as the use of a space between option and argument acts as
|
|
a separator, and causes the driver to pass only the option to the linker
|
|
and the argument to the compiler. In this case, it is simplest to use
|
|
the joined forms of both single\- and multiple-letter options, such as:
|
|
.PP
|
|
.Vb 1
|
|
\& gcc foo.o bar.o \-Wl,\-eENTRY \-Wl,\-Map=a.map
|
|
.Ve
|
|
.PP
|
|
Here is a table of the generic command line switches accepted by the \s-1GNU\s0
|
|
linker:
|
|
.IP "\fB@\fR\fIfile\fR" 4
|
|
.IX Item "@file"
|
|
Read command-line options from \fIfile\fR. The options read are
|
|
inserted in place of the original @\fIfile\fR option. If \fIfile\fR
|
|
does not exist, or cannot be read, then the option will be treated
|
|
literally, and not removed.
|
|
.Sp
|
|
Options in \fIfile\fR are separated by whitespace. A whitespace
|
|
character may be included in an option by surrounding the entire
|
|
option in either single or double quotes. Any character (including a
|
|
backslash) may be included by prefixing the character to be included
|
|
with a backslash. The \fIfile\fR may itself contain additional
|
|
@\fIfile\fR options; any such options will be processed recursively.
|
|
.IP "\fB\-a\fR \fIkeyword\fR" 4
|
|
.IX Item "-a keyword"
|
|
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 "\fB\-\-audit\fR \fI\s-1AUDITLIB\s0\fR" 4
|
|
.IX Item "--audit AUDITLIB"
|
|
Adds \fI\s-1AUDITLIB\s0\fR to the \f(CW\*(C`DT_AUDIT\*(C'\fR entry of the dynamic section.
|
|
\&\fI\s-1AUDITLIB\s0\fR is not checked for existence, nor will it use the \s-1DT_SONAME\s0
|
|
specified in the library. If specified multiple times \f(CW\*(C`DT_AUDIT\*(C'\fR
|
|
will contain a colon separated list of audit interfaces to use. If the linker
|
|
finds an object with an audit entry while searching for shared libraries,
|
|
it will add a corresponding \f(CW\*(C`DT_DEPAUDIT\*(C'\fR entry in the output file.
|
|
This option is only meaningful on \s-1ELF\s0 platforms supporting the rtld-audit
|
|
interface.
|
|
.IP "\fB\-A\fR \fIarchitecture\fR" 4
|
|
.IX Item "-A architecture"
|
|
.PD 0
|
|
.IP "\fB\-\-architecture=\fR\fIarchitecture\fR" 4
|
|
.IX Item "--architecture=architecture"
|
|
.PD
|
|
In the current release of \fBld\fR, this option is useful only for the
|
|
Intel 960 family of architectures. In that \fBld\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 \fBld\fR may support similar functionality for
|
|
other architecture families.
|
|
.IP "\fB\-b\fR \fIinput-format\fR" 4
|
|
.IX Item "-b input-format"
|
|
.PD 0
|
|
.IP "\fB\-\-format=\fR\fIinput-format\fR" 4
|
|
.IX Item "--format=input-format"
|
|
.PD
|
|
\&\fBld\fR may be configured to support more than one kind of object
|
|
file. If your \fBld\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 \fBld\fR is
|
|
configured to support alternative object formats, you don't usually need
|
|
to specify this, as \fBld\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(CW\*(C`GNUTARGET\*(C'\fR.
|
|
.Sp
|
|
You can also define the input format from a script, using the command
|
|
\&\f(CW\*(C`TARGET\*(C'\fR;
|
|
.IP "\fB\-c\fR \fIMRI-commandfile\fR" 4
|
|
.IX Item "-c MRI-commandfile"
|
|
.PD 0
|
|
.IP "\fB\-\-mri\-script=\fR\fIMRI-commandfile\fR" 4
|
|
.IX Item "--mri-script=MRI-commandfile"
|
|
.PD
|
|
For compatibility with linkers produced by \s-1MRI, \s0\fBld\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 \fBld\fR scripting language.
|
|
If \fIMRI-cmdfile\fR does not exist, \fBld\fR looks for it in the directories
|
|
specified by any \fB\-L\fR options.
|
|
.IP "\fB\-d\fR" 4
|
|
.IX Item "-d"
|
|
.PD 0
|
|
.IP "\fB\-dc\fR" 4
|
|
.IX Item "-dc"
|
|
.IP "\fB\-dp\fR" 4
|
|
.IX Item "-dp"
|
|
.PD
|
|
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(CW\*(C`FORCE_COMMON_ALLOCATION\*(C'\fR has the same effect.
|
|
.IP "\fB\-\-depaudit\fR \fI\s-1AUDITLIB\s0\fR" 4
|
|
.IX Item "--depaudit AUDITLIB"
|
|
.PD 0
|
|
.IP "\fB\-P\fR \fI\s-1AUDITLIB\s0\fR" 4
|
|
.IX Item "-P AUDITLIB"
|
|
.PD
|
|
Adds \fI\s-1AUDITLIB\s0\fR to the \f(CW\*(C`DT_DEPAUDIT\*(C'\fR entry of the dynamic section.
|
|
\&\fI\s-1AUDITLIB\s0\fR is not checked for existence, nor will it use the \s-1DT_SONAME\s0
|
|
specified in the library. If specified multiple times \f(CW\*(C`DT_DEPAUDIT\*(C'\fR
|
|
will contain a colon separated list of audit interfaces to use. This
|
|
option is only meaningful on \s-1ELF\s0 platforms supporting the rtld-audit interface.
|
|
The \-P option is provided for Solaris compatibility.
|
|
.IP "\fB\-e\fR \fIentry\fR" 4
|
|
.IX Item "-e entry"
|
|
.PD 0
|
|
.IP "\fB\-\-entry=\fR\fIentry\fR" 4
|
|
.IX Item "--entry=entry"
|
|
.PD
|
|
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 "\fB\-\-exclude\-libs\fR \fIlib\fR\fB,\fR\fIlib\fR\fB,...\fR" 4
|
|
.IX Item "--exclude-libs lib,lib,..."
|
|
Specifies a list of archive libraries from which symbols should not be automatically
|
|
exported. The library names may be delimited by commas or colons. Specifying
|
|
\&\f(CW\*(C`\-\-exclude\-libs ALL\*(C'\fR excludes symbols in all archive libraries from
|
|
automatic export. This option is available only for the i386 \s-1PE\s0 targeted
|
|
port of the linker and for \s-1ELF\s0 targeted ports. For i386 \s-1PE,\s0 symbols
|
|
explicitly listed in a .def file are still exported, regardless of this
|
|
option. For \s-1ELF\s0 targeted ports, symbols affected by this option will
|
|
be treated as hidden.
|
|
.IP "\fB\-\-exclude\-modules\-for\-implib\fR \fImodule\fR\fB,\fR\fImodule\fR\fB,...\fR" 4
|
|
.IX Item "--exclude-modules-for-implib module,module,..."
|
|
Specifies a list of object files or archive members, from which symbols
|
|
should not be automatically exported, but which should be copied wholesale
|
|
into the import library being generated during the link. The module names
|
|
may be delimited by commas or colons, and must match exactly the filenames
|
|
used by \fBld\fR to open the files; for archive members, this is simply
|
|
the member name, but for object files the name listed must include and
|
|
match precisely any path used to specify the input file on the linker's
|
|
command-line. This option is available only for the i386 \s-1PE\s0 targeted port
|
|
of the linker. Symbols explicitly listed in a .def file are still exported,
|
|
regardless of this option.
|
|
.IP "\fB\-E\fR" 4
|
|
.IX Item "-E"
|
|
.PD 0
|
|
.IP "\fB\-\-export\-dynamic\fR" 4
|
|
.IX Item "--export-dynamic"
|
|
.IP "\fB\-\-no\-export\-dynamic\fR" 4
|
|
.IX Item "--no-export-dynamic"
|
|
.PD
|
|
When creating a dynamically linked executable, using the \fB\-E\fR
|
|
option or the \fB\-\-export\-dynamic\fR option causes the linker to 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 either of these options (or use the
|
|
\&\fB\-\-no\-export\-dynamic\fR option to restore the default behavior), 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(CW\*(C`dlopen\*(C'\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.
|
|
.Sp
|
|
You can also use the dynamic list to control what symbols should
|
|
be added to the dynamic symbol table if the output format supports it.
|
|
See the description of \fB\-\-dynamic\-list\fR.
|
|
.Sp
|
|
Note that this option is specific to \s-1ELF\s0 targeted ports. \s-1PE\s0 targets
|
|
support a similar function to export all symbols from a \s-1DLL\s0 or \s-1EXE\s0; see
|
|
the description of \fB\-\-export\-all\-symbols\fR below.
|
|
.IP "\fB\-EB\fR" 4
|
|
.IX Item "-EB"
|
|
Link big-endian objects. This affects the default output format.
|
|
.IP "\fB\-EL\fR" 4
|
|
.IX Item "-EL"
|
|
Link little-endian objects. This affects the default output format.
|
|
.IP "\fB\-f\fR \fIname\fR" 4
|
|
.IX Item "-f name"
|
|
.PD 0
|
|
.IP "\fB\-\-auxiliary=\fR\fIname\fR" 4
|
|
.IX Item "--auxiliary=name"
|
|
.PD
|
|
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 "\fB\-F\fR \fIname\fR" 4
|
|
.IX Item "-F name"
|
|
.PD 0
|
|
.IP "\fB\-\-filter=\fR\fIname\fR" 4
|
|
.IX Item "--filter=name"
|
|
.PD
|
|
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 \fB\-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
|
|
\&\fB\-b\fR, \fB\-\-format\fR, \fB\-\-oformat\fR options, the
|
|
\&\f(CW\*(C`TARGET\*(C'\fR command in linker scripts, and the \f(CW\*(C`GNUTARGET\*(C'\fR
|
|
environment variable.
|
|
The \s-1GNU\s0 linker will ignore the \fB\-F\fR option when not
|
|
creating an \s-1ELF\s0 shared object.
|
|
.IP "\fB\-fini=\fR\fIname\fR" 4
|
|
.IX Item "-fini=name"
|
|
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\*(C`_fini\*(C'\fR as
|
|
the function to call.
|
|
.IP "\fB\-g\fR" 4
|
|
.IX Item "-g"
|
|
Ignored. Provided for compatibility with other tools.
|
|
.IP "\fB\-G\fR \fIvalue\fR" 4
|
|
.IX Item "-G value"
|
|
.PD 0
|
|
.IP "\fB\-\-gpsize=\fR\fIvalue\fR" 4
|
|
.IX Item "--gpsize=value"
|
|
.PD
|
|
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 ELF\s0 that support putting large and small objects into different
|
|
sections. This is ignored for other object file formats.
|
|
.IP "\fB\-h\fR \fIname\fR" 4
|
|
.IX Item "-h name"
|
|
.PD 0
|
|
.IP "\fB\-soname=\fR\fIname\fR" 4
|
|
.IX Item "-soname=name"
|
|
.PD
|
|
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 "\fB\-i\fR" 4
|
|
.IX Item "-i"
|
|
Perform an incremental link (same as option \fB\-r\fR).
|
|
.IP "\fB\-init=\fR\fIname\fR" 4
|
|
.IX Item "-init=name"
|
|
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\*(C`_init\*(C'\fR as the
|
|
function to call.
|
|
.IP "\fB\-l\fR \fInamespec\fR" 4
|
|
.IX Item "-l namespec"
|
|
.PD 0
|
|
.IP "\fB\-\-library=\fR\fInamespec\fR" 4
|
|
.IX Item "--library=namespec"
|
|
.PD
|
|
Add the archive or object file specified by \fInamespec\fR to the
|
|
list of files to link. This option may be used any number of times.
|
|
If \fInamespec\fR is of the form \fI:\fIfilename\fI\fR, \fBld\fR
|
|
will search the library path for a file called \fIfilename\fR, otherwise it
|
|
will search the library path for a file called \fIlib\fInamespec\fI.a\fR.
|
|
.Sp
|
|
On systems which support shared libraries, \fBld\fR may also search for
|
|
files other than \fIlib\fInamespec\fI.a\fR. Specifically, on \s-1ELF\s0
|
|
and SunOS systems, \fBld\fR will search a directory for a library
|
|
called \fIlib\fInamespec\fI.so\fR before searching for one called
|
|
\&\fIlib\fInamespec\fI.a\fR. (By convention, a \f(CW\*(C`.so\*(C'\fR extension
|
|
indicates a shared library.) Note that this behavior does not apply
|
|
to \fI:\fIfilename\fI\fR, which always specifies a file called
|
|
\&\fIfilename\fR.
|
|
.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 file(s) from the
|
|
archive. However, an undefined symbol in an object appearing later on
|
|
the command line will not cause the linker to search the archive again.
|
|
.Sp
|
|
See the \fB\-(\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 \fBld\fR on \s-1AIX,\s0 note that it is different from the
|
|
behaviour of the \s-1AIX\s0 linker.
|
|
.IP "\fB\-L\fR \fIsearchdir\fR" 4
|
|
.IX Item "-L searchdir"
|
|
.PD 0
|
|
.IP "\fB\-\-library\-path=\fR\fIsearchdir\fR" 4
|
|
.IX Item "--library-path=searchdir"
|
|
.PD
|
|
Add path \fIsearchdir\fR to the list of paths that \fBld\fR will search
|
|
for archive libraries and \fBld\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
|
|
\&\fB\-L\fR options apply to all \fB\-l\fR options, regardless of the
|
|
order in which the options appear. \fB\-L\fR options do not affect
|
|
how \fBld\fR searches for a linker script unless \fB\-T\fR
|
|
option is specified.
|
|
.Sp
|
|
If \fIsearchdir\fR begins with \f(CW\*(C`=\*(C'\fR or \f(CW$SYSROOT\fR, then this
|
|
prefix will be replaced by the \fIsysroot prefix\fR, controlled by the
|
|
\&\fB\-\-sysroot\fR option, or specified when the linker is configured.
|
|
.Sp
|
|
The default set of paths searched (without being specified with
|
|
\&\fB\-L\fR) depends on which emulation mode \fBld\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(CW\*(C`SEARCH_DIR\*(C'\fR command. Directories specified this way are searched
|
|
at the point in which the linker script appears in the command line.
|
|
.IP "\fB\-m\fR \fIemulation\fR" 4
|
|
.IX Item "-m emulation"
|
|
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(CW\*(C`LDEMULATION\*(C'\fR environment variable, if that is defined.
|
|
.Sp
|
|
Otherwise, the default emulation depends upon how the linker was
|
|
configured.
|
|
.IP "\fB\-M\fR" 4
|
|
.IX Item "-M"
|
|
.PD 0
|
|
.IP "\fB\-\-print\-map\fR" 4
|
|
.IX Item "--print-map"
|
|
.PD
|
|
Print a link map to the standard output. A link map provides
|
|
information about the link, including the following:
|
|
.RS 4
|
|
.IP "\(bu" 4
|
|
Where object files are mapped into memory.
|
|
.IP "\(bu" 4
|
|
How common symbols are allocated.
|
|
.IP "\(bu" 4
|
|
All archive members included in the link, with a mention of the symbol
|
|
which caused the archive member to be brought in.
|
|
.IP "\(bu" 4
|
|
The values assigned to symbols.
|
|
.Sp
|
|
Note \- symbols whose values are computed by an expression which
|
|
involves a reference to a previous value of the same symbol may not
|
|
have correct result displayed in the link map. This is because the
|
|
linker discards intermediate results and only retains the final value
|
|
of an expression. Under such circumstances the linker will display
|
|
the final value enclosed by square brackets. Thus for example a
|
|
linker script containing:
|
|
.Sp
|
|
.Vb 3
|
|
\& foo = 1
|
|
\& foo = foo * 4
|
|
\& foo = foo + 8
|
|
.Ve
|
|
.Sp
|
|
will produce the following output in the link map if the \fB\-M\fR
|
|
option is used:
|
|
.Sp
|
|
.Vb 3
|
|
\& 0x00000001 foo = 0x1
|
|
\& [0x0000000c] foo = (foo * 0x4)
|
|
\& [0x0000000c] foo = (foo + 0x8)
|
|
.Ve
|
|
.Sp
|
|
See \fBExpressions\fR for more information about expressions in linker
|
|
scripts.
|
|
.RE
|
|
.RS 4
|
|
.RE
|
|
.IP "\fB\-n\fR" 4
|
|
.IX Item "-n"
|
|
.PD 0
|
|
.IP "\fB\-\-nmagic\fR" 4
|
|
.IX Item "--nmagic"
|
|
.PD
|
|
Turn off page alignment of sections, and disable linking against shared
|
|
libraries. If the output format supports Unix style magic numbers,
|
|
mark the output as \f(CW\*(C`NMAGIC\*(C'\fR.
|
|
.IP "\fB\-N\fR" 4
|
|
.IX Item "-N"
|
|
.PD 0
|
|
.IP "\fB\-\-omagic\fR" 4
|
|
.IX Item "--omagic"
|
|
.PD
|
|
Set the text and data sections to be readable and writable. Also, do
|
|
not page-align the data segment, and disable linking against shared
|
|
libraries. If the output format supports Unix style magic numbers,
|
|
mark the output as \f(CW\*(C`OMAGIC\*(C'\fR. Note: Although a writable text section
|
|
is allowed for PE-COFF targets, it does not conform to the format
|
|
specification published by Microsoft.
|
|
.IP "\fB\-\-no\-omagic\fR" 4
|
|
.IX Item "--no-omagic"
|
|
This option negates most of the effects of the \fB\-N\fR option. It
|
|
sets the text section to be read-only, and forces the data segment to
|
|
be page-aligned. Note \- this option does not enable linking against
|
|
shared libraries. Use \fB\-Bdynamic\fR for this.
|
|
.IP "\fB\-o\fR \fIoutput\fR" 4
|
|
.IX Item "-o output"
|
|
.PD 0
|
|
.IP "\fB\-\-output=\fR\fIoutput\fR" 4
|
|
.IX Item "--output=output"
|
|
.PD
|
|
Use \fIoutput\fR as the name for the program produced by \fBld\fR; if this
|
|
option is not specified, the name \fIa.out\fR is used by default. The
|
|
script command \f(CW\*(C`OUTPUT\*(C'\fR can also specify the output file name.
|
|
.IP "\fB\-O\fR \fIlevel\fR" 4
|
|
.IX Item "-O level"
|
|
If \fIlevel\fR is a numeric values greater than zero \fBld\fR optimizes
|
|
the output. This might take significantly longer and therefore probably
|
|
should only be enabled for the final binary. At the moment this
|
|
option only affects \s-1ELF\s0 shared library generation. Future releases of
|
|
the linker may make more use of this option. Also currently there is
|
|
no difference in the linker's behaviour for different non-zero values
|
|
of this option. Again this may change with future releases.
|
|
.IP "\fB\-plugin\fR \fIname\fR" 4
|
|
.IX Item "-plugin name"
|
|
Involve a plugin in the linking process. The \fIname\fR parameter is
|
|
the absolute filename of the plugin. Usually this parameter is
|
|
automatically added by the complier, when using link time
|
|
optimization, but users can also add their own plugins if they so
|
|
wish.
|
|
.Sp
|
|
Note that the location of the compiler originated plugins is different
|
|
from the place where the \fBar\fR, \fBnm\fR and
|
|
\&\fBranlib\fR programs search for their plugins. In order for
|
|
those commands to make use of a compiler based plugin it must first be
|
|
copied into the \fI${libdir}/bfd\-plugins\fR directory. All gcc
|
|
based linker plugins are backward compatible, so it is sufficient to
|
|
just copy in the newest one.
|
|
.IP "\fB\-\-push\-state\fR" 4
|
|
.IX Item "--push-state"
|
|
The \fB\-\-push\-state\fR allows to preserve the current state of the
|
|
flags which govern the input file handling so that they can all be
|
|
restored with one corresponding \fB\-\-pop\-state\fR option.
|
|
.Sp
|
|
The option which are covered are: \fB\-Bdynamic\fR, \fB\-Bstatic\fR,
|
|
\&\fB\-dn\fR, \fB\-dy\fR, \fB\-call_shared\fR, \fB\-non_shared\fR,
|
|
\&\fB\-static\fR, \fB\-N\fR, \fB\-n\fR, \fB\-\-whole\-archive\fR,
|
|
\&\fB\-\-no\-whole\-archive\fR, \fB\-r\fR, \fB\-Ur\fR,
|
|
\&\fB\-\-copy\-dt\-needed\-entries\fR, \fB\-\-no\-copy\-dt\-needed\-entries\fR,
|
|
\&\fB\-\-as\-needed\fR, \fB\-\-no\-as\-needed\fR, and \fB\-a\fR.
|
|
.Sp
|
|
One target for this option are specifications for \fIpkg-config\fR. When
|
|
used with the \fB\-\-libs\fR option all possibly needed libraries are
|
|
listed and then possibly linked with all the time. It is better to return
|
|
something as follows:
|
|
.Sp
|
|
.Vb 1
|
|
\& \-Wl,\-\-push\-state,\-\-as\-needed \-libone \-libtwo \-Wl,\-\-pop\-state
|
|
.Ve
|
|
.IP "\fB\-\-pop\-state\fR" 4
|
|
.IX Item "--pop-state"
|
|
Undoes the effect of \-\-push\-state, restores the previous values of the
|
|
flags governing input file handling.
|
|
.IP "\fB\-q\fR" 4
|
|
.IX Item "-q"
|
|
.PD 0
|
|
.IP "\fB\-\-emit\-relocs\fR" 4
|
|
.IX Item "--emit-relocs"
|
|
.PD
|
|
Leave relocation sections and contents in fully linked executables.
|
|
Post link analysis and optimization tools may need this information in
|
|
order to perform correct modifications of executables. This results
|
|
in larger executables.
|
|
.Sp
|
|
This option is currently only supported on \s-1ELF\s0 platforms.
|
|
.IP "\fB\-\-force\-dynamic\fR" 4
|
|
.IX Item "--force-dynamic"
|
|
Force the output file to have dynamic sections. This option is specific
|
|
to VxWorks targets.
|
|
.IP "\fB\-r\fR" 4
|
|
.IX Item "-r"
|
|
.PD 0
|
|
.IP "\fB\-\-relocatable\fR" 4
|
|
.IX Item "--relocatable"
|
|
.PD
|
|
Generate relocatable output\-\-\-i.e., generate an output file that can in
|
|
turn serve as input to \fBld\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(CW\*(C`OMAGIC\*(C'\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
|
|
When an input file does not have the same format as the output file,
|
|
partial linking is only supported if that input file does not contain any
|
|
relocations. Different output formats can have further restrictions; for
|
|
example some \f(CW\*(C`a.out\*(C'\fR\-based formats do not support partial linking
|
|
with input files in other formats at all.
|
|
.Sp
|
|
This option does the same thing as \fB\-i\fR.
|
|
.IP "\fB\-R\fR \fIfilename\fR" 4
|
|
.IX Item "-R filename"
|
|
.PD 0
|
|
.IP "\fB\-\-just\-symbols=\fR\fIfilename\fR" 4
|
|
.IX Item "--just-symbols=filename"
|
|
.PD
|
|
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 \fB\-R\fR option is
|
|
followed by a directory name, rather than a file name, it is treated as
|
|
the \fB\-rpath\fR option.
|
|
.IP "\fB\-s\fR" 4
|
|
.IX Item "-s"
|
|
.PD 0
|
|
.IP "\fB\-\-strip\-all\fR" 4
|
|
.IX Item "--strip-all"
|
|
.PD
|
|
Omit all symbol information from the output file.
|
|
.IP "\fB\-S\fR" 4
|
|
.IX Item "-S"
|
|
.PD 0
|
|
.IP "\fB\-\-strip\-debug\fR" 4
|
|
.IX Item "--strip-debug"
|
|
.PD
|
|
Omit debugger symbol information (but not all symbols) from the output file.
|
|
.IP "\fB\-\-strip\-discarded\fR" 4
|
|
.IX Item "--strip-discarded"
|
|
.PD 0
|
|
.IP "\fB\-\-no\-strip\-discarded\fR" 4
|
|
.IX Item "--no-strip-discarded"
|
|
.PD
|
|
Omit (or do not omit) global symbols defined in discarded sections.
|
|
Enabled by default.
|
|
.IP "\fB\-t\fR" 4
|
|
.IX Item "-t"
|
|
.PD 0
|
|
.IP "\fB\-\-trace\fR" 4
|
|
.IX Item "--trace"
|
|
.PD
|
|
Print the names of the input files as \fBld\fR processes them.
|
|
.IP "\fB\-T\fR \fIscriptfile\fR" 4
|
|
.IX Item "-T scriptfile"
|
|
.PD 0
|
|
.IP "\fB\-\-script=\fR\fIscriptfile\fR" 4
|
|
.IX Item "--script=scriptfile"
|
|
.PD
|
|
Use \fIscriptfile\fR as the linker script. This script replaces
|
|
\&\fBld\fR's default linker script (rather than adding to it), so
|
|
\&\fIcommandfile\fR must specify everything necessary to describe the
|
|
output file. If \fIscriptfile\fR does not exist in
|
|
the current directory, \f(CW\*(C`ld\*(C'\fR looks for it in the directories
|
|
specified by any preceding \fB\-L\fR options. Multiple \fB\-T\fR
|
|
options accumulate.
|
|
.IP "\fB\-dT\fR \fIscriptfile\fR" 4
|
|
.IX Item "-dT scriptfile"
|
|
.PD 0
|
|
.IP "\fB\-\-default\-script=\fR\fIscriptfile\fR" 4
|
|
.IX Item "--default-script=scriptfile"
|
|
.PD
|
|
Use \fIscriptfile\fR as the default linker script.
|
|
.Sp
|
|
This option is similar to the \fB\-\-script\fR option except that
|
|
processing of the script is delayed until after the rest of the
|
|
command line has been processed. This allows options placed after the
|
|
\&\fB\-\-default\-script\fR option on the command line to affect the
|
|
behaviour of the linker script, which can be important when the linker
|
|
command line cannot be directly controlled by the user. (eg because
|
|
the command line is being constructed by another tool, such as
|
|
\&\fBgcc\fR).
|
|
.IP "\fB\-u\fR \fIsymbol\fR" 4
|
|
.IX Item "-u symbol"
|
|
.PD 0
|
|
.IP "\fB\-\-undefined=\fR\fIsymbol\fR" 4
|
|
.IX Item "--undefined=symbol"
|
|
.PD
|
|
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(CW\*(C`EXTERN\*(C'\fR linker script command.
|
|
.Sp
|
|
If this option is being used to force additional modules to be pulled
|
|
into the link, and if it is an error for the symbol to remain
|
|
undefined, then the option \fB\-\-require\-defined\fR should be used
|
|
instead.
|
|
.IP "\fB\-\-require\-defined=\fR\fIsymbol\fR" 4
|
|
.IX Item "--require-defined=symbol"
|
|
Require that \fIsymbol\fR is defined in the output file. This option
|
|
is the same as option \fB\-\-undefined\fR except that if \fIsymbol\fR
|
|
is not defined in the output file then the linker will issue an error
|
|
and exit. The same effect can be achieved in a linker script by using
|
|
\&\f(CW\*(C`EXTERN\*(C'\fR, \f(CW\*(C`ASSERT\*(C'\fR and \f(CW\*(C`DEFINED\*(C'\fR together. This option
|
|
can be used multiple times to require additional symbols.
|
|
.IP "\fB\-Ur\fR" 4
|
|
.IX Item "-Ur"
|
|
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 \fBld\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 "\fB\-\-orphan\-handling=\fR\fI\s-1MODE\s0\fR" 4
|
|
.IX Item "--orphan-handling=MODE"
|
|
Control how orphan sections are handled. An orphan section is one not
|
|
specifically mentioned in a linker script.
|
|
.Sp
|
|
\&\fI\s-1MODE\s0\fR can have any of the following values:
|
|
.RS 4
|
|
.ie n .IP """place""" 4
|
|
.el .IP "\f(CWplace\fR" 4
|
|
.IX Item "place"
|
|
Orphan sections are placed into a suitable output section following
|
|
the strategy described in \fBOrphan Sections\fR. The option
|
|
\&\fB\-\-unique\fR also affects how sections are placed.
|
|
.ie n .IP """discard""" 4
|
|
.el .IP "\f(CWdiscard\fR" 4
|
|
.IX Item "discard"
|
|
All orphan sections are discarded, by placing them in the
|
|
\&\fB/DISCARD/\fR section.
|
|
.ie n .IP """warn""" 4
|
|
.el .IP "\f(CWwarn\fR" 4
|
|
.IX Item "warn"
|
|
The linker will place the orphan section as for \f(CW\*(C`place\*(C'\fR and also
|
|
issue a warning.
|
|
.ie n .IP """error""" 4
|
|
.el .IP "\f(CWerror\fR" 4
|
|
.IX Item "error"
|
|
The linker will exit with an error if any orphan section is found.
|
|
.RE
|
|
.RS 4
|
|
.Sp
|
|
The default if \fB\-\-orphan\-handling\fR is not given is \f(CW\*(C`place\*(C'\fR.
|
|
.RE
|
|
.IP "\fB\-\-unique[=\fR\fI\s-1SECTION\s0\fR\fB]\fR" 4
|
|
.IX Item "--unique[=SECTION]"
|
|
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 "\fB\-v\fR" 4
|
|
.IX Item "-v"
|
|
.PD 0
|
|
.IP "\fB\-\-version\fR" 4
|
|
.IX Item "--version"
|
|
.IP "\fB\-V\fR" 4
|
|
.IX Item "-V"
|
|
.PD
|
|
Display the version number for \fBld\fR. The \fB\-V\fR option also
|
|
lists the supported emulations.
|
|
.IP "\fB\-x\fR" 4
|
|
.IX Item "-x"
|
|
.PD 0
|
|
.IP "\fB\-\-discard\-all\fR" 4
|
|
.IX Item "--discard-all"
|
|
.PD
|
|
Delete all local symbols.
|
|
.IP "\fB\-X\fR" 4
|
|
.IX Item "-X"
|
|
.PD 0
|
|
.IP "\fB\-\-discard\-locals\fR" 4
|
|
.IX Item "--discard-locals"
|
|
.PD
|
|
Delete all temporary local symbols. (These symbols start with
|
|
system-specific local label prefixes, typically \fB.L\fR for \s-1ELF\s0 systems
|
|
or \fBL\fR for traditional a.out systems.)
|
|
.IP "\fB\-y\fR \fIsymbol\fR" 4
|
|
.IX Item "-y symbol"
|
|
.PD 0
|
|
.IP "\fB\-\-trace\-symbol=\fR\fIsymbol\fR" 4
|
|
.IX Item "--trace-symbol=symbol"
|
|
.PD
|
|
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 "\fB\-Y\fR \fIpath\fR" 4
|
|
.IX Item "-Y path"
|
|
Add \fIpath\fR to the default library search path. This option exists
|
|
for Solaris compatibility.
|
|
.IP "\fB\-z\fR \fIkeyword\fR" 4
|
|
.IX Item "-z keyword"
|
|
The recognized keywords are:
|
|
.RS 4
|
|
.IP "\fBcombreloc\fR" 4
|
|
.IX Item "combreloc"
|
|
Combines multiple reloc sections and sorts them to make dynamic symbol
|
|
lookup caching possible.
|
|
.IP "\fBcommon\fR" 4
|
|
.IX Item "common"
|
|
Generate common symbols with the \s-1STT_COMMON\s0 type druing a relocatable
|
|
link.
|
|
.IP "\fBdefs\fR" 4
|
|
.IX Item "defs"
|
|
Disallows undefined symbols in object files. Undefined symbols in
|
|
shared libraries are still allowed.
|
|
.IP "\fBexecstack\fR" 4
|
|
.IX Item "execstack"
|
|
Marks the object as requiring executable stack.
|
|
.IP "\fBglobal\fR" 4
|
|
.IX Item "global"
|
|
This option is only meaningful when building a shared object. It makes
|
|
the symbols defined by this shared object available for symbol resolution
|
|
of subsequently loaded libraries.
|
|
.IP "\fBinitfirst\fR" 4
|
|
.IX Item "initfirst"
|
|
This option is only meaningful when building a shared object.
|
|
It marks the object so that its runtime initialization will occur
|
|
before the runtime initialization of any other objects brought into
|
|
the process at the same time. Similarly the runtime finalization of
|
|
the object will occur after the runtime finalization of any other
|
|
objects.
|
|
.IP "\fBinterpose\fR" 4
|
|
.IX Item "interpose"
|
|
Marks the object that its symbol table interposes before all symbols
|
|
but the primary executable.
|
|
.IP "\fBlazy\fR" 4
|
|
.IX Item "lazy"
|
|
When generating an executable or shared library, mark it to tell the
|
|
dynamic linker to defer function call resolution to the point when
|
|
the function is called (lazy binding), rather than at load time.
|
|
Lazy binding is the default.
|
|
.IP "\fBloadfltr\fR" 4
|
|
.IX Item "loadfltr"
|
|
Marks the object that its filters be processed immediately at
|
|
runtime.
|
|
.IP "\fBmuldefs\fR" 4
|
|
.IX Item "muldefs"
|
|
Allows multiple definitions.
|
|
.IP "\fBnocombreloc\fR" 4
|
|
.IX Item "nocombreloc"
|
|
Disables multiple reloc sections combining.
|
|
.IP "\fBnocommon\fR" 4
|
|
.IX Item "nocommon"
|
|
Generate common symbols with the \s-1STT_OBJECT\s0 type druing a relocatable
|
|
link.
|
|
.IP "\fBnocopyreloc\fR" 4
|
|
.IX Item "nocopyreloc"
|
|
Disable linker generated .dynbss variables used in place of variables
|
|
defined in shared libraries. May result in dynamic text relocations.
|
|
.IP "\fBnodefaultlib\fR" 4
|
|
.IX Item "nodefaultlib"
|
|
Marks the object that the search for dependencies of this object will
|
|
ignore any default library search paths.
|
|
.IP "\fBnodelete\fR" 4
|
|
.IX Item "nodelete"
|
|
Marks the object shouldn't be unloaded at runtime.
|
|
.IP "\fBnodlopen\fR" 4
|
|
.IX Item "nodlopen"
|
|
Marks the object not available to \f(CW\*(C`dlopen\*(C'\fR.
|
|
.IP "\fBnodump\fR" 4
|
|
.IX Item "nodump"
|
|
Marks the object can not be dumped by \f(CW\*(C`dldump\*(C'\fR.
|
|
.IP "\fBnoexecstack\fR" 4
|
|
.IX Item "noexecstack"
|
|
Marks the object as not requiring executable stack.
|
|
.IP "\fBtext\fR" 4
|
|
.IX Item "text"
|
|
Treat \s-1DT_TEXTREL\s0 in shared object as error.
|
|
.IP "\fBnotext\fR" 4
|
|
.IX Item "notext"
|
|
Don't treat \s-1DT_TEXTREL\s0 in shared object as error.
|
|
.IP "\fBtextoff\fR" 4
|
|
.IX Item "textoff"
|
|
Don't treat \s-1DT_TEXTREL\s0 in shared object as error.
|
|
.IP "\fBnorelro\fR" 4
|
|
.IX Item "norelro"
|
|
Don't create an \s-1ELF \s0\f(CW\*(C`PT_GNU_RELRO\*(C'\fR segment header in the object.
|
|
.IP "\fBnow\fR" 4
|
|
.IX Item "now"
|
|
When generating an executable or shared library, mark it to tell the
|
|
dynamic linker to resolve all symbols when the program is started, or
|
|
when the shared library is linked to using dlopen, instead of
|
|
deferring function call resolution to the point when the function is
|
|
first called.
|
|
.IP "\fBorigin\fR" 4
|
|
.IX Item "origin"
|
|
Marks the object may contain \f(CW$ORIGIN\fR.
|
|
.IP "\fBrelro\fR" 4
|
|
.IX Item "relro"
|
|
Create an \s-1ELF \s0\f(CW\*(C`PT_GNU_RELRO\*(C'\fR segment header in the object.
|
|
.IP "\fBmax\-page\-size=\fR\fIvalue\fR" 4
|
|
.IX Item "max-page-size=value"
|
|
Set the emulation maximum page size to \fIvalue\fR.
|
|
.IP "\fBcommon\-page\-size=\fR\fIvalue\fR" 4
|
|
.IX Item "common-page-size=value"
|
|
Set the emulation common page size to \fIvalue\fR.
|
|
.IP "\fBstack\-size=\fR\fIvalue\fR" 4
|
|
.IX Item "stack-size=value"
|
|
Specify a stack size for in an \s-1ELF \s0\f(CW\*(C`PT_GNU_STACK\*(C'\fR segment.
|
|
Specifying zero will override any default non-zero sized
|
|
\&\f(CW\*(C`PT_GNU_STACK\*(C'\fR segment creation.
|
|
.IP "\fBbndplt\fR" 4
|
|
.IX Item "bndplt"
|
|
Always generate \s-1BND\s0 prefix in \s-1PLT\s0 entries. Supported for Linux/x86_64.
|
|
.IP "\fBnoextern-protected-data\fR" 4
|
|
.IX Item "noextern-protected-data"
|
|
Don't treat protected data symbol as external when building shared
|
|
library. This option overrides linker backend default. It can be used
|
|
to workaround incorrect relocations against protected data symbols
|
|
generated by compiler. Updates on protected data symbols by another
|
|
module aren't visible to the resulting shared library. Supported for
|
|
i386 and x86\-64.
|
|
.IP "\fBdynamic-undefined-weak\fR" 4
|
|
.IX Item "dynamic-undefined-weak"
|
|
Make undefined weak symbols dynamic when building a dynamic object,
|
|
if they are referenced from a regular object file and not forced local
|
|
by symbol visibility or versioning. Not all targets support this
|
|
option.
|
|
.IP "\fBnodynamic-undefined-weak\fR" 4
|
|
.IX Item "nodynamic-undefined-weak"
|
|
Do not make undefined weak symbols dynamic when building a dynamic
|
|
object. Not all targets support this option. If neither
|
|
\&\fB\-z nodynamic-undefined-weak\fR nor \fB\-z dynamic-undefined-weak\fR
|
|
are given, a target may default to either option being in force, or
|
|
make some other selection of undefined weak symbols dynamic.
|
|
.IP "\fBnoreloc-overflow\fR" 4
|
|
.IX Item "noreloc-overflow"
|
|
Disable relocation overflow check. This can be used to disable
|
|
relocation overflow check if there will be no dynamic relocation
|
|
overflow at run-time. Supported for x86_64.
|
|
.IP "\fBcall\-nop=prefix\-addr\fR" 4
|
|
.IX Item "call-nop=prefix-addr"
|
|
.PD 0
|
|
.IP "\fBcall\-nop=suffix\-nop\fR" 4
|
|
.IX Item "call-nop=suffix-nop"
|
|
.IP "\fBcall\-nop=prefix\-\fR\fIbyte\fR" 4
|
|
.IX Item "call-nop=prefix-byte"
|
|
.IP "\fBcall\-nop=suffix\-\fR\fIbyte\fR" 4
|
|
.IX Item "call-nop=suffix-byte"
|
|
.PD
|
|
Specify the 1\-byte \f(CW\*(C`NOP\*(C'\fR padding when transforming indirect call
|
|
to a locally defined function, foo, via its \s-1GOT\s0 slot.
|
|
\&\fBcall\-nop=prefix\-addr\fR generates \f(CW\*(C`0x67 call foo\*(C'\fR.
|
|
\&\fBcall\-nop=suffix\-nop\fR generates \f(CW\*(C`call foo 0x90\*(C'\fR.
|
|
\&\fBcall\-nop=prefix\-\fR\fIbyte\fR generates \f(CW\*(C`\f(CIbyte\f(CW call foo\*(C'\fR.
|
|
\&\fBcall\-nop=suffix\-\fR\fIbyte\fR generates \f(CW\*(C`call foo \f(CIbyte\f(CW\*(C'\fR.
|
|
Supported for i386 and x86_64.
|
|
.IP "\fBibtplt\fR" 4
|
|
.IX Item "ibtplt"
|
|
Generate Intel Indirect Branch Tracking (\s-1IBT\s0) enabled \s-1PLT\s0 entries.
|
|
Supported for Linux/i386 and Linux/x86_64.
|
|
.IP "\fB\s-1IBT\s0\fR" 4
|
|
.IX Item "IBT"
|
|
Generate \s-1GNU_PROPERTY_X86_FEATURE_1_IBT\s0 in .note.gnu.property section
|
|
to indicate compatibility with \s-1IBT. \s0 This also implies \fBibtplt\fR.
|
|
Supported for Linux/i386 and Linux/x86_64.
|
|
.IP "\fBshstk\fR" 4
|
|
.IX Item "shstk"
|
|
Generate \s-1GNU_PROPERTY_X86_FEATURE_1_SHSTK\s0 in .note.gnu.property section
|
|
to indicate compatibility with Intel Shadow Stack. Supported for
|
|
Linux/i386 and Linux/x86_64.
|
|
.RE
|
|
.RS 4
|
|
.Sp
|
|
Other keywords are ignored for Solaris compatibility.
|
|
.RE
|
|
.IP "\fB\-(\fR \fIarchives\fR \fB\-)\fR" 4
|
|
.IX Item "-( archives -)"
|
|
.PD 0
|
|
.IP "\fB\-\-start\-group\fR \fIarchives\fR \fB\-\-end\-group\fR" 4
|
|
.IX Item "--start-group archives --end-group"
|
|
.PD
|
|
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 "\fB\-\-accept\-unknown\-input\-arch\fR" 4
|
|
.IX Item "--accept-unknown-input-arch"
|
|
.PD 0
|
|
.IP "\fB\-\-no\-accept\-unknown\-input\-arch\fR" 4
|
|
.IX Item "--no-accept-unknown-input-arch"
|
|
.PD
|
|
Tells the linker to accept input files whose architecture cannot be
|
|
recognised. The assumption is that the user knows what they are doing
|
|
and deliberately wants to link in these unknown input files. This was
|
|
the default behaviour of the linker, before release 2.14. The default
|
|
behaviour from release 2.14 onwards is to reject such input files, and
|
|
so the \fB\-\-accept\-unknown\-input\-arch\fR option has been added to
|
|
restore the old behaviour.
|
|
.IP "\fB\-\-as\-needed\fR" 4
|
|
.IX Item "--as-needed"
|
|
.PD 0
|
|
.IP "\fB\-\-no\-as\-needed\fR" 4
|
|
.IX Item "--no-as-needed"
|
|
.PD
|
|
This option affects \s-1ELF DT_NEEDED\s0 tags for dynamic libraries mentioned
|
|
on the command line after the \fB\-\-as\-needed\fR option. Normally
|
|
the linker will add a \s-1DT_NEEDED\s0 tag for each dynamic library mentioned
|
|
on the command line, regardless of whether the library is actually
|
|
needed or not. \fB\-\-as\-needed\fR causes a \s-1DT_NEEDED\s0 tag to only be
|
|
emitted for a library that \fIat that point in the link\fR satisfies a
|
|
non-weak undefined symbol reference from a regular object file or, if
|
|
the library is not found in the \s-1DT_NEEDED\s0 lists of other needed libraries, a
|
|
non-weak undefined symbol reference from another needed dynamic library.
|
|
Object files or libraries appearing on the command line \fIafter\fR
|
|
the library in question do not affect whether the library is seen as
|
|
needed. This is similar to the rules for extraction of object files
|
|
from archives. \fB\-\-no\-as\-needed\fR restores the default behaviour.
|
|
.IP "\fB\-\-add\-needed\fR" 4
|
|
.IX Item "--add-needed"
|
|
.PD 0
|
|
.IP "\fB\-\-no\-add\-needed\fR" 4
|
|
.IX Item "--no-add-needed"
|
|
.PD
|
|
These two options have been deprecated because of the similarity of
|
|
their names to the \fB\-\-as\-needed\fR and \fB\-\-no\-as\-needed\fR
|
|
options. They have been replaced by \fB\-\-copy\-dt\-needed\-entries\fR
|
|
and \fB\-\-no\-copy\-dt\-needed\-entries\fR.
|
|
.IP "\fB\-assert\fR \fIkeyword\fR" 4
|
|
.IX Item "-assert keyword"
|
|
This option is ignored for SunOS compatibility.
|
|
.IP "\fB\-Bdynamic\fR" 4
|
|
.IX Item "-Bdynamic"
|
|
.PD 0
|
|
.IP "\fB\-dy\fR" 4
|
|
.IX Item "-dy"
|
|
.IP "\fB\-call_shared\fR" 4
|
|
.IX Item "-call_shared"
|
|
.PD
|
|
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
|
|
\&\fB\-l\fR options which follow it.
|
|
.IP "\fB\-Bgroup\fR" 4
|
|
.IX Item "-Bgroup"
|
|
Set the \f(CW\*(C`DF_1_GROUP\*(C'\fR flag in the \f(CW\*(C`DT_FLAGS_1\*(C'\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.
|
|
\&\fB\-\-unresolved\-symbols=report\-all\fR is implied. This option is
|
|
only meaningful on \s-1ELF\s0 platforms which support shared libraries.
|
|
.IP "\fB\-Bstatic\fR" 4
|
|
.IX Item "-Bstatic"
|
|
.PD 0
|
|
.IP "\fB\-dn\fR" 4
|
|
.IX Item "-dn"
|
|
.IP "\fB\-non_shared\fR" 4
|
|
.IX Item "-non_shared"
|
|
.IP "\fB\-static\fR" 4
|
|
.IX Item "-static"
|
|
.PD
|
|
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 \fB\-l\fR options which follow it. This
|
|
option also implies \fB\-\-unresolved\-symbols=report\-all\fR. This
|
|
option can be used with \fB\-shared\fR. Doing so means that a
|
|
shared library is being created but that all of the library's external
|
|
references must be resolved by pulling in entries from static
|
|
libraries.
|
|
.IP "\fB\-Bsymbolic\fR" 4
|
|
.IX Item "-Bsymbolic"
|
|
When creating a shared library, bind references to global symbols to the
|
|
definition within the shared library, if any. Normally, it is possible
|
|
for a program linked against a shared library to override the definition
|
|
within the shared library. This option can also be used with the
|
|
\&\fB\-\-export\-dynamic\fR option, when creating a position independent
|
|
executable, to bind references to global symbols to the definition within
|
|
the executable. This option is only meaningful on \s-1ELF\s0 platforms which
|
|
support shared libraries and position independent executables.
|
|
.IP "\fB\-Bsymbolic\-functions\fR" 4
|
|
.IX Item "-Bsymbolic-functions"
|
|
When creating a shared library, bind references to global function
|
|
symbols to the definition within the shared library, if any.
|
|
This option can also be used with the \fB\-\-export\-dynamic\fR option,
|
|
when creating a position independent executable, to bind references
|
|
to global function symbols to the definition within the executable.
|
|
This option is only meaningful on \s-1ELF\s0 platforms which support shared
|
|
libraries and position independent executables.
|
|
.IP "\fB\-\-dynamic\-list=\fR\fIdynamic-list-file\fR" 4
|
|
.IX Item "--dynamic-list=dynamic-list-file"
|
|
Specify the name of a dynamic list file to the linker. This is
|
|
typically used when creating shared libraries to specify a list of
|
|
global symbols whose references shouldn't be bound to the definition
|
|
within the shared library, or creating dynamically linked executables
|
|
to specify a list of symbols which should be added to the symbol table
|
|
in the executable. This option is only meaningful on \s-1ELF\s0 platforms
|
|
which support shared libraries.
|
|
.Sp
|
|
The format of the dynamic list is the same as the version node without
|
|
scope and node name. See \fB\s-1VERSION\s0\fR for more information.
|
|
.IP "\fB\-\-dynamic\-list\-data\fR" 4
|
|
.IX Item "--dynamic-list-data"
|
|
Include all global data symbols to the dynamic list.
|
|
.IP "\fB\-\-dynamic\-list\-cpp\-new\fR" 4
|
|
.IX Item "--dynamic-list-cpp-new"
|
|
Provide the builtin dynamic list for \*(C+ operator new and delete. It
|
|
is mainly useful for building shared libstdc++.
|
|
.IP "\fB\-\-dynamic\-list\-cpp\-typeinfo\fR" 4
|
|
.IX Item "--dynamic-list-cpp-typeinfo"
|
|
Provide the builtin dynamic list for \*(C+ runtime type identification.
|
|
.IP "\fB\-\-check\-sections\fR" 4
|
|
.IX Item "--check-sections"
|
|
.PD 0
|
|
.IP "\fB\-\-no\-check\-sections\fR" 4
|
|
.IX Item "--no-check-sections"
|
|
.PD
|
|
Asks the linker \fInot\fR to check section addresses after they have
|
|
been assigned to see if there are 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.
|
|
Section overlap is not usually checked for relocatable links. You can
|
|
force checking in that case by using the \fB\-\-check\-sections\fR
|
|
option.
|
|
.IP "\fB\-\-copy\-dt\-needed\-entries\fR" 4
|
|
.IX Item "--copy-dt-needed-entries"
|
|
.PD 0
|
|
.IP "\fB\-\-no\-copy\-dt\-needed\-entries\fR" 4
|
|
.IX Item "--no-copy-dt-needed-entries"
|
|
.PD
|
|
This option affects the treatment of dynamic libraries referred to
|
|
by \s-1DT_NEEDED\s0 tags \fIinside\fR \s-1ELF\s0 dynamic libraries mentioned on the
|
|
command line. Normally the linker won't add a \s-1DT_NEEDED\s0 tag to the
|
|
output binary for each library mentioned in a \s-1DT_NEEDED\s0 tag in an
|
|
input dynamic library. With \fB\-\-copy\-dt\-needed\-entries\fR
|
|
specified on the command line however any dynamic libraries that
|
|
follow it will have their \s-1DT_NEEDED\s0 entries added. The default
|
|
behaviour can be restored with \fB\-\-no\-copy\-dt\-needed\-entries\fR.
|
|
.Sp
|
|
This option also has an effect on the resolution of symbols in dynamic
|
|
libraries. With \fB\-\-copy\-dt\-needed\-entries\fR dynamic libraries
|
|
mentioned on the command line will be recursively searched, following
|
|
their \s-1DT_NEEDED\s0 tags to other libraries, in order to resolve symbols
|
|
required by the output binary. With the default setting however
|
|
the searching of dynamic libraries that follow it will stop with the
|
|
dynamic library itself. No \s-1DT_NEEDED\s0 links will be traversed to resolve
|
|
symbols.
|
|
.IP "\fB\-\-cref\fR" 4
|
|
.IX Item "--cref"
|
|
Output a cross reference table. If a linker map file is being
|
|
generated, the cross reference table is printed to the map file.
|
|
Otherwise, it is printed on the standard output.
|
|
.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. If the symbol is defined as a common value then any files
|
|
where this happens appear next. Finally any files that reference the
|
|
symbol are listed.
|
|
.IP "\fB\-\-no\-define\-common\fR" 4
|
|
.IX Item "--no-define-common"
|
|
This option inhibits the assignment of addresses to common symbols.
|
|
The script command \f(CW\*(C`INHIBIT_COMMON_ALLOCATION\*(C'\fR has the same effect.
|
|
.Sp
|
|
The \fB\-\-no\-define\-common\fR option allows decoupling
|
|
the decision to assign addresses to Common symbols from the choice
|
|
of the output file type; otherwise a non-Relocatable output type
|
|
forces assigning addresses to Common symbols.
|
|
Using \fB\-\-no\-define\-common\fR allows Common symbols that are referenced
|
|
from a shared library to be assigned addresses only in the main program.
|
|
This eliminates the unused duplicate space in the shared library,
|
|
and also prevents any possible confusion over resolving to the wrong
|
|
duplicate when there are many dynamic modules with specialized search
|
|
paths for runtime symbol resolution.
|
|
.IP "\fB\-\-force\-group\-allocation\fR" 4
|
|
.IX Item "--force-group-allocation"
|
|
This option causes the linker to place section group members like
|
|
normal input sections, and to delete the section groups. This is the
|
|
default behaviour for a final link but this option can be used to
|
|
change the behaviour of a relocatable link (\fB\-r\fR). The script
|
|
command \f(CW\*(C`FORCE_GROUP_ALLOCATION\*(C'\fR has the same
|
|
effect.
|
|
.IP "\fB\-\-defsym=\fR\fIsymbol\fR\fB=\fR\fIexpression\fR" 4
|
|
.IX Item "--defsym=symbol=expression"
|
|
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\*(C`+\*(C'\fR and \f(CW\*(C`\-\*(C'\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 "\fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR" 4
|
|
.IX Item "--demangle[=style]"
|
|
.PD 0
|
|
.IP "\fB\-\-no\-demangle\fR" 4
|
|
.IX Item "--no-demangle"
|
|
.PD
|
|
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 "\fB\-I\fR\fIfile\fR" 4
|
|
.IX Item "-Ifile"
|
|
.PD 0
|
|
.IP "\fB\-\-dynamic\-linker=\fR\fIfile\fR" 4
|
|
.IX Item "--dynamic-linker=file"
|
|
.PD
|
|
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 "\fB\-\-no\-dynamic\-linker\fR" 4
|
|
.IX Item "--no-dynamic-linker"
|
|
When producing an executable file, omit the request for a dynamic
|
|
linker to be used at load-time. This is only meaningful for \s-1ELF\s0
|
|
executables that contain dynamic relocations, and usually requires
|
|
entry point code that is capable of processing these relocations.
|
|
.IP "\fB\-\-embedded\-relocs\fR" 4
|
|
.IX Item "--embedded-relocs"
|
|
This option is similar to the \fB\-\-emit\-relocs\fR option except
|
|
that the relocs are stored in a target specific section. This option
|
|
is only supported by the \fB\s-1BFIN\s0\fR, \fB\s-1CR16\s0\fR and \fIM68K\fR
|
|
targets.
|
|
.IP "\fB\-\-fatal\-warnings\fR" 4
|
|
.IX Item "--fatal-warnings"
|
|
.PD 0
|
|
.IP "\fB\-\-no\-fatal\-warnings\fR" 4
|
|
.IX Item "--no-fatal-warnings"
|
|
.PD
|
|
Treat all warnings as errors. The default behaviour can be restored
|
|
with the option \fB\-\-no\-fatal\-warnings\fR.
|
|
.IP "\fB\-\-force\-exe\-suffix\fR" 4
|
|
.IX Item "--force-exe-suffix"
|
|
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\*(C`.exe\*(C'\fR or \f(CW\*(C`.dll\*(C'\fR suffix, this option forces the linker to copy
|
|
the output file to one of the same name with a \f(CW\*(C`.exe\*(C'\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\*(C`.exe\*(C'\fR suffix.
|
|
.IP "\fB\-\-gc\-sections\fR" 4
|
|
.IX Item "--gc-sections"
|
|
.PD 0
|
|
.IP "\fB\-\-no\-gc\-sections\fR" 4
|
|
.IX Item "--no-gc-sections"
|
|
.PD
|
|
Enable garbage collection of unused input sections. It is ignored on
|
|
targets that do not support this option. The default behaviour (of not
|
|
performing this garbage collection) can be restored by specifying
|
|
\&\fB\-\-no\-gc\-sections\fR on the command line. Note that garbage
|
|
collection for \s-1COFF\s0 and \s-1PE\s0 format targets is supported, but the
|
|
implementation is currently considered to be experimental.
|
|
.Sp
|
|
\&\fB\-\-gc\-sections\fR decides which input sections are used by
|
|
examining symbols and relocations. The section containing the entry
|
|
symbol and all sections containing symbols undefined on the
|
|
command-line will be kept, as will sections containing symbols
|
|
referenced by dynamic objects. Note that when building shared
|
|
libraries, the linker must assume that any visible symbol is
|
|
referenced. Once this initial set of sections has been determined,
|
|
the linker recursively marks as used any section referenced by their
|
|
relocations. See \fB\-\-entry\fR and \fB\-\-undefined\fR.
|
|
.Sp
|
|
This option can be set when doing a partial link (enabled with option
|
|
\&\fB\-r\fR). In this case the root of symbols kept must be explicitly
|
|
specified either by an \fB\-\-entry\fR or \fB\-\-undefined\fR option or by
|
|
a \f(CW\*(C`ENTRY\*(C'\fR command in the linker script.
|
|
.IP "\fB\-\-print\-gc\-sections\fR" 4
|
|
.IX Item "--print-gc-sections"
|
|
.PD 0
|
|
.IP "\fB\-\-no\-print\-gc\-sections\fR" 4
|
|
.IX Item "--no-print-gc-sections"
|
|
.PD
|
|
List all sections removed by garbage collection. The listing is
|
|
printed on stderr. This option is only effective if garbage
|
|
collection has been enabled via the \fB\-\-gc\-sections\fR) option. The
|
|
default behaviour (of not listing the sections that are removed) can
|
|
be restored by specifying \fB\-\-no\-print\-gc\-sections\fR on the command
|
|
line.
|
|
.IP "\fB\-\-gc\-keep\-exported\fR" 4
|
|
.IX Item "--gc-keep-exported"
|
|
When \fB\-\-gc\-sections\fR is enabled, this option prevents garbage
|
|
collection of unused input sections that contain global symbols having
|
|
default or protected visibility. This option is intended to be used for
|
|
executables where unreferenced sections would otherwise be garbage
|
|
collected regardless of the external visibility of contained symbols.
|
|
Note that this option has no effect when linking shared objects since
|
|
it is already the default behaviour. This option is only supported for
|
|
\&\s-1ELF\s0 format targets.
|
|
.IP "\fB\-\-print\-output\-format\fR" 4
|
|
.IX Item "--print-output-format"
|
|
Print the name of the default output format (perhaps influenced by
|
|
other command-line options). This is the string that would appear
|
|
in an \f(CW\*(C`OUTPUT_FORMAT\*(C'\fR linker script command.
|
|
.IP "\fB\-\-print\-memory\-usage\fR" 4
|
|
.IX Item "--print-memory-usage"
|
|
Print used size, total size and used size of memory regions created with
|
|
the \fB\s-1MEMORY\s0\fR command. This is useful on embedded targets to have a
|
|
quick view of amount of free memory. The format of the output has one
|
|
headline and one line per region. It is both human readable and easily
|
|
parsable by tools. Here is an example of an output:
|
|
.Sp
|
|
.Vb 3
|
|
\& Memory region Used Size Region Size %age Used
|
|
\& ROM: 256 KB 1 MB 25.00%
|
|
\& RAM: 32 B 2 GB 0.00%
|
|
.Ve
|
|
.IP "\fB\-\-help\fR" 4
|
|
.IX Item "--help"
|
|
Print a summary of the command-line options on the standard output and exit.
|
|
.IP "\fB\-\-target\-help\fR" 4
|
|
.IX Item "--target-help"
|
|
Print a summary of all target specific options on the standard output and exit.
|
|
.IP "\fB\-Map=\fR\fImapfile\fR" 4
|
|
.IX Item "-Map=mapfile"
|
|
Print a link map to the file \fImapfile\fR. See the description of the
|
|
\&\fB\-M\fR option, above.
|
|
.IP "\fB\-\-no\-keep\-memory\fR" 4
|
|
.IX Item "--no-keep-memory"
|
|
\&\fBld\fR normally optimizes for speed over memory usage by caching the
|
|
symbol tables of input files in memory. This option tells \fBld\fR to
|
|
instead optimize for memory usage, by rereading the symbol tables as
|
|
necessary. This may be required if \fBld\fR runs out of memory space
|
|
while linking a large executable.
|
|
.IP "\fB\-\-no\-undefined\fR" 4
|
|
.IX Item "--no-undefined"
|
|
.PD 0
|
|
.IP "\fB\-z defs\fR" 4
|
|
.IX Item "-z defs"
|
|
.PD
|
|
Report unresolved symbol references from regular object files. This
|
|
is done even if the linker is creating a non-symbolic shared library.
|
|
The switch \fB\-\-[no\-]allow\-shlib\-undefined\fR controls the
|
|
behaviour for reporting unresolved references found in shared
|
|
libraries being linked in.
|
|
.IP "\fB\-\-allow\-multiple\-definition\fR" 4
|
|
.IX Item "--allow-multiple-definition"
|
|
.PD 0
|
|
.IP "\fB\-z muldefs\fR" 4
|
|
.IX Item "-z muldefs"
|
|
.PD
|
|
Normally when a symbol is defined multiple times, the linker will
|
|
report a fatal error. These options allow multiple definitions and the
|
|
first definition will be used.
|
|
.IP "\fB\-\-allow\-shlib\-undefined\fR" 4
|
|
.IX Item "--allow-shlib-undefined"
|
|
.PD 0
|
|
.IP "\fB\-\-no\-allow\-shlib\-undefined\fR" 4
|
|
.IX Item "--no-allow-shlib-undefined"
|
|
.PD
|
|
Allows or disallows undefined symbols in shared libraries.
|
|
This switch is similar to \fB\-\-no\-undefined\fR except that it
|
|
determines the behaviour when the undefined symbols are in a
|
|
shared library rather than a regular object file. It does not affect
|
|
how undefined symbols in regular object files are handled.
|
|
.Sp
|
|
The default behaviour is to report errors for any undefined symbols
|
|
referenced in shared libraries if the linker is being used to create
|
|
an executable, but to allow them if the linker is being used to create
|
|
a shared library.
|
|
.Sp
|
|
The reasons for allowing undefined symbol references in shared
|
|
libraries specified at link time are that:
|
|
.RS 4
|
|
.IP "\(bu" 4
|
|
A shared library specified at link time may not be the same as the one
|
|
that is available at load time, so the symbol might actually be
|
|
resolvable at load time.
|
|
.IP "\(bu" 4
|
|
There are some operating systems, eg BeOS and \s-1HPPA,\s0 where undefined
|
|
symbols in shared libraries are normal.
|
|
.Sp
|
|
The BeOS kernel for example patches shared libraries at load time to
|
|
select whichever function is most appropriate for the current
|
|
architecture. This is used, for example, to dynamically select an
|
|
appropriate memset function.
|
|
.RE
|
|
.RS 4
|
|
.RE
|
|
.IP "\fB\-\-no\-undefined\-version\fR" 4
|
|
.IX Item "--no-undefined-version"
|
|
Normally when a symbol has an undefined version, the linker will ignore
|
|
it. This option disallows symbols with undefined version and a fatal error
|
|
will be issued instead.
|
|
.IP "\fB\-\-default\-symver\fR" 4
|
|
.IX Item "--default-symver"
|
|
Create and use a default symbol version (the soname) for unversioned
|
|
exported symbols.
|
|
.IP "\fB\-\-default\-imported\-symver\fR" 4
|
|
.IX Item "--default-imported-symver"
|
|
Create and use a default symbol version (the soname) for unversioned
|
|
imported symbols.
|
|
.IP "\fB\-\-no\-warn\-mismatch\fR" 4
|
|
.IX Item "--no-warn-mismatch"
|
|
Normally \fBld\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 \fBld\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 "\fB\-\-no\-warn\-search\-mismatch\fR" 4
|
|
.IX Item "--no-warn-search-mismatch"
|
|
Normally \fBld\fR will give a warning if it finds an incompatible
|
|
library during a library search. This option silences the warning.
|
|
.IP "\fB\-\-no\-whole\-archive\fR" 4
|
|
.IX Item "--no-whole-archive"
|
|
Turn off the effect of the \fB\-\-whole\-archive\fR option for subsequent
|
|
archive files.
|
|
.IP "\fB\-\-noinhibit\-exec\fR" 4
|
|
.IX Item "--noinhibit-exec"
|
|
Retain the executable output file whenever it is still usable.
|
|
Normally, the linker will not produce an output file if it encounters
|
|
errors during the link process; it exits without writing an output file
|
|
when it issues any error whatsoever.
|
|
.IP "\fB\-nostdlib\fR" 4
|
|
.IX Item "-nostdlib"
|
|
Only search library directories explicitly specified on the
|
|
command line. Library directories specified in linker scripts
|
|
(including linker scripts specified on the command line) are ignored.
|
|
.IP "\fB\-\-oformat=\fR\fIoutput-format\fR" 4
|
|
.IX Item "--oformat=output-format"
|
|
\&\fBld\fR may be configured to support more than one kind of object
|
|
file. If your \fBld\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 \fBld\fR is configured to support alternative
|
|
object formats, you don't usually need to specify this, as \fBld\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(CW\*(C`OUTPUT_FORMAT\*(C'\fR can also specify the output format, but
|
|
this option overrides it.
|
|
.IP "\fB\-\-out\-implib\fR \fIfile\fR" 4
|
|
.IX Item "--out-implib file"
|
|
Create an import library in \fIfile\fR corresponding to the executable
|
|
the linker is generating (eg. a \s-1DLL\s0 or \s-1ELF\s0 program). This import
|
|
library (which should be called \f(CW\*(C`*.dll.a\*(C'\fR or \f(CW\*(C`*.a\*(C'\fR for DLLs)
|
|
may be used to link clients against the generated executable; this
|
|
behaviour makes it possible to skip a separate import library creation
|
|
step (eg. \f(CW\*(C`dlltool\*(C'\fR for DLLs). This option is only available for
|
|
the i386 \s-1PE\s0 and \s-1ELF\s0 targetted ports of the linker.
|
|
.IP "\fB\-pie\fR" 4
|
|
.IX Item "-pie"
|
|
.PD 0
|
|
.IP "\fB\-\-pic\-executable\fR" 4
|
|
.IX Item "--pic-executable"
|
|
.PD
|
|
Create a position independent executable. This is currently only supported on
|
|
\&\s-1ELF\s0 platforms. Position independent executables are similar to shared
|
|
libraries in that they are relocated by the dynamic linker to the virtual
|
|
address the \s-1OS\s0 chooses for them (which can vary between invocations). Like
|
|
normal dynamically linked executables they can be executed and symbols
|
|
defined in the executable cannot be overridden by shared libraries.
|
|
.IP "\fB\-qmagic\fR" 4
|
|
.IX Item "-qmagic"
|
|
This option is ignored for Linux compatibility.
|
|
.IP "\fB\-Qy\fR" 4
|
|
.IX Item "-Qy"
|
|
This option is ignored for \s-1SVR4\s0 compatibility.
|
|
.IP "\fB\-\-relax\fR" 4
|
|
.IX Item "--relax"
|
|
.PD 0
|
|
.IP "\fB\-\-no\-relax\fR" 4
|
|
.IX Item "--no-relax"
|
|
.PD
|
|
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 target specific,
|
|
global optimizations that become possible when the linker resolves
|
|
addressing in the program, such as relaxing address modes,
|
|
synthesizing new instructions, selecting shorter version of current
|
|
instructions, and combining constant values.
|
|
.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.
|
|
.Sp
|
|
On platforms where \fB\-\-relax\fR is accepted the option
|
|
\&\fB\-\-no\-relax\fR can be used to disable the feature.
|
|
.IP "\fB\-\-retain\-symbols\-file=\fR\fIfilename\fR" 4
|
|
.IX Item "--retain-symbols-file=filename"
|
|
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 "\fB\-rpath=\fR\fIdir\fR" 4
|
|
.IX Item "-rpath=dir"
|
|
Add a directory to the runtime library search path. This is used when
|
|
linking an \s-1ELF\s0 executable with shared objects. All \fB\-rpath\fR
|
|
arguments are concatenated and passed to the runtime linker, which uses
|
|
them to locate shared objects at runtime. The \fB\-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
|
|
\&\fB\-rpath\-link\fR option. If \fB\-rpath\fR is not used when linking an
|
|
\&\s-1ELF\s0 executable, the contents of the environment variable
|
|
\&\f(CW\*(C`LD_RUN_PATH\*(C'\fR will be used if it is defined.
|
|
.Sp
|
|
The \fB\-rpath\fR option may also be used on SunOS. By default, on
|
|
SunOS, the linker will form a runtime search path out of all the
|
|
\&\fB\-L\fR options it is given. If a \fB\-rpath\fR option is used, the
|
|
runtime search path will be formed exclusively using the \fB\-rpath\fR
|
|
options, ignoring the \fB\-L\fR options. This can be useful when using
|
|
gcc, which adds many \fB\-L\fR options which may be on \s-1NFS\s0 mounted
|
|
file systems.
|
|
.Sp
|
|
For compatibility with other \s-1ELF\s0 linkers, if the \fB\-R\fR option is
|
|
followed by a directory name, rather than a file name, it is treated as
|
|
the \fB\-rpath\fR option.
|
|
.IP "\fB\-rpath\-link=\fR\fIdir\fR" 4
|
|
.IX Item "-rpath-link=dir"
|
|
When using \s-1ELF\s0 or SunOS, one shared library may require another. This
|
|
happens when an \f(CW\*(C`ld \-shared\*(C'\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 \fB\-rpath\-link\fR option
|
|
specifies the first set of directories to search. The
|
|
\&\fB\-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
|
|
The tokens \fI\f(CI$ORIGIN\fI\fR and \fI\f(CI$LIB\fI\fR can appear in these search
|
|
directories. They will be replaced by the full path to the directory
|
|
containing the program or shared object in the case of \fI\f(CI$ORIGIN\fI\fR
|
|
and either \fBlib\fR \- for 32\-bit binaries \- or \fBlib64\fR \- for
|
|
64\-bit binaries \- in the case of \fI\f(CI$LIB\fI\fR.
|
|
.Sp
|
|
The alternative form of these tokens \- \fI${\s-1ORIGIN\s0}\fR and
|
|
\&\fI${\s-1LIB\s0}\fR can also be used. The token \fI\f(CI$PLATFORM\fI\fR is not
|
|
supported.
|
|
.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:
|
|
.RS 4
|
|
.IP "1." 4
|
|
Any directories specified by \fB\-rpath\-link\fR options.
|
|
.IP "2." 4
|
|
Any directories specified by \fB\-rpath\fR options. The difference
|
|
between \fB\-rpath\fR and \fB\-rpath\-link\fR is that directories
|
|
specified by \fB\-rpath\fR options are included in the executable and
|
|
used at runtime, whereas the \fB\-rpath\-link\fR option is only effective
|
|
at link time. Searching \fB\-rpath\fR in this way is only supported
|
|
by native linkers and cross linkers which have been configured with
|
|
the \fB\-\-with\-sysroot\fR option.
|
|
.IP "3." 4
|
|
On an \s-1ELF\s0 system, for native linkers, if the \fB\-rpath\fR and
|
|
\&\fB\-rpath\-link\fR options were not used, search the contents of the
|
|
environment variable \f(CW\*(C`LD_RUN_PATH\*(C'\fR.
|
|
.IP "4." 4
|
|
On SunOS, if the \fB\-rpath\fR option was not used, search any
|
|
directories specified using \fB\-L\fR options.
|
|
.IP "5." 4
|
|
For a native linker, search the contents of the environment
|
|
variable \f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR.
|
|
.IP "6." 4
|
|
For a native \s-1ELF\s0 linker, the directories in \f(CW\*(C`DT_RUNPATH\*(C'\fR or
|
|
\&\f(CW\*(C`DT_RPATH\*(C'\fR of a shared library are searched for shared
|
|
libraries needed by it. The \f(CW\*(C`DT_RPATH\*(C'\fR entries are ignored if
|
|
\&\f(CW\*(C`DT_RUNPATH\*(C'\fR entries exist.
|
|
.IP "7." 4
|
|
The default directories, normally \fI/lib\fR and \fI/usr/lib\fR.
|
|
.IP "8." 4
|
|
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.
|
|
.RE
|
|
.RS 4
|
|
.Sp
|
|
If the required shared library is not found, the linker will issue a
|
|
warning and continue with the link.
|
|
.RE
|
|
.IP "\fB\-shared\fR" 4
|
|
.IX Item "-shared"
|
|
.PD 0
|
|
.IP "\fB\-Bshareable\fR" 4
|
|
.IX Item "-Bshareable"
|
|
.PD
|
|
Create a shared library. This is currently only supported on \s-1ELF, XCOFF\s0
|
|
and SunOS platforms. On SunOS, the linker will automatically create a
|
|
shared library if the \fB\-e\fR option is not used and there are
|
|
undefined symbols in the link.
|
|
.IP "\fB\-\-sort\-common\fR" 4
|
|
.IX Item "--sort-common"
|
|
.PD 0
|
|
.IP "\fB\-\-sort\-common=ascending\fR" 4
|
|
.IX Item "--sort-common=ascending"
|
|
.IP "\fB\-\-sort\-common=descending\fR" 4
|
|
.IX Item "--sort-common=descending"
|
|
.PD
|
|
This option tells \fBld\fR to sort the common symbols by alignment in
|
|
ascending or descending order when it places them in the appropriate output
|
|
sections. The symbol alignments considered are sixteen-byte or larger,
|
|
eight-byte, four-byte, two-byte, and one-byte. This is to prevent gaps
|
|
between symbols due to alignment constraints. If no sorting order is
|
|
specified, then descending order is assumed.
|
|
.IP "\fB\-\-sort\-section=name\fR" 4
|
|
.IX Item "--sort-section=name"
|
|
This option will apply \f(CW\*(C`SORT_BY_NAME\*(C'\fR to all wildcard section
|
|
patterns in the linker script.
|
|
.IP "\fB\-\-sort\-section=alignment\fR" 4
|
|
.IX Item "--sort-section=alignment"
|
|
This option will apply \f(CW\*(C`SORT_BY_ALIGNMENT\*(C'\fR to all wildcard section
|
|
patterns in the linker script.
|
|
.IP "\fB\-\-spare\-dynamic\-tags=\fR\fIcount\fR" 4
|
|
.IX Item "--spare-dynamic-tags=count"
|
|
This option specifies the number of empty slots to leave in the
|
|
\&.dynamic section of \s-1ELF\s0 shared objects. Empty slots may be needed by
|
|
post processing tools, such as the prelinker. The default is 5.
|
|
.IP "\fB\-\-split\-by\-file[=\fR\fIsize\fR\fB]\fR" 4
|
|
.IX Item "--split-by-file[=size]"
|
|
Similar to \fB\-\-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 "\fB\-\-split\-by\-reloc[=\fR\fIcount\fR\fB]\fR" 4
|
|
.IX Item "--split-by-reloc[=count]"
|
|
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 "\fB\-\-stats\fR" 4
|
|
.IX Item "--stats"
|
|
Compute and display statistics about the operation of the linker, such
|
|
as execution time and memory usage.
|
|
.IP "\fB\-\-sysroot=\fR\fIdirectory\fR" 4
|
|
.IX Item "--sysroot=directory"
|
|
Use \fIdirectory\fR as the location of the sysroot, overriding the
|
|
configure-time default. This option is only supported by linkers
|
|
that were configured using \fB\-\-with\-sysroot\fR.
|
|
.IP "\fB\-\-task\-link\fR" 4
|
|
.IX Item "--task-link"
|
|
This is used by \s-1COFF/PE\s0 based targets to create a task-linked object
|
|
file where all of the global symbols have been converted to statics.
|
|
.IP "\fB\-\-traditional\-format\fR" 4
|
|
.IX Item "--traditional-format"
|
|
For some targets, the output of \fBld\fR is different in some ways from
|
|
the output of some existing linker. This switch requests \fBld\fR to
|
|
use the traditional format instead.
|
|
.Sp
|
|
For example, on SunOS, \fBld\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(CW\*(C`dbx\*(C'\fR program can not read the resulting program (\f(CW\*(C`gdb\*(C'\fR has no
|
|
trouble). The \fB\-\-traditional\-format\fR switch tells \fBld\fR to not
|
|
combine duplicate entries.
|
|
.IP "\fB\-\-section\-start=\fR\fIsectionname\fR\fB=\fR\fIorg\fR" 4
|
|
.IX Item "--section-start=sectionname=org"
|
|
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 "\fB\-Tbss=\fR\fIorg\fR" 4
|
|
.IX Item "-Tbss=org"
|
|
.PD 0
|
|
.IP "\fB\-Tdata=\fR\fIorg\fR" 4
|
|
.IX Item "-Tdata=org"
|
|
.IP "\fB\-Ttext=\fR\fIorg\fR" 4
|
|
.IX Item "-Ttext=org"
|
|
.PD
|
|
Same as \fB\-\-section\-start\fR, with \f(CW\*(C`.bss\*(C'\fR, \f(CW\*(C`.data\*(C'\fR or
|
|
\&\f(CW\*(C`.text\*(C'\fR as the \fIsectionname\fR.
|
|
.IP "\fB\-Ttext\-segment=\fR\fIorg\fR" 4
|
|
.IX Item "-Ttext-segment=org"
|
|
When creating an \s-1ELF\s0 executable, it will set the address of the first
|
|
byte of the text segment.
|
|
.IP "\fB\-Trodata\-segment=\fR\fIorg\fR" 4
|
|
.IX Item "-Trodata-segment=org"
|
|
When creating an \s-1ELF\s0 executable or shared object for a target where
|
|
the read-only data is in its own segment separate from the executable
|
|
text, it will set the address of the first byte of the read-only data segment.
|
|
.IP "\fB\-Tldata\-segment=\fR\fIorg\fR" 4
|
|
.IX Item "-Tldata-segment=org"
|
|
When creating an \s-1ELF\s0 executable or shared object for x86\-64 medium memory
|
|
model, it will set the address of the first byte of the ldata segment.
|
|
.IP "\fB\-\-unresolved\-symbols=\fR\fImethod\fR" 4
|
|
.IX Item "--unresolved-symbols=method"
|
|
Determine how to handle unresolved symbols. There are four possible
|
|
values for \fBmethod\fR:
|
|
.RS 4
|
|
.IP "\fBignore-all\fR" 4
|
|
.IX Item "ignore-all"
|
|
Do not report any unresolved symbols.
|
|
.IP "\fBreport-all\fR" 4
|
|
.IX Item "report-all"
|
|
Report all unresolved symbols. This is the default.
|
|
.IP "\fBignore-in-object-files\fR" 4
|
|
.IX Item "ignore-in-object-files"
|
|
Report unresolved symbols that are contained in shared libraries, but
|
|
ignore them if they come from regular object files.
|
|
.IP "\fBignore-in-shared-libs\fR" 4
|
|
.IX Item "ignore-in-shared-libs"
|
|
Report unresolved symbols that come from regular object files, but
|
|
ignore them if they come from shared libraries. This can be useful
|
|
when creating a dynamic binary and it is known that all the shared
|
|
libraries that it should be referencing are included on the linker's
|
|
command line.
|
|
.RE
|
|
.RS 4
|
|
.Sp
|
|
The behaviour for shared libraries on their own can also be controlled
|
|
by the \fB\-\-[no\-]allow\-shlib\-undefined\fR option.
|
|
.Sp
|
|
Normally the linker will generate an error message for each reported
|
|
unresolved symbol but the option \fB\-\-warn\-unresolved\-symbols\fR
|
|
can change this to a warning.
|
|
.RE
|
|
.IP "\fB\-\-dll\-verbose\fR" 4
|
|
.IX Item "--dll-verbose"
|
|
.PD 0
|
|
.IP "\fB\-\-verbose[=\fR\fI\s-1NUMBER\s0\fR\fB]\fR" 4
|
|
.IX Item "--verbose[=NUMBER]"
|
|
.PD
|
|
Display the version number for \fBld\fR and list the linker emulations
|
|
supported. Display which input files can and cannot be opened. Display
|
|
the linker script being used by the linker. If the optional \fI\s-1NUMBER\s0\fR
|
|
argument > 1, plugin symbol status will also be displayed.
|
|
.IP "\fB\-\-version\-script=\fR\fIversion-scriptfile\fR" 4
|
|
.IX Item "--version-script=version-scriptfile"
|
|
Specify the name of a version script to the linker. This is typically
|
|
used when creating shared libraries to specify additional information
|
|
about the version hierarchy for the library being created. This option
|
|
is only fully supported on \s-1ELF\s0 platforms which support shared libraries;
|
|
see \fB\s-1VERSION\s0\fR. It is partially supported on \s-1PE\s0 platforms, which can
|
|
use version scripts to filter symbol visibility in auto-export mode: any
|
|
symbols marked \fBlocal\fR in the version script will not be exported.
|
|
.IP "\fB\-\-warn\-common\fR" 4
|
|
.IX Item "--warn-common"
|
|
Warn when a common symbol is combined with another common symbol or with
|
|
a symbol definition. Unix linkers allow this somewhat sloppy practice,
|
|
but linkers on some other operating systems do not. This option allows
|
|
you to find potential problems from combining global symbols.
|
|
Unfortunately, some C libraries use this practice, so you may get some
|
|
warnings about symbols in the libraries as well as in your programs.
|
|
.Sp
|
|
There are three kinds of global symbols, illustrated here by C examples:
|
|
.RS 4
|
|
.IP "\fBint i = 1;\fR" 4
|
|
.IX Item "int i = 1;"
|
|
A definition, which goes in the initialized data section of the output
|
|
file.
|
|
.IP "\fBextern int i;\fR" 4
|
|
.IX Item "extern int i;"
|
|
An undefined reference, which does not allocate space.
|
|
There must be either a definition or a common symbol for the
|
|
variable somewhere.
|
|
.IP "\fBint i;\fR" 4
|
|
.IX Item "int i;"
|
|
A common symbol. If there are only (one or more) common symbols for a
|
|
variable, it goes in the uninitialized data area of the output file.
|
|
The linker merges multiple common symbols for the same variable into a
|
|
single symbol. If they are of different sizes, it picks the largest
|
|
size. The linker turns a common symbol into a declaration, if there is
|
|
a definition of the same variable.
|
|
.RE
|
|
.RS 4
|
|
.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." 4
|
|
Turning a common symbol into a reference, because there is already a
|
|
definition for the symbol.
|
|
.Sp
|
|
.Vb 3
|
|
\& <file>(<section>): warning: common of \`<symbol>\*(Aq
|
|
\& overridden by definition
|
|
\& <file>(<section>): warning: defined here
|
|
.Ve
|
|
.IP "2." 4
|
|
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.
|
|
.Sp
|
|
.Vb 3
|
|
\& <file>(<section>): warning: definition of \`<symbol>\*(Aq
|
|
\& overriding common
|
|
\& <file>(<section>): warning: common is here
|
|
.Ve
|
|
.IP "3." 4
|
|
Merging a common symbol with a previous same-sized common symbol.
|
|
.Sp
|
|
.Vb 3
|
|
\& <file>(<section>): warning: multiple common
|
|
\& of \`<symbol>\*(Aq
|
|
\& <file>(<section>): warning: previous common is here
|
|
.Ve
|
|
.IP "4." 4
|
|
Merging a common symbol with a previous larger common symbol.
|
|
.Sp
|
|
.Vb 3
|
|
\& <file>(<section>): warning: common of \`<symbol>\*(Aq
|
|
\& overridden by larger common
|
|
\& <file>(<section>): warning: larger common is here
|
|
.Ve
|
|
.IP "5." 4
|
|
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.
|
|
.Sp
|
|
.Vb 3
|
|
\& <file>(<section>): warning: common of \`<symbol>\*(Aq
|
|
\& overriding smaller common
|
|
\& <file>(<section>): warning: smaller common is here
|
|
.Ve
|
|
.RE
|
|
.RS 4
|
|
.RE
|
|
.IP "\fB\-\-warn\-constructors\fR" 4
|
|
.IX Item "--warn-constructors"
|
|
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 "\fB\-\-warn\-multiple\-gp\fR" 4
|
|
.IX Item "--warn-multiple-gp"
|
|
Warn if multiple global pointer values are required in the output file.
|
|
This is only meaningful for certain processors, such as the Alpha.
|
|
Specifically, some processors put large-valued constants in a special
|
|
section. A special register (the global pointer) points into the middle
|
|
of this section, so that constants can be loaded efficiently via a
|
|
base-register relative addressing mode. Since the offset in
|
|
base-register relative mode is fixed and relatively small (e.g., 16
|
|
bits), this limits the maximum size of the constant pool. Thus, in
|
|
large programs, it is often necessary to use multiple global pointer
|
|
values in order to be able to address all possible constants. This
|
|
option causes a warning to be issued whenever this case occurs.
|
|
.IP "\fB\-\-warn\-once\fR" 4
|
|
.IX Item "--warn-once"
|
|
Only warn once for each undefined symbol, rather than once per module
|
|
which refers to it.
|
|
.IP "\fB\-\-warn\-section\-align\fR" 4
|
|
.IX Item "--warn-section-align"
|
|
Warn if the address of an output section is changed because of
|
|
alignment. Typically, the alignment will be set by an input section.
|
|
The address will only be changed if it not explicitly specified; that
|
|
is, if the \f(CW\*(C`SECTIONS\*(C'\fR command does not specify a start address for
|
|
the section.
|
|
.IP "\fB\-\-warn\-shared\-textrel\fR" 4
|
|
.IX Item "--warn-shared-textrel"
|
|
Warn if the linker adds a \s-1DT_TEXTREL\s0 to a shared object.
|
|
.IP "\fB\-\-warn\-alternate\-em\fR" 4
|
|
.IX Item "--warn-alternate-em"
|
|
Warn if an object has alternate \s-1ELF\s0 machine code.
|
|
.IP "\fB\-\-warn\-unresolved\-symbols\fR" 4
|
|
.IX Item "--warn-unresolved-symbols"
|
|
If the linker is going to report an unresolved symbol (see the option
|
|
\&\fB\-\-unresolved\-symbols\fR) it will normally generate an error.
|
|
This option makes it generate a warning instead.
|
|
.IP "\fB\-\-error\-unresolved\-symbols\fR" 4
|
|
.IX Item "--error-unresolved-symbols"
|
|
This restores the linker's default behaviour of generating errors when
|
|
it is reporting unresolved symbols.
|
|
.IP "\fB\-\-whole\-archive\fR" 4
|
|
.IX Item "--whole-archive"
|
|
For each archive mentioned on the command line after the
|
|
\&\fB\-\-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 \fB\-Wl,\-whole\-archive\fR.
|
|
Second, don't forget to use \fB\-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 "\fB\-\-wrap=\fR\fIsymbol\fR" 4
|
|
.IX Item "--wrap=symbol"
|
|
Use a wrapper function for \fIsymbol\fR. Any undefined reference to
|
|
\&\fIsymbol\fR will be resolved to \f(CW\*(C`_\|_wrap_\f(CIsymbol\f(CW\*(C'\fR. Any
|
|
undefined reference to \f(CW\*(C`_\|_real_\f(CIsymbol\f(CW\*(C'\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\*(C`_\|_wrap_\f(CIsymbol\f(CW\*(C'\fR. If it
|
|
wishes to call the system function, it should call
|
|
\&\f(CW\*(C`_\|_real_\f(CIsymbol\f(CW\*(C'\fR.
|
|
.Sp
|
|
Here is a trivial example:
|
|
.Sp
|
|
.Vb 6
|
|
\& void *
|
|
\& _\|_wrap_malloc (size_t c)
|
|
\& {
|
|
\& printf ("malloc called with %zu\en", c);
|
|
\& return _\|_real_malloc (c);
|
|
\& }
|
|
.Ve
|
|
.Sp
|
|
If you link other code with this file using \fB\-\-wrap malloc\fR, then
|
|
all calls to \f(CW\*(C`malloc\*(C'\fR will call the function \f(CW\*(C`_\|_wrap_malloc\*(C'\fR
|
|
instead. The call to \f(CW\*(C`_\|_real_malloc\*(C'\fR in \f(CW\*(C`_\|_wrap_malloc\*(C'\fR will
|
|
call the real \f(CW\*(C`malloc\*(C'\fR function.
|
|
.Sp
|
|
You may wish to provide a \f(CW\*(C`_\|_real_malloc\*(C'\fR function as well, so that
|
|
links without the \fB\-\-wrap\fR option will succeed. If you do this,
|
|
you should not put the definition of \f(CW\*(C`_\|_real_malloc\*(C'\fR in the same
|
|
file as \f(CW\*(C`_\|_wrap_malloc\*(C'\fR; if you do, the assembler may resolve the
|
|
call before the linker has a chance to wrap it to \f(CW\*(C`malloc\*(C'\fR.
|
|
.IP "\fB\-\-eh\-frame\-hdr\fR" 4
|
|
.IX Item "--eh-frame-hdr"
|
|
.PD 0
|
|
.IP "\fB\-\-no\-eh\-frame\-hdr\fR" 4
|
|
.IX Item "--no-eh-frame-hdr"
|
|
.PD
|
|
Request (\fB\-\-eh\-frame\-hdr\fR) or suppress
|
|
(\fB\-\-no\-eh\-frame\-hdr\fR) the creation of \f(CW\*(C`.eh_frame_hdr\*(C'\fR
|
|
section and \s-1ELF \s0\f(CW\*(C`PT_GNU_EH_FRAME\*(C'\fR segment header.
|
|
.IP "\fB\-\-no\-ld\-generated\-unwind\-info\fR" 4
|
|
.IX Item "--no-ld-generated-unwind-info"
|
|
Request creation of \f(CW\*(C`.eh_frame\*(C'\fR unwind info for linker
|
|
generated code sections like \s-1PLT. \s0 This option is on by default
|
|
if linker generated unwind info is supported.
|
|
.IP "\fB\-\-enable\-new\-dtags\fR" 4
|
|
.IX Item "--enable-new-dtags"
|
|
.PD 0
|
|
.IP "\fB\-\-disable\-new\-dtags\fR" 4
|
|
.IX Item "--disable-new-dtags"
|
|
.PD
|
|
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
|
|
\&\fB\-\-enable\-new\-dtags\fR, the new dynamic tags will be created as needed
|
|
and older dynamic tags will be omitted.
|
|
If you specify \fB\-\-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.
|
|
.IP "\fB\-\-hash\-size=\fR\fInumber\fR" 4
|
|
.IX Item "--hash-size=number"
|
|
Set the default size of the linker's hash tables to a prime number
|
|
close to \fInumber\fR. Increasing this value can reduce the length of
|
|
time it takes the linker to perform its tasks, at the expense of
|
|
increasing the linker's memory requirements. Similarly reducing this
|
|
value can reduce the memory requirements at the expense of speed.
|
|
.IP "\fB\-\-hash\-style=\fR\fIstyle\fR" 4
|
|
.IX Item "--hash-style=style"
|
|
Set the type of linker's hash table(s). \fIstyle\fR can be either
|
|
\&\f(CW\*(C`sysv\*(C'\fR for classic \s-1ELF \s0\f(CW\*(C`.hash\*(C'\fR section, \f(CW\*(C`gnu\*(C'\fR for
|
|
new style \s-1GNU \s0\f(CW\*(C`.gnu.hash\*(C'\fR section or \f(CW\*(C`both\*(C'\fR for both
|
|
the classic \s-1ELF \s0\f(CW\*(C`.hash\*(C'\fR and new style \s-1GNU \s0\f(CW\*(C`.gnu.hash\*(C'\fR
|
|
hash tables. The default is \f(CW\*(C`sysv\*(C'\fR.
|
|
.IP "\fB\-\-compress\-debug\-sections=none\fR" 4
|
|
.IX Item "--compress-debug-sections=none"
|
|
.PD 0
|
|
.IP "\fB\-\-compress\-debug\-sections=zlib\fR" 4
|
|
.IX Item "--compress-debug-sections=zlib"
|
|
.IP "\fB\-\-compress\-debug\-sections=zlib\-gnu\fR" 4
|
|
.IX Item "--compress-debug-sections=zlib-gnu"
|
|
.IP "\fB\-\-compress\-debug\-sections=zlib\-gabi\fR" 4
|
|
.IX Item "--compress-debug-sections=zlib-gabi"
|
|
.PD
|
|
On \s-1ELF\s0 platforms, these options control how \s-1DWARF\s0 debug sections are
|
|
compressed using zlib.
|
|
.Sp
|
|
\&\fB\-\-compress\-debug\-sections=none\fR doesn't compress \s-1DWARF\s0 debug
|
|
sections. \fB\-\-compress\-debug\-sections=zlib\-gnu\fR compresses
|
|
\&\s-1DWARF\s0 debug sections and renames them to begin with \fB.zdebug\fR
|
|
instead of \fB.debug\fR. \fB\-\-compress\-debug\-sections=zlib\-gabi\fR
|
|
also compresses \s-1DWARF\s0 debug sections, but rather than renaming them it
|
|
sets the \s-1SHF_COMPRESSED\s0 flag in the sections' headers.
|
|
.Sp
|
|
The \fB\-\-compress\-debug\-sections=zlib\fR option is an alias for
|
|
\&\fB\-\-compress\-debug\-sections=zlib\-gabi\fR.
|
|
.Sp
|
|
Note that this option overrides any compression in input debug
|
|
sections, so if a binary is linked with \fB\-\-compress\-debug\-sections=none\fR
|
|
for example, then any compressed debug sections in input files will be
|
|
uncompressed before they are copied into the output binary.
|
|
.Sp
|
|
The default compression behaviour varies depending upon the target
|
|
involved and the configure options used to build the toolchain. The
|
|
default can be determined by examining the output from the linker's
|
|
\&\fB\-\-help\fR option.
|
|
.IP "\fB\-\-reduce\-memory\-overheads\fR" 4
|
|
.IX Item "--reduce-memory-overheads"
|
|
This option reduces memory requirements at ld runtime, at the expense of
|
|
linking speed. This was introduced to select the old O(n^2) algorithm
|
|
for link map file generation, rather than the new O(n) algorithm which uses
|
|
about 40% more memory for symbol storage.
|
|
.Sp
|
|
Another effect of the switch is to set the default hash table size to
|
|
1021, which again saves memory at the cost of lengthening the linker's
|
|
run time. This is not done however if the \fB\-\-hash\-size\fR switch
|
|
has been used.
|
|
.Sp
|
|
The \fB\-\-reduce\-memory\-overheads\fR switch may be also be used to
|
|
enable other tradeoffs in future versions of the linker.
|
|
.IP "\fB\-\-build\-id\fR" 4
|
|
.IX Item "--build-id"
|
|
.PD 0
|
|
.IP "\fB\-\-build\-id=\fR\fIstyle\fR" 4
|
|
.IX Item "--build-id=style"
|
|
.PD
|
|
Request the creation of a \f(CW\*(C`.note.gnu.build\-id\*(C'\fR \s-1ELF\s0 note section
|
|
or a \f(CW\*(C`.buildid\*(C'\fR \s-1COFF\s0 section. The contents of the note are
|
|
unique bits identifying this linked file. \fIstyle\fR can be
|
|
\&\f(CW\*(C`uuid\*(C'\fR to use 128 random bits, \f(CW\*(C`sha1\*(C'\fR to use a 160\-bit
|
|
\&\s-1SHA1\s0 hash on the normative parts of the output contents,
|
|
\&\f(CW\*(C`md5\*(C'\fR to use a 128\-bit \s-1MD5\s0 hash on the normative parts of
|
|
the output contents, or \f(CW\*(C`0x\f(CIhexstring\f(CW\*(C'\fR to use a chosen bit
|
|
string specified as an even number of hexadecimal digits (\f(CW\*(C`\-\*(C'\fR and
|
|
\&\f(CW\*(C`:\*(C'\fR characters between digit pairs are ignored). If \fIstyle\fR
|
|
is omitted, \f(CW\*(C`sha1\*(C'\fR is used.
|
|
.Sp
|
|
The \f(CW\*(C`md5\*(C'\fR and \f(CW\*(C`sha1\*(C'\fR styles produces an identifier
|
|
that is always the same in an identical output file, but will be
|
|
unique among all nonidentical output files. It is not intended
|
|
to be compared as a checksum for the file's contents. A linked
|
|
file may be changed later by other tools, but the build \s-1ID\s0 bit
|
|
string identifying the original linked file does not change.
|
|
.Sp
|
|
Passing \f(CW\*(C`none\*(C'\fR for \fIstyle\fR disables the setting from any
|
|
\&\f(CW\*(C`\-\-build\-id\*(C'\fR options earlier on the command line.
|
|
.PP
|
|
The i386 \s-1PE\s0 linker supports the \fB\-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\*(C`*.dll\*(C'\fR when you
|
|
use this option. In addition, the linker fully supports the standard
|
|
\&\f(CW\*(C`*.def\*(C'\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 "\fB\-\-add\-stdcall\-alias\fR" 4
|
|
.IX Item "--add-stdcall-alias"
|
|
If given, symbols with a stdcall suffix (@\fInn\fR) will be exported
|
|
as-is and also with the suffix stripped.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-base\-file\fR \fIfile\fR" 4
|
|
.IX Item "--base-file file"
|
|
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.
|
|
[This is an i386 \s-1PE\s0 specific option]
|
|
.IP "\fB\-\-dll\fR" 4
|
|
.IX Item "--dll"
|
|
Create a \s-1DLL\s0 instead of a regular executable. You may also use
|
|
\&\fB\-shared\fR or specify a \f(CW\*(C`LIBRARY\*(C'\fR in a given \f(CW\*(C`.def\*(C'\fR
|
|
file.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-enable\-long\-section\-names\fR" 4
|
|
.IX Item "--enable-long-section-names"
|
|
.PD 0
|
|
.IP "\fB\-\-disable\-long\-section\-names\fR" 4
|
|
.IX Item "--disable-long-section-names"
|
|
.PD
|
|
The \s-1PE\s0 variants of the \s-1COFF\s0 object format add an extension that permits
|
|
the use of section names longer than eight characters, the normal limit
|
|
for \s-1COFF. \s0 By default, these names are only allowed in object files, as
|
|
fully-linked executable images do not carry the \s-1COFF\s0 string table required
|
|
to support the longer names. As a \s-1GNU\s0 extension, it is possible to
|
|
allow their use in executable images as well, or to (probably pointlessly!)
|
|
disallow it in object files, by using these two options. Executable images
|
|
generated with these long section names are slightly non-standard, carrying
|
|
as they do a string table, and may generate confusing output when examined
|
|
with non-GNU PE-aware tools, such as file viewers and dumpers. However,
|
|
\&\s-1GDB\s0 relies on the use of \s-1PE\s0 long section names to find Dwarf\-2 debug
|
|
information sections in an executable image at runtime, and so if neither
|
|
option is specified on the command-line, \fBld\fR will enable long
|
|
section names, overriding the default and technically correct behaviour,
|
|
when it finds the presence of debug information while linking an executable
|
|
image and not stripping symbols.
|
|
[This option is valid for all \s-1PE\s0 targeted ports of the linker]
|
|
.IP "\fB\-\-enable\-stdcall\-fixup\fR" 4
|
|
.IX Item "--enable-stdcall-fixup"
|
|
.PD 0
|
|
.IP "\fB\-\-disable\-stdcall\-fixup\fR" 4
|
|
.IX Item "--disable-stdcall-fixup"
|
|
.PD
|
|
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\*(C`_foo\*(C'\fR might be linked to the function
|
|
\&\f(CW\*(C`_foo@12\*(C'\fR, or the undefined symbol \f(CW\*(C`_bar@16\*(C'\fR might be linked
|
|
to the function \f(CW\*(C`_bar\*(C'\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 \fB\-\-enable\-stdcall\-fixup\fR, this
|
|
feature is fully enabled and warnings are not printed. If you specify
|
|
\&\fB\-\-disable\-stdcall\-fixup\fR, this feature is disabled and such
|
|
mismatches are considered to be errors.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-leading\-underscore\fR" 4
|
|
.IX Item "--leading-underscore"
|
|
.PD 0
|
|
.IP "\fB\-\-no\-leading\-underscore\fR" 4
|
|
.IX Item "--no-leading-underscore"
|
|
.PD
|
|
For most targets default symbol-prefix is an underscore and is defined
|
|
in target's description. By this option it is possible to
|
|
disable/enable the default underscore symbol-prefix.
|
|
.IP "\fB\-\-export\-all\-symbols\fR" 4
|
|
.IX Item "--export-all-symbols"
|
|
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(CW\*(C`DllMain@12\*(C'\fR,
|
|
\&\f(CW\*(C`DllEntryPoint@0\*(C'\fR, \f(CW\*(C`DllMainCRTStartup@12\*(C'\fR, and
|
|
\&\f(CW\*(C`impure_ptr\*(C'\fR will not be automatically
|
|
exported. Also, symbols imported from other DLLs will not be
|
|
re-exported, nor will symbols specifying the \s-1DLL\s0's internal layout
|
|
such as those beginning with \f(CW\*(C`_head_\*(C'\fR or ending with
|
|
\&\f(CW\*(C`_iname\*(C'\fR. In addition, no symbols from \f(CW\*(C`libgcc\*(C'\fR,
|
|
\&\f(CW\*(C`libstd++\*(C'\fR, \f(CW\*(C`libmingw32\*(C'\fR, or \f(CW\*(C`crtX.o\*(C'\fR will be exported.
|
|
Symbols whose names begin with \f(CW\*(C`_\|_rtti_\*(C'\fR or \f(CW\*(C`_\|_builtin_\*(C'\fR will
|
|
not be exported, to help with \*(C+ DLLs. Finally, there is an
|
|
extensive list of cygwin-private symbols that are not exported
|
|
(obviously, this applies on when building DLLs for cygwin targets).
|
|
These cygwin-excludes are: \f(CW\*(C`_cygwin_dll_entry@12\*(C'\fR,
|
|
\&\f(CW\*(C`_cygwin_crt0_common@8\*(C'\fR, \f(CW\*(C`_cygwin_noncygwin_dll_entry@12\*(C'\fR,
|
|
\&\f(CW\*(C`_fmode\*(C'\fR, \f(CW\*(C`_impure_ptr\*(C'\fR, \f(CW\*(C`cygwin_attach_dll\*(C'\fR,
|
|
\&\f(CW\*(C`cygwin_premain0\*(C'\fR, \f(CW\*(C`cygwin_premain1\*(C'\fR, \f(CW\*(C`cygwin_premain2\*(C'\fR,
|
|
\&\f(CW\*(C`cygwin_premain3\*(C'\fR, and \f(CW\*(C`environ\*(C'\fR.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-exclude\-symbols\fR \fIsymbol\fR\fB,\fR\fIsymbol\fR\fB,...\fR" 4
|
|
.IX Item "--exclude-symbols symbol,symbol,..."
|
|
Specifies a list of symbols which should not be automatically
|
|
exported. The symbol names may be delimited by commas or colons.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-exclude\-all\-symbols\fR" 4
|
|
.IX Item "--exclude-all-symbols"
|
|
Specifies no symbols should be automatically exported.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-file\-alignment\fR" 4
|
|
.IX Item "--file-alignment"
|
|
Specify the file alignment. Sections in the file will always begin at
|
|
file offsets which are multiples of this number. This defaults to
|
|
512.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-heap\fR \fIreserve\fR" 4
|
|
.IX Item "--heap reserve"
|
|
.PD 0
|
|
.IP "\fB\-\-heap\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4
|
|
.IX Item "--heap reserve,commit"
|
|
.PD
|
|
Specify the number of bytes of memory to reserve (and optionally commit)
|
|
to be used as heap for this program. The default is 1MB reserved, 4K
|
|
committed.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-image\-base\fR \fIvalue\fR" 4
|
|
.IX Item "--image-base value"
|
|
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.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-kill\-at\fR" 4
|
|
.IX Item "--kill-at"
|
|
If given, the stdcall suffixes (@\fInn\fR) will be stripped from
|
|
symbols before they are exported.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-large\-address\-aware\fR" 4
|
|
.IX Item "--large-address-aware"
|
|
If given, the appropriate bit in the \*(L"Characteristics\*(R" field of the \s-1COFF\s0
|
|
header is set to indicate that this executable supports virtual addresses
|
|
greater than 2 gigabytes. This should be used in conjunction with the /3GB
|
|
or /USERVA=\fIvalue\fR megabytes switch in the \*(L"[operating systems]\*(R"
|
|
section of the \s-1BOOT.INI. \s0 Otherwise, this bit has no effect.
|
|
[This option is specific to \s-1PE\s0 targeted ports of the linker]
|
|
.IP "\fB\-\-disable\-large\-address\-aware\fR" 4
|
|
.IX Item "--disable-large-address-aware"
|
|
Reverts the effect of a previous \fB\-\-large\-address\-aware\fR option.
|
|
This is useful if \fB\-\-large\-address\-aware\fR is always set by the compiler
|
|
driver (e.g. Cygwin gcc) and the executable does not support virtual
|
|
addresses greater than 2 gigabytes.
|
|
[This option is specific to \s-1PE\s0 targeted ports of the linker]
|
|
.IP "\fB\-\-major\-image\-version\fR \fIvalue\fR" 4
|
|
.IX Item "--major-image-version value"
|
|
Sets the major number of the \*(L"image version\*(R". Defaults to 1.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-major\-os\-version\fR \fIvalue\fR" 4
|
|
.IX Item "--major-os-version value"
|
|
Sets the major number of the \*(L"os version\*(R". Defaults to 4.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-major\-subsystem\-version\fR \fIvalue\fR" 4
|
|
.IX Item "--major-subsystem-version value"
|
|
Sets the major number of the \*(L"subsystem version\*(R". Defaults to 4.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-minor\-image\-version\fR \fIvalue\fR" 4
|
|
.IX Item "--minor-image-version value"
|
|
Sets the minor number of the \*(L"image version\*(R". Defaults to 0.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-minor\-os\-version\fR \fIvalue\fR" 4
|
|
.IX Item "--minor-os-version value"
|
|
Sets the minor number of the \*(L"os version\*(R". Defaults to 0.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-minor\-subsystem\-version\fR \fIvalue\fR" 4
|
|
.IX Item "--minor-subsystem-version value"
|
|
Sets the minor number of the \*(L"subsystem version\*(R". Defaults to 0.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-output\-def\fR \fIfile\fR" 4
|
|
.IX Item "--output-def file"
|
|
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\*(C`*.def\*(C'\fR) may be used to create an import
|
|
library with \f(CW\*(C`dlltool\*(C'\fR or may be used as a reference to
|
|
automatically or implicitly exported symbols.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-enable\-auto\-image\-base\fR" 4
|
|
.IX Item "--enable-auto-image-base"
|
|
.PD 0
|
|
.IP "\fB\-\-enable\-auto\-image\-base=\fR\fIvalue\fR" 4
|
|
.IX Item "--enable-auto-image-base=value"
|
|
.PD
|
|
Automatically choose the image base for DLLs, optionally starting with base
|
|
\&\fIvalue\fR, unless one is specified using the \f(CW\*(C`\-\-image\-base\*(C'\fR argument.
|
|
By using a hash generated from the dllname to create unique image bases
|
|
for each \s-1DLL,\s0 in-memory collisions and relocations which can delay program
|
|
execution are avoided.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-disable\-auto\-image\-base\fR" 4
|
|
.IX Item "--disable-auto-image-base"
|
|
Do not automatically generate a unique image base. If there is no
|
|
user-specified image base (\f(CW\*(C`\-\-image\-base\*(C'\fR) then use the platform
|
|
default.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-dll\-search\-prefix\fR \fIstring\fR" 4
|
|
.IX Item "--dll-search-prefix string"
|
|
When linking dynamically to a dll without an import library,
|
|
search for \f(CW\*(C`<string><basename>.dll\*(C'\fR in preference to
|
|
\&\f(CW\*(C`lib<basename>.dll\*(C'\fR. This behaviour allows easy distinction
|
|
between DLLs built for the various \*(L"subplatforms\*(R": native, cygwin,
|
|
uwin, pw, etc. For instance, cygwin DLLs typically use
|
|
\&\f(CW\*(C`\-\-dll\-search\-prefix=cyg\*(C'\fR.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-enable\-auto\-import\fR" 4
|
|
.IX Item "--enable-auto-import"
|
|
Do sophisticated linking of \f(CW\*(C`_symbol\*(C'\fR to \f(CW\*(C`_\|_imp_\|_symbol\*(C'\fR for
|
|
\&\s-1DATA\s0 imports from DLLs, and create the necessary thunking symbols when
|
|
building the import libraries with those \s-1DATA\s0 exports. Note: Use of the
|
|
\&'auto\-import' extension will cause the text section of the image file
|
|
to be made writable. This does not conform to the PE-COFF format
|
|
specification published by Microsoft.
|
|
.Sp
|
|
Note \- use of the 'auto\-import' extension will also cause read only
|
|
data which would normally be placed into the .rdata section to be
|
|
placed into the .data section instead. This is in order to work
|
|
around a problem with consts that is described here:
|
|
http://www.cygwin.com/ml/cygwin/2004\-09/msg01101.html
|
|
.Sp
|
|
Using 'auto\-import' generally will 'just work' \*(-- but sometimes you may
|
|
see this message:
|
|
.Sp
|
|
"variable '<var>' can't be auto-imported. Please read the
|
|
documentation for ld's \f(CW\*(C`\-\-enable\-auto\-import\*(C'\fR for details."
|
|
.Sp
|
|
This message occurs when some (sub)expression accesses an address
|
|
ultimately given by the sum of two constants (Win32 import tables only
|
|
allow one). Instances where this may occur include accesses to member
|
|
fields of struct variables imported from a \s-1DLL,\s0 as well as using a
|
|
constant index into an array variable imported from a \s-1DLL. \s0 Any
|
|
multiword variable (arrays, structs, long long, etc) may trigger
|
|
this error condition. However, regardless of the exact data type
|
|
of the offending exported variable, ld will always detect it, issue
|
|
the warning, and exit.
|
|
.Sp
|
|
There are several ways to address this difficulty, regardless of the
|
|
data type of the exported variable:
|
|
.Sp
|
|
One way is to use \-\-enable\-runtime\-pseudo\-reloc switch. This leaves the task
|
|
of adjusting references in your client code for runtime environment, so
|
|
this method works only when runtime environment supports this feature.
|
|
.Sp
|
|
A second solution is to force one of the 'constants' to be a variable \*(--
|
|
that is, unknown and un-optimizable at compile time. For arrays,
|
|
there are two possibilities: a) make the indexee (the array's address)
|
|
a variable, or b) make the 'constant' index a variable. Thus:
|
|
.Sp
|
|
.Vb 3
|
|
\& extern type extern_array[];
|
|
\& extern_array[1] \-\->
|
|
\& { volatile type *t=extern_array; t[1] }
|
|
.Ve
|
|
.Sp
|
|
or
|
|
.Sp
|
|
.Vb 3
|
|
\& extern type extern_array[];
|
|
\& extern_array[1] \-\->
|
|
\& { volatile int t=1; extern_array[t] }
|
|
.Ve
|
|
.Sp
|
|
For structs (and most other multiword data types) the only option
|
|
is to make the struct itself (or the long long, or the ...) variable:
|
|
.Sp
|
|
.Vb 3
|
|
\& extern struct s extern_struct;
|
|
\& extern_struct.field \-\->
|
|
\& { volatile struct s *t=&extern_struct; t\->field }
|
|
.Ve
|
|
.Sp
|
|
or
|
|
.Sp
|
|
.Vb 3
|
|
\& extern long long extern_ll;
|
|
\& extern_ll \-\->
|
|
\& { volatile long long * local_ll=&extern_ll; *local_ll }
|
|
.Ve
|
|
.Sp
|
|
A third method of dealing with this difficulty is to abandon
|
|
\&'auto\-import' for the offending symbol and mark it with
|
|
\&\f(CW\*(C`_\|_declspec(dllimport)\*(C'\fR. However, in practice that
|
|
requires using compile-time #defines to indicate whether you are
|
|
building a \s-1DLL,\s0 building client code that will link to the \s-1DLL,\s0 or
|
|
merely building/linking to a static library. In making the choice
|
|
between the various methods of resolving the 'direct address with
|
|
constant offset' problem, you should consider typical real-world usage:
|
|
.Sp
|
|
Original:
|
|
.Sp
|
|
.Vb 7
|
|
\& \-\-foo.h
|
|
\& extern int arr[];
|
|
\& \-\-foo.c
|
|
\& #include "foo.h"
|
|
\& void main(int argc, char **argv){
|
|
\& printf("%d\en",arr[1]);
|
|
\& }
|
|
.Ve
|
|
.Sp
|
|
Solution 1:
|
|
.Sp
|
|
.Vb 9
|
|
\& \-\-foo.h
|
|
\& extern int arr[];
|
|
\& \-\-foo.c
|
|
\& #include "foo.h"
|
|
\& void main(int argc, char **argv){
|
|
\& /* This workaround is for win32 and cygwin; do not "optimize" */
|
|
\& volatile int *parr = arr;
|
|
\& printf("%d\en",parr[1]);
|
|
\& }
|
|
.Ve
|
|
.Sp
|
|
Solution 2:
|
|
.Sp
|
|
.Vb 10
|
|
\& \-\-foo.h
|
|
\& /* Note: auto\-export is assumed (no _\|_declspec(dllexport)) */
|
|
\& #if (defined(_WIN32) || defined(_\|_CYGWIN_\|_)) && \e
|
|
\& !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
|
|
\& #define FOO_IMPORT _\|_declspec(dllimport)
|
|
\& #else
|
|
\& #define FOO_IMPORT
|
|
\& #endif
|
|
\& extern FOO_IMPORT int arr[];
|
|
\& \-\-foo.c
|
|
\& #include "foo.h"
|
|
\& void main(int argc, char **argv){
|
|
\& printf("%d\en",arr[1]);
|
|
\& }
|
|
.Ve
|
|
.Sp
|
|
A fourth way to avoid this problem is to re-code your
|
|
library to use a functional interface rather than a data interface
|
|
for the offending variables (e.g. \fIset_foo()\fR and \fIget_foo()\fR accessor
|
|
functions).
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-disable\-auto\-import\fR" 4
|
|
.IX Item "--disable-auto-import"
|
|
Do not attempt to do sophisticated linking of \f(CW\*(C`_symbol\*(C'\fR to
|
|
\&\f(CW\*(C`_\|_imp_\|_symbol\*(C'\fR for \s-1DATA\s0 imports from DLLs.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-enable\-runtime\-pseudo\-reloc\fR" 4
|
|
.IX Item "--enable-runtime-pseudo-reloc"
|
|
If your code contains expressions described in \-\-enable\-auto\-import section,
|
|
that is, \s-1DATA\s0 imports from \s-1DLL\s0 with non-zero offset, this switch will create
|
|
a vector of 'runtime pseudo relocations' which can be used by runtime
|
|
environment to adjust references to such data in your client code.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-disable\-runtime\-pseudo\-reloc\fR" 4
|
|
.IX Item "--disable-runtime-pseudo-reloc"
|
|
Do not create pseudo relocations for non-zero offset \s-1DATA\s0 imports from
|
|
DLLs.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-enable\-extra\-pe\-debug\fR" 4
|
|
.IX Item "--enable-extra-pe-debug"
|
|
Show additional debug info related to auto-import symbol thunking.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-section\-alignment\fR" 4
|
|
.IX Item "--section-alignment"
|
|
Sets the section alignment. Sections in memory will always begin at
|
|
addresses which are a multiple of this number. Defaults to 0x1000.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-stack\fR \fIreserve\fR" 4
|
|
.IX Item "--stack reserve"
|
|
.PD 0
|
|
.IP "\fB\-\-stack\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4
|
|
.IX Item "--stack reserve,commit"
|
|
.PD
|
|
Specify the number of bytes of memory to reserve (and optionally commit)
|
|
to be used as stack for this program. The default is 2MB reserved, 4K
|
|
committed.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.IP "\fB\-\-subsystem\fR \fIwhich\fR" 4
|
|
.IX Item "--subsystem which"
|
|
.PD 0
|
|
.IP "\fB\-\-subsystem\fR \fIwhich\fR\fB:\fR\fImajor\fR" 4
|
|
.IX Item "--subsystem which:major"
|
|
.IP "\fB\-\-subsystem\fR \fIwhich\fR\fB:\fR\fImajor\fR\fB.\fR\fIminor\fR" 4
|
|
.IX Item "--subsystem which:major.minor"
|
|
.PD
|
|
Specifies the subsystem under which your program will execute. The
|
|
legal values for \fIwhich\fR are \f(CW\*(C`native\*(C'\fR, \f(CW\*(C`windows\*(C'\fR,
|
|
\&\f(CW\*(C`console\*(C'\fR, \f(CW\*(C`posix\*(C'\fR, and \f(CW\*(C`xbox\*(C'\fR. You may optionally set
|
|
the subsystem version also. Numeric values are also accepted for
|
|
\&\fIwhich\fR.
|
|
[This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
|
|
.Sp
|
|
The following options set flags in the \f(CW\*(C`DllCharacteristics\*(C'\fR field
|
|
of the \s-1PE\s0 file header:
|
|
[These options are specific to \s-1PE\s0 targeted ports of the linker]
|
|
.IP "\fB\-\-high\-entropy\-va\fR" 4
|
|
.IX Item "--high-entropy-va"
|
|
Image is compatible with 64\-bit address space layout randomization
|
|
(\s-1ASLR\s0).
|
|
.IP "\fB\-\-dynamicbase\fR" 4
|
|
.IX Item "--dynamicbase"
|
|
The image base address may be relocated using address space layout
|
|
randomization (\s-1ASLR\s0). This feature was introduced with \s-1MS\s0 Windows
|
|
Vista for i386 \s-1PE\s0 targets.
|
|
.IP "\fB\-\-forceinteg\fR" 4
|
|
.IX Item "--forceinteg"
|
|
Code integrity checks are enforced.
|
|
.IP "\fB\-\-nxcompat\fR" 4
|
|
.IX Item "--nxcompat"
|
|
The image is compatible with the Data Execution Prevention.
|
|
This feature was introduced with \s-1MS\s0 Windows \s-1XP SP2\s0 for i386 \s-1PE\s0 targets.
|
|
.IP "\fB\-\-no\-isolation\fR" 4
|
|
.IX Item "--no-isolation"
|
|
Although the image understands isolation, do not isolate the image.
|
|
.IP "\fB\-\-no\-seh\fR" 4
|
|
.IX Item "--no-seh"
|
|
The image does not use \s-1SEH.\s0 No \s-1SE\s0 handler may be called from
|
|
this image.
|
|
.IP "\fB\-\-no\-bind\fR" 4
|
|
.IX Item "--no-bind"
|
|
Do not bind this image.
|
|
.IP "\fB\-\-wdmdriver\fR" 4
|
|
.IX Item "--wdmdriver"
|
|
The driver uses the \s-1MS\s0 Windows Driver Model.
|
|
.IP "\fB\-\-tsaware\fR" 4
|
|
.IX Item "--tsaware"
|
|
The image is Terminal Server aware.
|
|
.IP "\fB\-\-insert\-timestamp\fR" 4
|
|
.IX Item "--insert-timestamp"
|
|
.PD 0
|
|
.IP "\fB\-\-no\-insert\-timestamp\fR" 4
|
|
.IX Item "--no-insert-timestamp"
|
|
.PD
|
|
Insert a real timestamp into the image. This is the default behaviour
|
|
as it matches legacy code and it means that the image will work with
|
|
other, proprietary tools. The problem with this default is that it
|
|
will result in slightly different images being produced each time the
|
|
same sources are linked. The option \fB\-\-no\-insert\-timestamp\fR
|
|
can be used to insert a zero value for the timestamp, this ensuring
|
|
that binaries produced from identical sources will compare
|
|
identically.
|
|
.PP
|
|
The C6X uClinux target uses a binary format called \s-1DSBT\s0 to support shared
|
|
libraries. Each shared library in the system needs to have a unique index;
|
|
all executables use an index of 0.
|
|
.IP "\fB\-\-dsbt\-size\fR \fIsize\fR" 4
|
|
.IX Item "--dsbt-size size"
|
|
This option sets the number of entries in the \s-1DSBT\s0 of the current executable
|
|
or shared library to \fIsize\fR. The default is to create a table with 64
|
|
entries.
|
|
.IP "\fB\-\-dsbt\-index\fR \fIindex\fR" 4
|
|
.IX Item "--dsbt-index index"
|
|
This option sets the \s-1DSBT\s0 index of the current executable or shared library
|
|
to \fIindex\fR. The default is 0, which is appropriate for generating
|
|
executables. If a shared library is generated with a \s-1DSBT\s0 index of 0, the
|
|
\&\f(CW\*(C`R_C6000_DSBT_INDEX\*(C'\fR relocs are copied into the output file.
|
|
.Sp
|
|
The \fB\-\-no\-merge\-exidx\-entries\fR switch disables the merging of adjacent
|
|
exidx entries in frame unwind info.
|
|
.PP
|
|
The 68HC11 and 68HC12 linkers support specific options to control the
|
|
memory bank switching mapping and trampoline code generation.
|
|
.IP "\fB\-\-no\-trampoline\fR" 4
|
|
.IX Item "--no-trampoline"
|
|
This option disables the generation of trampoline. By default a trampoline
|
|
is generated for each far function which is called using a \f(CW\*(C`jsr\*(C'\fR
|
|
instruction (this happens when a pointer to a far function is taken).
|
|
.IP "\fB\-\-bank\-window\fR \fIname\fR" 4
|
|
.IX Item "--bank-window name"
|
|
This option indicates to the linker the name of the memory region in
|
|
the \fB\s-1MEMORY\s0\fR specification that describes the memory bank window.
|
|
The definition of such region is then used by the linker to compute
|
|
paging and addresses within the memory window.
|
|
.PP
|
|
The following options are supported to control handling of \s-1GOT\s0 generation
|
|
when linking for 68K targets.
|
|
.IP "\fB\-\-got=\fR\fItype\fR" 4
|
|
.IX Item "--got=type"
|
|
This option tells the linker which \s-1GOT\s0 generation scheme to use.
|
|
\&\fItype\fR should be one of \fBsingle\fR, \fBnegative\fR,
|
|
\&\fBmultigot\fR or \fBtarget\fR. For more information refer to the
|
|
Info entry for \fIld\fR.
|
|
.PP
|
|
The following options are supported to control microMIPS instruction
|
|
generation and branch relocation checks for \s-1ISA\s0 mode transitions when
|
|
linking for \s-1MIPS\s0 targets.
|
|
.IP "\fB\-\-insn32\fR" 4
|
|
.IX Item "--insn32"
|
|
.PD 0
|
|
.IP "\fB\-\-no\-insn32\fR" 4
|
|
.IX Item "--no-insn32"
|
|
.PD
|
|
These options control the choice of microMIPS instructions used in code
|
|
generated by the linker, such as that in the \s-1PLT\s0 or lazy binding stubs,
|
|
or in relaxation. If \fB\-\-insn32\fR is used, then the linker only uses
|
|
32\-bit instruction encodings. By default or if \fB\-\-no\-insn32\fR is
|
|
used, all instruction encodings are used, including 16\-bit ones where
|
|
possible.
|
|
.IP "\fB\-\-ignore\-branch\-isa\fR" 4
|
|
.IX Item "--ignore-branch-isa"
|
|
.PD 0
|
|
.IP "\fB\-\-no\-ignore\-branch\-isa\fR" 4
|
|
.IX Item "--no-ignore-branch-isa"
|
|
.PD
|
|
These options control branch relocation checks for invalid \s-1ISA\s0 mode
|
|
transitions. If \fB\-\-ignore\-branch\-isa\fR is used, then the linker
|
|
accepts any branch relocations and any \s-1ISA\s0 mode transition required
|
|
is lost in relocation calculation, except for some cases of \f(CW\*(C`BAL\*(C'\fR
|
|
instructions which meet relaxation conditions and are converted to
|
|
equivalent \f(CW\*(C`JALX\*(C'\fR instructions as the associated relocation is
|
|
calculated. By default or if \fB\-\-no\-ignore\-branch\-isa\fR is used
|
|
a check is made causing the loss of an \s-1ISA\s0 mode transition to produce
|
|
an error.
|
|
.SH "ENVIRONMENT"
|
|
.IX Header "ENVIRONMENT"
|
|
You can change the behaviour of \fBld\fR with the environment variables
|
|
\&\f(CW\*(C`GNUTARGET\*(C'\fR,
|
|
\&\f(CW\*(C`LDEMULATION\*(C'\fR and \f(CW\*(C`COLLECT_NO_DEMANGLE\*(C'\fR.
|
|
.PP
|
|
\&\f(CW\*(C`GNUTARGET\*(C'\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 \s-1BFD\s0 names for an input format. If there is no
|
|
\&\f(CW\*(C`GNUTARGET\*(C'\fR in the environment, \fBld\fR uses the natural format
|
|
of the target. If \f(CW\*(C`GNUTARGET\*(C'\fR is set to \f(CW\*(C`default\*(C'\fR then \s-1BFD\s0
|
|
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
|
|
\&\s-1BFD\s0 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(CW\*(C`LDEMULATION\*(C'\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(CW\*(C`LDEMULATION\*(C'\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(CW\*(C`COLLECT_NO_DEMANGLE\*(C'\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(CW\*(C`gcc\*(C'\fR linker wrapper program. The default
|
|
may be overridden by the \fB\-\-demangle\fR and \fB\-\-no\-demangle\fR
|
|
options.
|
|
.SH "SEE ALSO"
|
|
.IX Header "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"
|
|
.IX Header "COPYRIGHT"
|
|
Copyright (c) 1991\-2017 Free Software Foundation, Inc.
|
|
.PP
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
|
|
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"\s-1GNU\s0 Free Documentation License\*(R".
|