3903 lines
128 KiB
HTML
3903 lines
128 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of LD</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>LD</H1>
|
|
Section: GNU Development Tools (1)<BR>Updated: 2021-01-21<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
ld - The GNU linker
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
ld [<B>options</B>] <I>objfile</I> ...
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
<B>ld</B> 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 <B>ld</B>.
|
|
<P>
|
|
|
|
<B>ld</B> accepts Linker Command Language files written in
|
|
a superset of <FONT SIZE="-1">AT&T</FONT>'s Link Editor Command Language syntax,
|
|
to provide explicit and total control over the linking process.
|
|
<P>
|
|
|
|
This man page does not describe the command language; see the
|
|
<B>ld</B> entry in <TT>"info"</TT> for full details on the command
|
|
language and on other aspects of the <FONT SIZE="-1">GNU</FONT> linker.
|
|
<P>
|
|
|
|
This version of <B>ld</B> uses the general purpose <FONT SIZE="-1">BFD</FONT> libraries
|
|
to operate on object files. This allows <B>ld</B> to read, combine, and
|
|
write object files in many different formats---for example, <FONT SIZE="-1">COFF</FONT> or
|
|
<TT>"a.out"</TT>. Different formats may be linked together to produce any
|
|
available kind of object file.
|
|
<P>
|
|
|
|
Aside from its flexibility, the <FONT SIZE="-1">GNU</FONT> linker is more helpful than other
|
|
linkers in providing diagnostic information. Many linkers abandon
|
|
execution immediately upon encountering an error; whenever possible,
|
|
<B>ld</B> continues executing, allowing you to identify other errors
|
|
(or, in some cases, to get an output file in spite of the error).
|
|
<P>
|
|
|
|
The <FONT SIZE="-1">GNU</FONT> linker <B>ld</B> 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.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
|
|
|
|
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 <B>ld</B> is to link standard Unix
|
|
object files on a standard, supported Unix system. On such a system, to
|
|
link a file <TT>"hello.o"</TT>:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
ld -o <output> /lib/crt0.o hello.o -lc
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
This tells <B>ld</B> to produce a file called <I>output</I> as the
|
|
result of linking the file <TT>"/lib/crt0.o"</TT> with <TT>"hello.o"</TT> and
|
|
the library <TT>"libc.a"</TT>, which will come from the standard search
|
|
directories. (See the discussion of the <B>-l</B> option below.)
|
|
<P>
|
|
|
|
Some of the command-line options to <B>ld</B> may be specified at any
|
|
point in the command line. However, options which refer to files, such
|
|
as <B>-l</B> or <B>-T</B>, 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.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
Usually the linker is invoked with at least one object file, but you can
|
|
specify other forms of binary input files using <B>-l</B>, <B>-R</B>,
|
|
and the script command language. If <I>no</I> binary input files at all
|
|
are specified, the linker does not produce any output, and issues the
|
|
message <B>No input files</B>.
|
|
<P>
|
|
|
|
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 <B>-T</B>). 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
|
|
<TT>"INPUT"</TT> or <TT>"GROUP"</TT> 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 <B>-T</B> option
|
|
to replace the default linker script entirely, but note the effect of
|
|
the <TT>"INSERT"</TT> command.
|
|
<P>
|
|
|
|
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.
|
|
<P>
|
|
|
|
For options whose names are multiple letters, either one dash or two can
|
|
precede the option name; for example, <B>-trace-symbol</B> and
|
|
<B>--trace-symbol</B> 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
|
|
<B>-o</B> option. So for example <B>-omagic</B> sets the output file
|
|
name to <B>magic</B> whereas <B>--omagic</B> sets the <FONT SIZE="-1">NMAGIC</FONT> flag on the
|
|
output.
|
|
<P>
|
|
|
|
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,
|
|
<B>--trace-symbol foo</B> and <B>--trace-symbol=foo</B> are equivalent.
|
|
Unique abbreviations of the names of multiple-letter options are
|
|
accepted.
|
|
<P>
|
|
|
|
Note---if the linker is being invoked indirectly, via a compiler driver
|
|
(e.g. <B>gcc</B>) then all the linker command-line options should be
|
|
prefixed by <B>-Wl,</B> (or whatever is appropriate for the particular
|
|
compiler driver) like this:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
gcc -Wl,--start-group foo.o bar.o -Wl,--end-group
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
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:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
gcc foo.o bar.o -Wl,-eENTRY -Wl,-Map=a.map
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Here is a table of the generic command-line switches accepted by the <FONT SIZE="-1">GNU</FONT>
|
|
linker:
|
|
<DL COMPACT>
|
|
<DT id="1"><B>@</B><I>file</I><DD>
|
|
|
|
|
|
Read command-line options from <I>file</I>. The options read are
|
|
inserted in place of the original @<I>file</I> option. If <I>file</I>
|
|
does not exist, or cannot be read, then the option will be treated
|
|
literally, and not removed.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Options in <I>file</I> 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 <I>file</I> may itself contain additional
|
|
@<I>file</I> options; any such options will be processed recursively.
|
|
<DT id="2"><B>-a</B> <I>keyword</I><DD>
|
|
|
|
|
|
This option is supported for <FONT SIZE="-1">HP/UX</FONT> compatibility. The <I>keyword</I>
|
|
argument must be one of the strings <B>archive</B>, <B>shared</B>, or
|
|
<B>default</B>. <B>-aarchive</B> is functionally equivalent to
|
|
<B>-Bstatic</B>, and the other two keywords are functionally equivalent
|
|
to <B>-Bdynamic</B>. This option may be used any number of times.
|
|
<DT id="3"><B>--audit</B> <I></I><FONT SIZE="-1"><I>AUDITLIB</I></FONT><I></I><DD>
|
|
|
|
|
|
Adds <I></I><FONT SIZE="-1"><I>AUDITLIB</I></FONT><I></I> to the <TT>"DT_AUDIT"</TT> entry of the dynamic section.
|
|
<I></I><FONT SIZE="-1"><I>AUDITLIB</I></FONT><I></I> is not checked for existence, nor will it use the <FONT SIZE="-1">DT_SONAME</FONT>
|
|
specified in the library. If specified multiple times <TT>"DT_AUDIT"</TT>
|
|
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 <TT>"DT_DEPAUDIT"</TT> entry in the output file.
|
|
This option is only meaningful on <FONT SIZE="-1">ELF</FONT> platforms supporting the rtld-audit
|
|
interface.
|
|
<DT id="4"><B>-b</B> <I>input-format</I><DD>
|
|
|
|
|
|
|
|
<DT id="5"><B>--format=</B><I>input-format</I><DD>
|
|
|
|
|
|
|
|
<B>ld</B> may be configured to support more than one kind of object
|
|
file. If your <B>ld</B> is configured this way, you can use the
|
|
<B>-b</B> option to specify the binary format for input object files
|
|
that follow this option on the command line. Even when <B>ld</B> is
|
|
configured to support alternative object formats, you don't usually need
|
|
to specify this, as <B>ld</B> should be configured to expect as a
|
|
default input format the most usual format on each machine.
|
|
<I>input-format</I> is a text string, the name of a particular format
|
|
supported by the <FONT SIZE="-1">BFD</FONT> libraries. (You can list the available binary
|
|
formats with <B>objdump -i</B>.)
|
|
|
|
|
|
<P>
|
|
|
|
|
|
You may want to use this option if you are linking files with an unusual
|
|
binary format. You can also use <B>-b</B> to switch formats explicitly (when
|
|
linking object files of different formats), by including
|
|
<B>-b</B> <I>input-format</I> before each group of object files in a
|
|
particular format.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The default format is taken from the environment variable
|
|
<TT>"GNUTARGET"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
You can also define the input format from a script, using the command
|
|
<TT>"TARGET"</TT>;
|
|
<DT id="6"><B>-c</B> <I>MRI-commandfile</I><DD>
|
|
|
|
|
|
|
|
<DT id="7"><B>--mri-script=</B><I>MRI-commandfile</I><DD>
|
|
|
|
|
|
|
|
For compatibility with linkers produced by <FONT SIZE="-1">MRI,</FONT> <B>ld</B> accepts script
|
|
files written in an alternate, restricted command language, described in
|
|
the <FONT SIZE="-1">MRI</FONT> Compatible Script Files section of <FONT SIZE="-1">GNU</FONT> ld documentation.
|
|
Introduce <FONT SIZE="-1">MRI</FONT> script files with
|
|
the option <B>-c</B>; use the <B>-T</B> option to run linker
|
|
scripts written in the general-purpose <B>ld</B> scripting language.
|
|
If <I>MRI-cmdfile</I> does not exist, <B>ld</B> looks for it in the directories
|
|
specified by any <B>-L</B> options.
|
|
<DT id="8"><B>-d</B><DD>
|
|
|
|
|
|
|
|
<DT id="9"><B>-dc</B><DD>
|
|
|
|
|
|
<DT id="10"><B>-dp</B><DD>
|
|
|
|
|
|
|
|
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 <B>-r</B>). The
|
|
script command <TT>"FORCE_COMMON_ALLOCATION"</TT> has the same effect.
|
|
<DT id="11"><B>--depaudit</B> <I></I><FONT SIZE="-1"><I>AUDITLIB</I></FONT><I></I><DD>
|
|
|
|
|
|
|
|
<DT id="12"><B>-P</B> <I></I><FONT SIZE="-1"><I>AUDITLIB</I></FONT><I></I><DD>
|
|
|
|
|
|
|
|
Adds <I></I><FONT SIZE="-1"><I>AUDITLIB</I></FONT><I></I> to the <TT>"DT_DEPAUDIT"</TT> entry of the dynamic section.
|
|
<I></I><FONT SIZE="-1"><I>AUDITLIB</I></FONT><I></I> is not checked for existence, nor will it use the <FONT SIZE="-1">DT_SONAME</FONT>
|
|
specified in the library. If specified multiple times <TT>"DT_DEPAUDIT"</TT>
|
|
will contain a colon separated list of audit interfaces to use. This
|
|
option is only meaningful on <FONT SIZE="-1">ELF</FONT> platforms supporting the rtld-audit interface.
|
|
The -P option is provided for Solaris compatibility.
|
|
<DT id="13"><B>-e</B> <I>entry</I><DD>
|
|
|
|
|
|
|
|
<DT id="14"><B>--entry=</B><I>entry</I><DD>
|
|
|
|
|
|
|
|
Use <I>entry</I> as the explicit symbol for beginning execution of your
|
|
program, rather than the default entry point. If there is no symbol
|
|
named <I>entry</I>, the linker will try to parse <I>entry</I> as a number,
|
|
and use that as the entry address (the number will be interpreted in
|
|
base 10; you may use a leading <B>0x</B> for base 16, or a leading
|
|
<B>0</B> for base 8).
|
|
<DT id="15"><B>--exclude-libs</B> <I>lib</I><B>,</B><I>lib</I><B>,...</B><DD>
|
|
|
|
|
|
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
|
|
<TT>"--exclude-libs ALL"</TT> excludes symbols in all archive libraries from
|
|
automatic export. This option is available only for the i386 <FONT SIZE="-1">PE</FONT> targeted
|
|
port of the linker and for <FONT SIZE="-1">ELF</FONT> targeted ports. For i386 <FONT SIZE="-1">PE,</FONT> symbols
|
|
explicitly listed in a .def file are still exported, regardless of this
|
|
option. For <FONT SIZE="-1">ELF</FONT> targeted ports, symbols affected by this option will
|
|
be treated as hidden.
|
|
<DT id="16"><B>--exclude-modules-for-implib</B> <I>module</I><B>,</B><I>module</I><B>,...</B><DD>
|
|
|
|
|
|
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 <B>ld</B> 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 <FONT SIZE="-1">PE</FONT> targeted port
|
|
of the linker. Symbols explicitly listed in a .def file are still exported,
|
|
regardless of this option.
|
|
<DT id="17"><B>-E</B><DD>
|
|
|
|
|
|
|
|
<DT id="18"><B>--export-dynamic</B><DD>
|
|
|
|
|
|
<DT id="19"><B>--no-export-dynamic</B><DD>
|
|
|
|
|
|
|
|
When creating a dynamically linked executable, using the <B>-E</B>
|
|
option or the <B>--export-dynamic</B> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you do not use either of these options (or use the
|
|
<B>--no-export-dynamic</B> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you use <TT>"dlopen"</TT> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <B>--dynamic-list</B>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note that this option is specific to <FONT SIZE="-1">ELF</FONT> targeted ports. <FONT SIZE="-1">PE</FONT> targets
|
|
support a similar function to export all symbols from a <FONT SIZE="-1">DLL</FONT> or <FONT SIZE="-1">EXE</FONT>; see
|
|
the description of <B>--export-all-symbols</B> below.
|
|
<DT id="20"><B>-EB</B><DD>
|
|
|
|
|
|
Link big-endian objects. This affects the default output format.
|
|
<DT id="21"><B>-EL</B><DD>
|
|
|
|
|
|
Link little-endian objects. This affects the default output format.
|
|
<DT id="22"><B>-f</B> <I>name</I><DD>
|
|
|
|
|
|
|
|
<DT id="23"><B>--auxiliary=</B><I>name</I><DD>
|
|
|
|
|
|
|
|
When creating an <FONT SIZE="-1">ELF</FONT> shared object, set the internal <FONT SIZE="-1">DT_AUXILIARY</FONT> 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 <I>name</I>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you later link a program against this filter object, then, when you
|
|
run the program, the dynamic linker will see the <FONT SIZE="-1">DT_AUXILIARY</FONT> 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
|
|
<I>name</I>. If there is one, it will be used instead of the definition
|
|
in the filter object. The shared object <I>name</I> need not exist.
|
|
Thus the shared object <I>name</I> may be used to provide an alternative
|
|
implementation of certain functions, perhaps for debugging or for
|
|
machine-specific performance.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option may be specified more than once. The <FONT SIZE="-1">DT_AUXILIARY</FONT> entries
|
|
will be created in the order in which they appear on the command line.
|
|
<DT id="24"><B>-F</B> <I>name</I><DD>
|
|
|
|
|
|
|
|
<DT id="25"><B>--filter=</B><I>name</I><DD>
|
|
|
|
|
|
|
|
When creating an <FONT SIZE="-1">ELF</FONT> shared object, set the internal <FONT SIZE="-1">DT_FILTER</FONT> 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 <I>name</I>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you later link a program against this filter object, then, when you
|
|
run the program, the dynamic linker will see the <FONT SIZE="-1">DT_FILTER</FONT> 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 <I>name</I>. Thus the filter object can be
|
|
used to select a subset of the symbols provided by the object
|
|
<I>name</I>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Some older linkers used the <B>-F</B> option throughout a compilation
|
|
toolchain for specifying object-file format for both input and output
|
|
object files.
|
|
The <FONT SIZE="-1">GNU</FONT> linker uses other mechanisms for this purpose: the
|
|
<B>-b</B>, <B>--format</B>, <B>--oformat</B> options, the
|
|
<TT>"TARGET"</TT> command in linker scripts, and the <TT>"GNUTARGET"</TT>
|
|
environment variable.
|
|
The <FONT SIZE="-1">GNU</FONT> linker will ignore the <B>-F</B> option when not
|
|
creating an <FONT SIZE="-1">ELF</FONT> shared object.
|
|
<DT id="26"><B>-fini=</B><I>name</I><DD>
|
|
|
|
|
|
When creating an <FONT SIZE="-1">ELF</FONT> executable or shared object, call <FONT SIZE="-1">NAME</FONT> when the
|
|
executable or shared object is unloaded, by setting <FONT SIZE="-1">DT_FINI</FONT> to the
|
|
address of the function. By default, the linker uses <TT>"_fini"</TT> as
|
|
the function to call.
|
|
<DT id="27"><B>-g</B><DD>
|
|
|
|
|
|
Ignored. Provided for compatibility with other tools.
|
|
<DT id="28"><B>-G</B> <I>value</I><DD>
|
|
|
|
|
|
|
|
<DT id="29"><B>--gpsize=</B><I>value</I><DD>
|
|
|
|
|
|
|
|
Set the maximum size of objects to be optimized using the <FONT SIZE="-1">GP</FONT> register to
|
|
<I>size</I>. This is only meaningful for object file formats such as
|
|
<FONT SIZE="-1">MIPS ELF</FONT> that support putting large and small objects into different
|
|
sections. This is ignored for other object file formats.
|
|
<DT id="30"><B>-h</B> <I>name</I><DD>
|
|
|
|
|
|
|
|
<DT id="31"><B>-soname=</B><I>name</I><DD>
|
|
|
|
|
|
|
|
When creating an <FONT SIZE="-1">ELF</FONT> shared object, set the internal <FONT SIZE="-1">DT_SONAME</FONT> field to
|
|
the specified name. When an executable is linked with a shared object
|
|
which has a <FONT SIZE="-1">DT_SONAME</FONT> field, then when the executable is run the dynamic
|
|
linker will attempt to load the shared object specified by the <FONT SIZE="-1">DT_SONAME</FONT>
|
|
field rather than the using the file name given to the linker.
|
|
<DT id="32"><B>-i</B><DD>
|
|
|
|
|
|
Perform an incremental link (same as option <B>-r</B>).
|
|
<DT id="33"><B>-init=</B><I>name</I><DD>
|
|
|
|
|
|
When creating an <FONT SIZE="-1">ELF</FONT> executable or shared object, call <FONT SIZE="-1">NAME</FONT> when the
|
|
executable or shared object is loaded, by setting <FONT SIZE="-1">DT_INIT</FONT> to the address
|
|
of the function. By default, the linker uses <TT>"_init"</TT> as the
|
|
function to call.
|
|
<DT id="34"><B>-l</B> <I>namespec</I><DD>
|
|
|
|
|
|
|
|
<DT id="35"><B>--library=</B><I>namespec</I><DD>
|
|
|
|
|
|
|
|
Add the archive or object file specified by <I>namespec</I> to the
|
|
list of files to link. This option may be used any number of times.
|
|
If <I>namespec</I> is of the form <I>:filename</I>, <B>ld</B>
|
|
will search the library path for a file called <I>filename</I>, otherwise it
|
|
will search the library path for a file called <I>libnamespec.a</I>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
On systems which support shared libraries, <B>ld</B> may also search for
|
|
files other than <I>libnamespec.a</I>. Specifically, on <FONT SIZE="-1">ELF</FONT>
|
|
and SunOS systems, <B>ld</B> will search a directory for a library
|
|
called <I>libnamespec.so</I> before searching for one called
|
|
<I>libnamespec.a</I>. (By convention, a <TT>".so"</TT> extension
|
|
indicates a shared library.) Note that this behavior does not apply
|
|
to <I>:filename</I>, which always specifies a file called
|
|
<I>filename</I>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
See the <B>-(</B> option for a way to force the linker to search
|
|
archives multiple times.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
You may list the same archive multiple times on the command line.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This type of archive searching is standard for Unix linkers. However,
|
|
if you are using <B>ld</B> on <FONT SIZE="-1">AIX,</FONT> note that it is different from the
|
|
behaviour of the <FONT SIZE="-1">AIX</FONT> linker.
|
|
<DT id="36"><B>-L</B> <I>searchdir</I><DD>
|
|
|
|
|
|
|
|
<DT id="37"><B>--library-path=</B><I>searchdir</I><DD>
|
|
|
|
|
|
|
|
Add path <I>searchdir</I> to the list of paths that <B>ld</B> will search
|
|
for archive libraries and <B>ld</B> 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
|
|
<B>-L</B> options apply to all <B>-l</B> options, regardless of the
|
|
order in which the options appear. <B>-L</B> options do not affect
|
|
how <B>ld</B> searches for a linker script unless <B>-T</B>
|
|
option is specified.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If <I>searchdir</I> begins with <TT>"="</TT> or <TT>$SYSROOT</TT>, then this
|
|
prefix will be replaced by the <I>sysroot prefix</I>, controlled by the
|
|
<B>--sysroot</B> option, or specified when the linker is configured.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The default set of paths searched (without being specified with
|
|
<B>-L</B>) depends on which emulation mode <B>ld</B> is using, and in
|
|
some cases also on how it was configured.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The paths can also be specified in a link script with the
|
|
<TT>"SEARCH_DIR"</TT> command. Directories specified this way are searched
|
|
at the point in which the linker script appears in the command line.
|
|
<DT id="38"><B>-m</B> <I>emulation</I><DD>
|
|
|
|
|
|
Emulate the <I>emulation</I> linker. You can list the available
|
|
emulations with the <B>--verbose</B> or <B>-V</B> options.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If the <B>-m</B> option is not used, the emulation is taken from the
|
|
<TT>"LDEMULATION"</TT> environment variable, if that is defined.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Otherwise, the default emulation depends upon how the linker was
|
|
configured.
|
|
<DT id="39"><B>-M</B><DD>
|
|
|
|
|
|
|
|
<DT id="40"><B>--print-map</B><DD>
|
|
|
|
|
|
|
|
Print a link map to the standard output. A link map provides
|
|
information about the link, including the following:
|
|
<DL COMPACT><DT id="41"><DD>
|
|
<DL COMPACT>
|
|
<DT id="42">•<DD>
|
|
Where object files are mapped into memory.
|
|
<DT id="43">•<DD>
|
|
How common symbols are allocated.
|
|
<DT id="44">•<DD>
|
|
All archive members included in the link, with a mention of the symbol
|
|
which caused the archive member to be brought in.
|
|
<DT id="45">•<DD>
|
|
The values assigned to symbols.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
foo = 1
|
|
foo = foo * 4
|
|
foo = foo + 8
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
will produce the following output in the link map if the <B>-M</B>
|
|
option is used:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
0x00000001 foo = 0x1
|
|
[0x0000000c] foo = (foo * 0x4)
|
|
[0x0000000c] foo = (foo + 0x8)
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
See <B>Expressions</B> for more information about expressions in linker
|
|
scripts.
|
|
<DT id="46">•<DD>
|
|
How <FONT SIZE="-1">GNU</FONT> properties are merged.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
When the linker merges input .note.gnu.property sections into one output
|
|
.note.gnu.property section, some properties are removed or updated.
|
|
These actions are reported in the link map. For example:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
Removed property 0xc0000002 to merge foo.o (0x1) and bar.o (not found)
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This indicates that property 0xc0000002 is removed from output when
|
|
merging properties in <I>foo.o</I>, whose property 0xc0000002 value
|
|
is 0x1, and <I>bar.o</I>, which doesn't have property 0xc0000002.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
Updated property 0xc0010001 (0x1) to merge foo.o (0x1) and bar.o (0x1)
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This indicates that property 0xc0010001 value is updated to 0x1 in output
|
|
when merging properties in <I>foo.o</I>, whose 0xc0010001 property value
|
|
is 0x1, and <I>bar.o</I>, whose 0xc0010001 property value is 0x1.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="47"><DD>
|
|
</DL>
|
|
|
|
<DT id="48"><B>--print-map-discarded</B><DD>
|
|
|
|
|
|
|
|
<DT id="49"><B>--no-print-map-discarded</B><DD>
|
|
|
|
|
|
|
|
Print (or do not print) the list of discarded and garbage collected sections
|
|
in the link map. Enabled by default.
|
|
<DT id="50"><B>-n</B><DD>
|
|
|
|
|
|
|
|
<DT id="51"><B>--nmagic</B><DD>
|
|
|
|
|
|
|
|
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 <TT>"NMAGIC"</TT>.
|
|
<DT id="52"><B>-N</B><DD>
|
|
|
|
|
|
|
|
<DT id="53"><B>--omagic</B><DD>
|
|
|
|
|
|
|
|
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 <TT>"OMAGIC"</TT>. Note: Although a writable text section
|
|
is allowed for PE-COFF targets, it does not conform to the format
|
|
specification published by Microsoft.
|
|
<DT id="54"><B>--no-omagic</B><DD>
|
|
|
|
|
|
This option negates most of the effects of the <B>-N</B> 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 <B>-Bdynamic</B> for this.
|
|
<DT id="55"><B>-o</B> <I>output</I><DD>
|
|
|
|
|
|
|
|
<DT id="56"><B>--output=</B><I>output</I><DD>
|
|
|
|
|
|
|
|
Use <I>output</I> as the name for the program produced by <B>ld</B>; if this
|
|
option is not specified, the name <I>a.out</I> is used by default. The
|
|
script command <TT>"OUTPUT"</TT> can also specify the output file name.
|
|
<DT id="57"><B>-O</B> <I>level</I><DD>
|
|
|
|
|
|
If <I>level</I> is a numeric values greater than zero <B>ld</B> 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 <FONT SIZE="-1">ELF</FONT> 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.
|
|
<DT id="58"><B>-plugin</B> <I>name</I><DD>
|
|
|
|
|
|
Involve a plugin in the linking process. The <I>name</I> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note that the location of the compiler originated plugins is different
|
|
from the place where the <B>ar</B>, <B>nm</B> and
|
|
<B>ranlib</B> 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 <I>${libdir}/bfd-plugins</I> directory. All gcc
|
|
based linker plugins are backward compatible, so it is sufficient to
|
|
just copy in the newest one.
|
|
<DT id="59"><B>--push-state</B><DD>
|
|
|
|
|
|
The <B>--push-state</B> 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 <B>--pop-state</B> option.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The option which are covered are: <B>-Bdynamic</B>, <B>-Bstatic</B>,
|
|
<B>-dn</B>, <B>-dy</B>, <B>-call_shared</B>, <B>-non_shared</B>,
|
|
<B>-static</B>, <B>-N</B>, <B>-n</B>, <B>--whole-archive</B>,
|
|
<B>--no-whole-archive</B>, <B>-r</B>, <B>-Ur</B>,
|
|
<B>--copy-dt-needed-entries</B>, <B>--no-copy-dt-needed-entries</B>,
|
|
<B>--as-needed</B>, <B>--no-as-needed</B>, and <B>-a</B>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
One target for this option are specifications for <I>pkg-config</I>. When
|
|
used with the <B>--libs</B> option all possibly needed libraries are
|
|
listed and then possibly linked with all the time. It is better to return
|
|
something as follows:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
-Wl,--push-state,--as-needed -libone -libtwo -Wl,--pop-state
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="60"><B>--pop-state</B><DD>
|
|
|
|
|
|
Undoes the effect of --push-state, restores the previous values of the
|
|
flags governing input file handling.
|
|
<DT id="61"><B>-q</B><DD>
|
|
|
|
|
|
|
|
<DT id="62"><B>--emit-relocs</B><DD>
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option is currently only supported on <FONT SIZE="-1">ELF</FONT> platforms.
|
|
<DT id="63"><B>--force-dynamic</B><DD>
|
|
|
|
|
|
Force the output file to have dynamic sections. This option is specific
|
|
to VxWorks targets.
|
|
<DT id="64"><B>-r</B><DD>
|
|
|
|
|
|
|
|
<DT id="65"><B>--relocatable</B><DD>
|
|
|
|
|
|
|
|
Generate relocatable output---i.e., generate an output file that can in
|
|
turn serve as input to <B>ld</B>. This is often called <I>partial
|
|
linking</I>. As a side effect, in environments that support standard Unix
|
|
magic numbers, this option also sets the output file's magic number to
|
|
<TT>"OMAGIC"</TT>.
|
|
If this option is not specified, an absolute file is produced. When
|
|
linking C<FONT SIZE="-2">++</FONT> programs, this option <I>will not</I> resolve references to
|
|
constructors; to do that, use <B>-Ur</B>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <TT>"a.out"</TT>-based formats do not support partial linking
|
|
with input files in other formats at all.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option does the same thing as <B>-i</B>.
|
|
<DT id="66"><B>-R</B> <I>filename</I><DD>
|
|
|
|
|
|
|
|
<DT id="67"><B>--just-symbols=</B><I>filename</I><DD>
|
|
|
|
|
|
|
|
Read symbol names and their addresses from <I>filename</I>, 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For compatibility with other <FONT SIZE="-1">ELF</FONT> linkers, if the <B>-R</B> option is
|
|
followed by a directory name, rather than a file name, it is treated as
|
|
the <B>-rpath</B> option.
|
|
<DT id="68"><B>-s</B><DD>
|
|
|
|
|
|
|
|
<DT id="69"><B>--strip-all</B><DD>
|
|
|
|
|
|
|
|
Omit all symbol information from the output file.
|
|
<DT id="70"><B>-S</B><DD>
|
|
|
|
|
|
|
|
<DT id="71"><B>--strip-debug</B><DD>
|
|
|
|
|
|
|
|
Omit debugger symbol information (but not all symbols) from the output file.
|
|
<DT id="72"><B>--strip-discarded</B><DD>
|
|
|
|
|
|
|
|
<DT id="73"><B>--no-strip-discarded</B><DD>
|
|
|
|
|
|
|
|
Omit (or do not omit) global symbols defined in discarded sections.
|
|
Enabled by default.
|
|
<DT id="74"><B>-t</B><DD>
|
|
|
|
|
|
|
|
<DT id="75"><B>--trace</B><DD>
|
|
|
|
|
|
|
|
Print the names of the input files as <B>ld</B> processes them. If
|
|
<B>-t</B> is given twice then members within archives are also printed.
|
|
<B>-t</B> output is useful to generate a list of all the object files
|
|
and scripts involved in linking, for example, when packaging files for
|
|
a linker bug report.
|
|
<DT id="76"><B>-T</B> <I>scriptfile</I><DD>
|
|
|
|
|
|
|
|
<DT id="77"><B>--script=</B><I>scriptfile</I><DD>
|
|
|
|
|
|
|
|
Use <I>scriptfile</I> as the linker script. This script replaces
|
|
<B>ld</B>'s default linker script (rather than adding to it), so
|
|
<I>commandfile</I> must specify everything necessary to describe the
|
|
output file. If <I>scriptfile</I> does not exist in
|
|
the current directory, <TT>"ld"</TT> looks for it in the directories
|
|
specified by any preceding <B>-L</B> options. Multiple <B>-T</B>
|
|
options accumulate.
|
|
<DT id="78"><B>-dT</B> <I>scriptfile</I><DD>
|
|
|
|
|
|
|
|
<DT id="79"><B>--default-script=</B><I>scriptfile</I><DD>
|
|
|
|
|
|
|
|
Use <I>scriptfile</I> as the default linker script.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option is similar to the <B>--script</B> 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
|
|
<B>--default-script</B> 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
|
|
<B>gcc</B>).
|
|
<DT id="80"><B>-u</B> <I>symbol</I><DD>
|
|
|
|
|
|
|
|
<DT id="81"><B>--undefined=</B><I>symbol</I><DD>
|
|
|
|
|
|
|
|
Force <I>symbol</I> to be entered in the output file as an undefined
|
|
symbol. Doing this may, for example, trigger linking of additional
|
|
modules from standard libraries. <B>-u</B> may be repeated with
|
|
different option arguments to enter additional undefined symbols. This
|
|
option is equivalent to the <TT>"EXTERN"</TT> linker script command.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <B>--require-defined</B> should be used
|
|
instead.
|
|
<DT id="82"><B>--require-defined=</B><I>symbol</I><DD>
|
|
|
|
|
|
Require that <I>symbol</I> is defined in the output file. This option
|
|
is the same as option <B>--undefined</B> except that if <I>symbol</I>
|
|
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
|
|
<TT>"EXTERN"</TT>, <TT>"ASSERT"</TT> and <TT>"DEFINED"</TT> together. This option
|
|
can be used multiple times to require additional symbols.
|
|
<DT id="83"><B>-Ur</B><DD>
|
|
|
|
|
|
For anything other than C<FONT SIZE="-2">++</FONT> programs, this option is equivalent to
|
|
<B>-r</B>: it generates relocatable output---i.e., an output file that can in
|
|
turn serve as input to <B>ld</B>. When linking C<FONT SIZE="-2">++</FONT> programs, <B>-Ur</B>
|
|
<I>does</I> resolve references to constructors, unlike <B>-r</B>.
|
|
It does not work to use <B>-Ur</B> on files that were themselves linked
|
|
with <B>-Ur</B>; once the constructor table has been built, it cannot
|
|
be added to. Use <B>-Ur</B> only for the last partial link, and
|
|
<B>-r</B> for the others.
|
|
<DT id="84"><B>--orphan-handling=</B><I></I><FONT SIZE="-1"><I>MODE</I></FONT><I></I><DD>
|
|
|
|
|
|
Control how orphan sections are handled. An orphan section is one not
|
|
specifically mentioned in a linker script.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
<I></I><FONT SIZE="-1"><I>MODE</I></FONT><I></I> can have any of the following values:
|
|
<DL COMPACT><DT id="85"><DD>
|
|
<DL COMPACT>
|
|
<DT id="86">"place"<DD>
|
|
|
|
|
|
|
|
|
|
Orphan sections are placed into a suitable output section following
|
|
the strategy described in <B>Orphan Sections</B>. The option
|
|
<B>--unique</B> also affects how sections are placed.
|
|
<DT id="87">"discard"<DD>
|
|
|
|
|
|
|
|
|
|
All orphan sections are discarded, by placing them in the
|
|
<B>/DISCARD/</B> section.
|
|
<DT id="88">"warn"<DD>
|
|
|
|
|
|
|
|
|
|
The linker will place the orphan section as for <TT>"place"</TT> and also
|
|
issue a warning.
|
|
<DT id="89">"error"<DD>
|
|
|
|
|
|
|
|
|
|
The linker will exit with an error if any orphan section is found.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="90"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The default if <B>--orphan-handling</B> is not given is <TT>"place"</TT>.
|
|
</DL>
|
|
|
|
<DT id="91"><B>--unique[=</B><I></I><FONT SIZE="-1"><I>SECTION</I></FONT><I></I><B>]</B><DD>
|
|
|
|
|
|
Creates a separate output section for every input section matching
|
|
<I></I><FONT SIZE="-1"><I>SECTION</I></FONT><I></I>, or if the optional wildcard <I></I><FONT SIZE="-1"><I>SECTION</I></FONT><I></I> 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.
|
|
<DT id="92"><B>-v</B><DD>
|
|
|
|
|
|
|
|
<DT id="93"><B>--version</B><DD>
|
|
|
|
|
|
<DT id="94"><B>-V</B><DD>
|
|
|
|
|
|
|
|
Display the version number for <B>ld</B>. The <B>-V</B> option also
|
|
lists the supported emulations.
|
|
<DT id="95"><B>-x</B><DD>
|
|
|
|
|
|
|
|
<DT id="96"><B>--discard-all</B><DD>
|
|
|
|
|
|
|
|
Delete all local symbols.
|
|
<DT id="97"><B>-X</B><DD>
|
|
|
|
|
|
|
|
<DT id="98"><B>--discard-locals</B><DD>
|
|
|
|
|
|
|
|
Delete all temporary local symbols. (These symbols start with
|
|
system-specific local label prefixes, typically <B>.L</B> for <FONT SIZE="-1">ELF</FONT> systems
|
|
or <B>L</B> for traditional a.out systems.)
|
|
<DT id="99"><B>-y</B> <I>symbol</I><DD>
|
|
|
|
|
|
|
|
<DT id="100"><B>--trace-symbol=</B><I>symbol</I><DD>
|
|
|
|
|
|
|
|
Print the name of each linked file in which <I>symbol</I> appears. This
|
|
option may be given any number of times. On many systems it is necessary
|
|
to prepend an underscore.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option is useful when you have an undefined symbol in your link but
|
|
don't know where the reference is coming from.
|
|
<DT id="101"><B>-Y</B> <I>path</I><DD>
|
|
|
|
|
|
Add <I>path</I> to the default library search path. This option exists
|
|
for Solaris compatibility.
|
|
<DT id="102"><B>-z</B> <I>keyword</I><DD>
|
|
|
|
|
|
The recognized keywords are:
|
|
<DL COMPACT><DT id="103"><DD>
|
|
<DL COMPACT>
|
|
<DT id="104"><B>bndplt</B><DD>
|
|
|
|
|
|
Always generate <FONT SIZE="-1">BND</FONT> prefix in <FONT SIZE="-1">PLT</FONT> entries. Supported for Linux/x86_64.
|
|
<DT id="105"><B>call-nop=prefix-addr</B><DD>
|
|
|
|
|
|
|
|
<DT id="106"><B>call-nop=suffix-nop</B><DD>
|
|
|
|
|
|
<DT id="107"><B>call-nop=prefix-</B><I>byte</I><DD>
|
|
|
|
|
|
<DT id="108"><B>call-nop=suffix-</B><I>byte</I><DD>
|
|
|
|
|
|
|
|
Specify the 1-byte <TT>"NOP"</TT> padding when transforming indirect call
|
|
to a locally defined function, foo, via its <FONT SIZE="-1">GOT</FONT> slot.
|
|
<B>call-nop=prefix-addr</B> generates <TT>"0x67 call foo"</TT>.
|
|
<B>call-nop=suffix-nop</B> generates <TT>"call foo 0x90"</TT>.
|
|
<B>call-nop=prefix-</B><I>byte</I> generates <TT>"</TT>byte<TT> call foo"</TT>.
|
|
<B>call-nop=suffix-</B><I>byte</I> generates <TT>"call foo </TT>byte<TT>"</TT>.
|
|
Supported for i386 and x86_64.
|
|
<DT id="109"><B>cet-report=none</B><DD>
|
|
|
|
|
|
|
|
<DT id="110"><B>cet-report=warning</B><DD>
|
|
|
|
|
|
<DT id="111"><B>cet-report=error</B><DD>
|
|
|
|
|
|
|
|
Specify how to report the missing <FONT SIZE="-1">GNU_PROPERTY_X86_FEATURE_1_IBT</FONT> and
|
|
<FONT SIZE="-1">GNU_PROPERTY_X86_FEATURE_1_SHSTK</FONT> properties in input .note.gnu.property
|
|
section. <B>cet-report=none</B>, which is the default, will make the
|
|
linker not report missing properties in input files.
|
|
<B>cet-report=warning</B> will make the linker issue a warning for
|
|
missing properties in input files. <B>cet-report=error</B> will make
|
|
the linker issue an error for missing properties in input files.
|
|
Note that <B>ibt</B> will turn off the missing
|
|
<FONT SIZE="-1">GNU_PROPERTY_X86_FEATURE_1_IBT</FONT> property report and <B>shstk</B> will
|
|
turn off the missing <FONT SIZE="-1">GNU_PROPERTY_X86_FEATURE_1_SHSTK</FONT> property report.
|
|
Supported for Linux/i386 and Linux/x86_64.
|
|
<DT id="112"><B>combreloc</B><DD>
|
|
|
|
|
|
|
|
<DT id="113"><B>nocombreloc</B><DD>
|
|
|
|
|
|
|
|
Combine multiple dynamic relocation sections and sort to improve
|
|
dynamic symbol lookup caching. Do not do this if <B>nocombreloc</B>.
|
|
<DT id="114"><B>common</B><DD>
|
|
|
|
|
|
|
|
<DT id="115"><B>nocommon</B><DD>
|
|
|
|
|
|
|
|
Generate common symbols with <FONT SIZE="-1">STT_COMMON</FONT> type during a relocatable
|
|
link. Use <FONT SIZE="-1">STT_OBJECT</FONT> type if <B>nocommon</B>.
|
|
<DT id="116"><B>common-page-size=</B><I>value</I><DD>
|
|
|
|
|
|
Set the page size most commonly used to <I>value</I>. Memory image
|
|
layout will be optimized to minimize memory pages if the system is
|
|
using pages of this size.
|
|
<DT id="117"><B>defs</B><DD>
|
|
|
|
|
|
Report unresolved symbol references from regular object files. This
|
|
is done even if the linker is creating a non-symbolic shared library.
|
|
This option is the inverse of <B>-z undefs</B>.
|
|
<DT id="118"><B>dynamic-undefined-weak</B><DD>
|
|
|
|
|
|
|
|
<DT id="119"><B>nodynamic-undefined-weak</B><DD>
|
|
|
|
|
|
|
|
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. Do not make them dynamic if
|
|
<B>nodynamic-undefined-weak</B>. If neither option is given, a target
|
|
may default to either option being in force, or make some other
|
|
selection of undefined weak symbols dynamic. Not all targets support
|
|
these options.
|
|
<DT id="120"><B>execstack</B><DD>
|
|
|
|
|
|
Marks the object as requiring executable stack.
|
|
<DT id="121"><B>global</B><DD>
|
|
|
|
|
|
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.
|
|
<DT id="122"><B>globalaudit</B><DD>
|
|
|
|
|
|
This option is only meaningful when building a dynamic executable.
|
|
This option marks the executable as requiring global auditing by
|
|
setting the <TT>"DF_1_GLOBAUDIT"</TT> bit in the <TT>"DT_FLAGS_1"</TT> dynamic
|
|
tag. Global auditing requires that any auditing library defined via
|
|
the <B>--depaudit</B> or <B>-P</B> command-line options be run for
|
|
all dynamic objects loaded by the application.
|
|
<DT id="123"><B>ibtplt</B><DD>
|
|
|
|
|
|
Generate Intel Indirect Branch Tracking (<FONT SIZE="-1">IBT</FONT>) enabled <FONT SIZE="-1">PLT</FONT> entries.
|
|
Supported for Linux/i386 and Linux/x86_64.
|
|
<DT id="124"><B>ibt</B><DD>
|
|
|
|
|
|
Generate <FONT SIZE="-1">GNU_PROPERTY_X86_FEATURE_1_IBT</FONT> in .note.gnu.property section
|
|
to indicate compatibility with <FONT SIZE="-1">IBT.</FONT> This also implies <B>ibtplt</B>.
|
|
Supported for Linux/i386 and Linux/x86_64.
|
|
<DT id="125"><B>initfirst</B><DD>
|
|
|
|
|
|
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.
|
|
<DT id="126"><B>interpose</B><DD>
|
|
|
|
|
|
Specify that the dynamic loader should modify its symbol search order
|
|
so that symbols in this shared library interpose all other shared
|
|
libraries not so marked.
|
|
<DT id="127"><B>lazy</B><DD>
|
|
|
|
|
|
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.
|
|
<DT id="128"><B>loadfltr</B><DD>
|
|
|
|
|
|
Specify that the object's filters be processed immediately at runtime.
|
|
<DT id="129"><B>max-page-size=</B><I>value</I><DD>
|
|
|
|
|
|
Set the maximum memory page size supported to <I>value</I>.
|
|
<DT id="130"><B>muldefs</B><DD>
|
|
|
|
|
|
Allow multiple definitions.
|
|
<DT id="131"><B>nocopyreloc</B><DD>
|
|
|
|
|
|
Disable linker generated .dynbss variables used in place of variables
|
|
defined in shared libraries. May result in dynamic text relocations.
|
|
<DT id="132"><B>nodefaultlib</B><DD>
|
|
|
|
|
|
Specify that the dynamic loader search for dependencies of this object
|
|
should ignore any default library search paths.
|
|
<DT id="133"><B>nodelete</B><DD>
|
|
|
|
|
|
Specify that the object shouldn't be unloaded at runtime.
|
|
<DT id="134"><B>nodlopen</B><DD>
|
|
|
|
|
|
Specify that the object is not available to <TT>"dlopen"</TT>.
|
|
<DT id="135"><B>nodump</B><DD>
|
|
|
|
|
|
Specify that the object can not be dumped by <TT>"dldump"</TT>.
|
|
<DT id="136"><B>noexecstack</B><DD>
|
|
|
|
|
|
Marks the object as not requiring executable stack.
|
|
<DT id="137"><B>noextern-protected-data</B><DD>
|
|
|
|
|
|
Don't treat protected data symbols as external when building a shared
|
|
library. This option overrides the linker backend default. It can be
|
|
used to work around 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.
|
|
<DT id="138"><B>noreloc-overflow</B><DD>
|
|
|
|
|
|
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.
|
|
<DT id="139"><B>now</B><DD>
|
|
|
|
|
|
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 loaded by dlopen, instead of deferring
|
|
function call resolution to the point when the function is first
|
|
called.
|
|
<DT id="140"><B>origin</B><DD>
|
|
|
|
|
|
Specify that the object requires <B></B>$ORIGIN<B></B> handling in paths.
|
|
<DT id="141"><B>relro</B><DD>
|
|
|
|
|
|
|
|
<DT id="142"><B>norelro</B><DD>
|
|
|
|
|
|
|
|
Create an <FONT SIZE="-1">ELF</FONT> <TT>"PT_GNU_RELRO"</TT> segment header in the object. This
|
|
specifies a memory segment that should be made read-only after
|
|
relocation, if supported. Specifying <B>common-page-size</B> smaller
|
|
than the system page size will render this protection ineffective.
|
|
Don't create an <FONT SIZE="-1">ELF</FONT> <TT>"PT_GNU_RELRO"</TT> segment if <B>norelro</B>.
|
|
<DT id="143"><B>separate-code</B><DD>
|
|
|
|
|
|
|
|
<DT id="144"><B>noseparate-code</B><DD>
|
|
|
|
|
|
|
|
Create separate code <TT>"PT_LOAD"</TT> segment header in the object. This
|
|
specifies a memory segment that should contain only instructions and must
|
|
be in wholly disjoint pages from any other data. Don't create separate
|
|
code <TT>"PT_LOAD"</TT> segment if <B>noseparate-code</B> is used.
|
|
<DT id="145"><B>shstk</B><DD>
|
|
|
|
|
|
Generate <FONT SIZE="-1">GNU_PROPERTY_X86_FEATURE_1_SHSTK</FONT> in .note.gnu.property section
|
|
to indicate compatibility with Intel Shadow Stack. Supported for
|
|
Linux/i386 and Linux/x86_64.
|
|
<DT id="146"><B>stack-size=</B><I>value</I><DD>
|
|
|
|
|
|
Specify a stack size for an <FONT SIZE="-1">ELF</FONT> <TT>"PT_GNU_STACK"</TT> segment.
|
|
Specifying zero will override any default non-zero sized
|
|
<TT>"PT_GNU_STACK"</TT> segment creation.
|
|
<DT id="147"><B>text</B><DD>
|
|
|
|
|
|
|
|
<DT id="148"><B>notext</B><DD>
|
|
|
|
|
|
<DT id="149"><B>textoff</B><DD>
|
|
|
|
|
|
|
|
Report an error if <FONT SIZE="-1">DT_TEXTREL</FONT> is set, i.e., if the binary has dynamic
|
|
relocations in read-only sections. Don't report an error if
|
|
<B>notext</B> or <B>textoff</B>.
|
|
<DT id="150"><B>undefs</B><DD>
|
|
|
|
|
|
Do not report unresolved symbol references from regular object files,
|
|
either when creating an executable, or when creating a shared library.
|
|
This option is the inverse of <B>-z defs</B>.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="151"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Other keywords are ignored for Solaris compatibility.
|
|
</DL>
|
|
|
|
<DT id="152"><B>-(</B> <I>archives</I> <B>-)</B><DD>
|
|
|
|
|
|
|
|
<DT id="153"><B>--start-group</B> <I>archives</I> <B>--end-group</B><DD>
|
|
|
|
|
|
|
|
The <I>archives</I> should be a list of archive files. They may be
|
|
either explicit file names, or <B>-l</B> options.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 will all be searched repeatedly until all possible references are
|
|
resolved.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
<DT id="154"><B>--accept-unknown-input-arch</B><DD>
|
|
|
|
|
|
|
|
<DT id="155"><B>--no-accept-unknown-input-arch</B><DD>
|
|
|
|
|
|
|
|
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 <B>--accept-unknown-input-arch</B> option has been added to
|
|
restore the old behaviour.
|
|
<DT id="156"><B>--as-needed</B><DD>
|
|
|
|
|
|
|
|
<DT id="157"><B>--no-as-needed</B><DD>
|
|
|
|
|
|
|
|
This option affects <FONT SIZE="-1">ELF DT_NEEDED</FONT> tags for dynamic libraries mentioned
|
|
on the command line after the <B>--as-needed</B> option. Normally
|
|
the linker will add a <FONT SIZE="-1">DT_NEEDED</FONT> tag for each dynamic library mentioned
|
|
on the command line, regardless of whether the library is actually
|
|
needed or not. <B>--as-needed</B> causes a <FONT SIZE="-1">DT_NEEDED</FONT> tag to only be
|
|
emitted for a library that <I>at that point in the link</I> satisfies a
|
|
non-weak undefined symbol reference from a regular object file or, if
|
|
the library is not found in the <FONT SIZE="-1">DT_NEEDED</FONT> 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 <I>after</I>
|
|
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. <B>--no-as-needed</B> restores the default behaviour.
|
|
<DT id="158"><B>--add-needed</B><DD>
|
|
|
|
|
|
|
|
<DT id="159"><B>--no-add-needed</B><DD>
|
|
|
|
|
|
|
|
These two options have been deprecated because of the similarity of
|
|
their names to the <B>--as-needed</B> and <B>--no-as-needed</B>
|
|
options. They have been replaced by <B>--copy-dt-needed-entries</B>
|
|
and <B>--no-copy-dt-needed-entries</B>.
|
|
<DT id="160"><B>-assert</B> <I>keyword</I><DD>
|
|
|
|
|
|
This option is ignored for SunOS compatibility.
|
|
<DT id="161"><B>-Bdynamic</B><DD>
|
|
|
|
|
|
|
|
<DT id="162"><B>-dy</B><DD>
|
|
|
|
|
|
<DT id="163"><B>-call_shared</B><DD>
|
|
|
|
|
|
|
|
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
|
|
<B>-l</B> options which follow it.
|
|
<DT id="164"><B>-Bgroup</B><DD>
|
|
|
|
|
|
Set the <TT>"DF_1_GROUP"</TT> flag in the <TT>"DT_FLAGS_1"</TT> 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.
|
|
<B>--unresolved-symbols=report-all</B> is implied. This option is
|
|
only meaningful on <FONT SIZE="-1">ELF</FONT> platforms which support shared libraries.
|
|
<DT id="165"><B>-Bstatic</B><DD>
|
|
|
|
|
|
|
|
<DT id="166"><B>-dn</B><DD>
|
|
|
|
|
|
<DT id="167"><B>-non_shared</B><DD>
|
|
|
|
|
|
<DT id="168"><B>-static</B><DD>
|
|
|
|
|
|
|
|
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 <B>-l</B> options which follow it. This
|
|
option also implies <B>--unresolved-symbols=report-all</B>. This
|
|
option can be used with <B>-shared</B>. 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.
|
|
<DT id="169"><B>-Bsymbolic</B><DD>
|
|
|
|
|
|
When creating a shared library, bind references to global symbols to the
|
|
definition within the shared library, if any. Normally, it is possible
|
|
for a program linked against a shared library to override the definition
|
|
within the shared library. This option is only meaningful on <FONT SIZE="-1">ELF</FONT>
|
|
platforms which support shared libraries.
|
|
<DT id="170"><B>-Bsymbolic-functions</B><DD>
|
|
|
|
|
|
When creating a shared library, bind references to global function
|
|
symbols to the definition within the shared library, if any.
|
|
This option is only meaningful on <FONT SIZE="-1">ELF</FONT> platforms which support shared
|
|
libraries.
|
|
<DT id="171"><B>--dynamic-list=</B><I>dynamic-list-file</I><DD>
|
|
|
|
|
|
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 <FONT SIZE="-1">ELF</FONT> platforms
|
|
which support shared libraries.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The format of the dynamic list is the same as the version node without
|
|
scope and node name. See <B></B><FONT SIZE="-1"><B>VERSION</B></FONT><B></B> for more information.
|
|
<DT id="172"><B>--dynamic-list-data</B><DD>
|
|
|
|
|
|
Include all global data symbols to the dynamic list.
|
|
<DT id="173"><B>--dynamic-list-cpp-new</B><DD>
|
|
|
|
|
|
Provide the builtin dynamic list for C<FONT SIZE="-2">++</FONT> operator new and delete. It
|
|
is mainly useful for building shared libstdc++.
|
|
<DT id="174"><B>--dynamic-list-cpp-typeinfo</B><DD>
|
|
|
|
|
|
Provide the builtin dynamic list for C<FONT SIZE="-2">++</FONT> runtime type identification.
|
|
<DT id="175"><B>--check-sections</B><DD>
|
|
|
|
|
|
|
|
<DT id="176"><B>--no-check-sections</B><DD>
|
|
|
|
|
|
|
|
Asks the linker <I>not</I> 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 <B>--check-sections</B>.
|
|
Section overlap is not usually checked for relocatable links. You can
|
|
force checking in that case by using the <B>--check-sections</B>
|
|
option.
|
|
<DT id="177"><B>--copy-dt-needed-entries</B><DD>
|
|
|
|
|
|
|
|
<DT id="178"><B>--no-copy-dt-needed-entries</B><DD>
|
|
|
|
|
|
|
|
This option affects the treatment of dynamic libraries referred to
|
|
by <FONT SIZE="-1">DT_NEEDED</FONT> tags <I>inside</I> <FONT SIZE="-1">ELF</FONT> dynamic libraries mentioned on the
|
|
command line. Normally the linker won't add a <FONT SIZE="-1">DT_NEEDED</FONT> tag to the
|
|
output binary for each library mentioned in a <FONT SIZE="-1">DT_NEEDED</FONT> tag in an
|
|
input dynamic library. With <B>--copy-dt-needed-entries</B>
|
|
specified on the command line however any dynamic libraries that
|
|
follow it will have their <FONT SIZE="-1">DT_NEEDED</FONT> entries added. The default
|
|
behaviour can be restored with <B>--no-copy-dt-needed-entries</B>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option also has an effect on the resolution of symbols in dynamic
|
|
libraries. With <B>--copy-dt-needed-entries</B> dynamic libraries
|
|
mentioned on the command line will be recursively searched, following
|
|
their <FONT SIZE="-1">DT_NEEDED</FONT> 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 <FONT SIZE="-1">DT_NEEDED</FONT> links will be traversed to resolve
|
|
symbols.
|
|
<DT id="179"><B>--cref</B><DD>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
<DT id="180"><B>--no-define-common</B><DD>
|
|
|
|
|
|
This option inhibits the assignment of addresses to common symbols.
|
|
The script command <TT>"INHIBIT_COMMON_ALLOCATION"</TT> has the same effect.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <B>--no-define-common</B> 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 <B>--no-define-common</B> 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.
|
|
<DT id="181"><B>--force-group-allocation</B><DD>
|
|
|
|
|
|
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 (<B>-r</B>). The script
|
|
command <TT>"FORCE_GROUP_ALLOCATION"</TT> has the same
|
|
effect.
|
|
<DT id="182"><B>--defsym=</B><I>symbol</I><B>=</B><I>expression</I><DD>
|
|
|
|
|
|
Create a global symbol in the output file, containing the absolute
|
|
address given by <I>expression</I>. 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 <I>expression</I> in this
|
|
context: you may give a hexadecimal constant or the name of an existing
|
|
symbol, or use <TT>"+"</TT> and <TT>"-"</TT> to add or subtract hexadecimal
|
|
constants or symbols. If you need more elaborate expressions, consider
|
|
using the linker command language from a script.
|
|
<I>Note:</I> there should be no white space between <I>symbol</I>, the
|
|
equals sign ("<B>=</B>"), and <I>expression</I>.
|
|
<DT id="183"><B>--demangle[=</B><I>style</I><B>]</B><DD>
|
|
|
|
|
|
|
|
<DT id="184"><B>--no-demangle</B><DD>
|
|
|
|
|
|
|
|
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<FONT SIZE="-2">++</FONT>
|
|
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 <B></B><FONT SIZE="-1"><B>COLLECT_NO_DEMANGLE</B></FONT><B></B>
|
|
is set. These options may be used to override the default.
|
|
<DT id="185"><B>-I</B><I>file</I><DD>
|
|
|
|
|
|
|
|
<DT id="186"><B>--dynamic-linker=</B><I>file</I><DD>
|
|
|
|
|
|
|
|
Set the name of the dynamic linker. This is only meaningful when
|
|
generating dynamically linked <FONT SIZE="-1">ELF</FONT> executables. The default dynamic
|
|
linker is normally correct; don't use this unless you know what you are
|
|
doing.
|
|
<DT id="187"><B>--no-dynamic-linker</B><DD>
|
|
|
|
|
|
When producing an executable file, omit the request for a dynamic
|
|
linker to be used at load-time. This is only meaningful for <FONT SIZE="-1">ELF</FONT>
|
|
executables that contain dynamic relocations, and usually requires
|
|
entry point code that is capable of processing these relocations.
|
|
<DT id="188"><B>--embedded-relocs</B><DD>
|
|
|
|
|
|
This option is similar to the <B>--emit-relocs</B> option except
|
|
that the relocs are stored in a target-specific section. This option
|
|
is only supported by the <B></B><FONT SIZE="-1"><B>BFIN</B></FONT><B></B>, <B></B><FONT SIZE="-1"><B>CR16</B></FONT><B></B> and <I>M68K</I>
|
|
targets.
|
|
<DT id="189"><B>--disable-multiple-abs-defs</B><DD>
|
|
|
|
|
|
Do not allow multiple definitions with symbols included
|
|
in filename invoked by -R or --just-symbols
|
|
<DT id="190"><B>--fatal-warnings</B><DD>
|
|
|
|
|
|
|
|
<DT id="191"><B>--no-fatal-warnings</B><DD>
|
|
|
|
|
|
|
|
Treat all warnings as errors. The default behaviour can be restored
|
|
with the option <B>--no-fatal-warnings</B>.
|
|
<DT id="192"><B>--force-exe-suffix</B><DD>
|
|
|
|
|
|
Make sure that an output file has a .exe suffix.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If a successfully built fully linked output file does not have a
|
|
<TT>".exe"</TT> or <TT>".dll"</TT> suffix, this option forces the linker to copy
|
|
the output file to one of the same name with a <TT>".exe"</TT> 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 <TT>".exe"</TT> suffix.
|
|
<DT id="193"><B>--gc-sections</B><DD>
|
|
|
|
|
|
|
|
<DT id="194"><B>--no-gc-sections</B><DD>
|
|
|
|
|
|
|
|
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
|
|
<B>--no-gc-sections</B> on the command line. Note that garbage
|
|
collection for <FONT SIZE="-1">COFF</FONT> and <FONT SIZE="-1">PE</FONT> format targets is supported, but the
|
|
implementation is currently considered to be experimental.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
<B>--gc-sections</B> 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 <B>--entry</B>, <B>--undefined</B>, and
|
|
<B>--gc-keep-exported</B>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This option can be set when doing a partial link (enabled with option
|
|
<B>-r</B>). In this case the root of symbols kept must be explicitly
|
|
specified either by one of the options <B>--entry</B>,
|
|
<B>--undefined</B>, or <B>--gc-keep-exported</B> or by a <TT>"ENTRY"</TT>
|
|
command in the linker script.
|
|
<DT id="195"><B>--print-gc-sections</B><DD>
|
|
|
|
|
|
|
|
<DT id="196"><B>--no-print-gc-sections</B><DD>
|
|
|
|
|
|
|
|
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 <B>--gc-sections</B>) option. The
|
|
default behaviour (of not listing the sections that are removed) can
|
|
be restored by specifying <B>--no-print-gc-sections</B> on the command
|
|
line.
|
|
<DT id="197"><B>--gc-keep-exported</B><DD>
|
|
|
|
|
|
When <B>--gc-sections</B> 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
|
|
<FONT SIZE="-1">ELF</FONT> format targets.
|
|
<DT id="198"><B>--print-output-format</B><DD>
|
|
|
|
|
|
Print the name of the default output format (perhaps influenced by
|
|
other command-line options). This is the string that would appear
|
|
in an <TT>"OUTPUT_FORMAT"</TT> linker script command.
|
|
<DT id="199"><B>--print-memory-usage</B><DD>
|
|
|
|
|
|
Print used size, total size and used size of memory regions created with
|
|
the <B></B><FONT SIZE="-1"><B>MEMORY</B></FONT><B></B> 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:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
Memory region Used Size Region Size %age Used
|
|
ROM: 256 KB 1 MB 25.00%
|
|
RAM: 32 B 2 GB 0.00%
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="200"><B>--help</B><DD>
|
|
|
|
|
|
Print a summary of the command-line options on the standard output and exit.
|
|
<DT id="201"><B>--target-help</B><DD>
|
|
|
|
|
|
Print a summary of all target-specific options on the standard output and exit.
|
|
<DT id="202"><B>-Map=</B><I>mapfile</I><DD>
|
|
|
|
|
|
Print a link map to the file <I>mapfile</I>. See the description of the
|
|
<B>-M</B> option, above.
|
|
<DT id="203"><B>--no-keep-memory</B><DD>
|
|
|
|
|
|
<B>ld</B> normally optimizes for speed over memory usage by caching the
|
|
symbol tables of input files in memory. This option tells <B>ld</B> to
|
|
instead optimize for memory usage, by rereading the symbol tables as
|
|
necessary. This may be required if <B>ld</B> runs out of memory space
|
|
while linking a large executable.
|
|
<DT id="204"><B>--no-undefined</B><DD>
|
|
|
|
|
|
|
|
<DT id="205"><B>-z defs</B><DD>
|
|
|
|
|
|
|
|
Report unresolved symbol references from regular object files. This
|
|
is done even if the linker is creating a non-symbolic shared library.
|
|
The switch <B>--[no-]allow-shlib-undefined</B> controls the
|
|
behaviour for reporting unresolved references found in shared
|
|
libraries being linked in.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The effects of this option can be reverted by using <TT>"-z undefs"</TT>.
|
|
<DT id="206"><B>--allow-multiple-definition</B><DD>
|
|
|
|
|
|
|
|
<DT id="207"><B>-z muldefs</B><DD>
|
|
|
|
|
|
|
|
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.
|
|
<DT id="208"><B>--allow-shlib-undefined</B><DD>
|
|
|
|
|
|
|
|
<DT id="209"><B>--no-allow-shlib-undefined</B><DD>
|
|
|
|
|
|
|
|
Allows or disallows undefined symbols in shared libraries.
|
|
This switch is similar to <B>--no-undefined</B> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The reasons for allowing undefined symbol references in shared
|
|
libraries specified at link time are that:
|
|
<DL COMPACT><DT id="210"><DD>
|
|
<DL COMPACT>
|
|
<DT id="211">•<DD>
|
|
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.
|
|
<DT id="212">•<DD>
|
|
There are some operating systems, eg BeOS and <FONT SIZE="-1">HPPA,</FONT> where undefined
|
|
symbols in shared libraries are normal.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="213"><DD>
|
|
</DL>
|
|
|
|
<DT id="214"><B>--no-undefined-version</B><DD>
|
|
|
|
|
|
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.
|
|
<DT id="215"><B>--default-symver</B><DD>
|
|
|
|
|
|
Create and use a default symbol version (the soname) for unversioned
|
|
exported symbols.
|
|
<DT id="216"><B>--default-imported-symver</B><DD>
|
|
|
|
|
|
Create and use a default symbol version (the soname) for unversioned
|
|
imported symbols.
|
|
<DT id="217"><B>--no-warn-mismatch</B><DD>
|
|
|
|
|
|
Normally <B>ld</B> 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 <B>ld</B> 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.
|
|
<DT id="218"><B>--no-warn-search-mismatch</B><DD>
|
|
|
|
|
|
Normally <B>ld</B> will give a warning if it finds an incompatible
|
|
library during a library search. This option silences the warning.
|
|
<DT id="219"><B>--no-whole-archive</B><DD>
|
|
|
|
|
|
Turn off the effect of the <B>--whole-archive</B> option for subsequent
|
|
archive files.
|
|
<DT id="220"><B>--noinhibit-exec</B><DD>
|
|
|
|
|
|
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.
|
|
<DT id="221"><B>-nostdlib</B><DD>
|
|
|
|
|
|
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.
|
|
<DT id="222"><B>--oformat=</B><I>output-format</I><DD>
|
|
|
|
|
|
<B>ld</B> may be configured to support more than one kind of object
|
|
file. If your <B>ld</B> is configured this way, you can use the
|
|
<B>--oformat</B> option to specify the binary format for the output
|
|
object file. Even when <B>ld</B> is configured to support alternative
|
|
object formats, you don't usually need to specify this, as <B>ld</B>
|
|
should be configured to produce as a default output format the most
|
|
usual format on each machine. <I>output-format</I> is a text string, the
|
|
name of a particular format supported by the <FONT SIZE="-1">BFD</FONT> libraries. (You can
|
|
list the available binary formats with <B>objdump -i</B>.) The script
|
|
command <TT>"OUTPUT_FORMAT"</TT> can also specify the output format, but
|
|
this option overrides it.
|
|
<DT id="223"><B>--out-implib</B> <I>file</I><DD>
|
|
|
|
|
|
Create an import library in <I>file</I> corresponding to the executable
|
|
the linker is generating (eg. a <FONT SIZE="-1">DLL</FONT> or <FONT SIZE="-1">ELF</FONT> program). This import
|
|
library (which should be called <TT>"*.dll.a"</TT> or <TT>"*.a"</TT> 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. <TT>"dlltool"</TT> for DLLs). This option is only available for
|
|
the i386 <FONT SIZE="-1">PE</FONT> and <FONT SIZE="-1">ELF</FONT> targetted ports of the linker.
|
|
<DT id="224"><B>-pie</B><DD>
|
|
|
|
|
|
|
|
<DT id="225"><B>--pic-executable</B><DD>
|
|
|
|
|
|
|
|
Create a position independent executable. This is currently only supported on
|
|
<FONT SIZE="-1">ELF</FONT> platforms. Position independent executables are similar to shared
|
|
libraries in that they are relocated by the dynamic linker to the virtual
|
|
address the <FONT SIZE="-1">OS</FONT> 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.
|
|
<DT id="226"><B>-qmagic</B><DD>
|
|
|
|
|
|
This option is ignored for Linux compatibility.
|
|
<DT id="227"><B>-Qy</B><DD>
|
|
|
|
|
|
This option is ignored for <FONT SIZE="-1">SVR4</FONT> compatibility.
|
|
<DT id="228"><B>--relax</B><DD>
|
|
|
|
|
|
|
|
<DT id="229"><B>--no-relax</B><DD>
|
|
|
|
|
|
|
|
An option with machine dependent effects.
|
|
This option is only supported on a few targets.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
On some platforms the <B>--relax</B> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <FONT SIZE="-1">MN10200</FONT> and <FONT SIZE="-1">MN10300</FONT>
|
|
family of processors.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
On platforms where this is not supported, <B>--relax</B> is accepted,
|
|
but ignored.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
On platforms where <B>--relax</B> is accepted the option
|
|
<B>--no-relax</B> can be used to disable the feature.
|
|
<DT id="230"><B>--retain-symbols-file=</B><I>filename</I><DD>
|
|
|
|
|
|
Retain <I>only</I> the symbols listed in the file <I>filename</I>,
|
|
discarding all others. <I>filename</I> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
<B>--retain-symbols-file</B> does <I>not</I> discard undefined symbols,
|
|
or symbols needed for relocations.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
You may only specify <B>--retain-symbols-file</B> once in the command
|
|
line. It overrides <B>-s</B> and <B>-S</B>.
|
|
<DT id="231"><B>-rpath=</B><I>dir</I><DD>
|
|
|
|
|
|
Add a directory to the runtime library search path. This is used when
|
|
linking an <FONT SIZE="-1">ELF</FONT> executable with shared objects. All <B>-rpath</B>
|
|
arguments are concatenated and passed to the runtime linker, which uses
|
|
them to locate shared objects at runtime.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <B>-rpath</B> option is also used when locating shared objects which
|
|
are needed by shared objects explicitly included in the link; see the
|
|
description of the <B>-rpath-link</B> option. Searching <B>-rpath</B>
|
|
in this way is only supported by native linkers and cross linkers which
|
|
have been configured with the <B>--with-sysroot</B> option.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If <B>-rpath</B> is not used when linking an <FONT SIZE="-1">ELF</FONT> executable, the
|
|
contents of the environment variable <TT>"LD_RUN_PATH"</TT> will be used if it
|
|
is defined.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <B>-rpath</B> option may also be used on SunOS. By default, on
|
|
SunOS, the linker will form a runtime search path out of all the
|
|
<B>-L</B> options it is given. If a <B>-rpath</B> option is used, the
|
|
runtime search path will be formed exclusively using the <B>-rpath</B>
|
|
options, ignoring the <B>-L</B> options. This can be useful when using
|
|
gcc, which adds many <B>-L</B> options which may be on <FONT SIZE="-1">NFS</FONT> mounted
|
|
file systems.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For compatibility with other <FONT SIZE="-1">ELF</FONT> linkers, if the <B>-R</B> option is
|
|
followed by a directory name, rather than a file name, it is treated as
|
|
the <B>-rpath</B> option.
|
|
<DT id="232"><B>-rpath-link=</B><I>dir</I><DD>
|
|
|
|
|
|
When using <FONT SIZE="-1">ELF</FONT> or SunOS, one shared library may require another. This
|
|
happens when an <TT>"ld -shared"</TT> link includes a shared library as one
|
|
of the input files.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <B>-rpath-link</B> option
|
|
specifies the first set of directories to search. The
|
|
<B>-rpath-link</B> option may specify a sequence of directory names
|
|
either by specifying a list of names separated by colons, or by
|
|
appearing multiple times.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The tokens <I></I>$ORIGIN<I></I> and <I></I>$LIB<I></I> 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 <I></I>$ORIGIN<I></I>
|
|
and either <B>lib</B> - for 32-bit binaries - or <B>lib64</B> - for
|
|
64-bit binaries - in the case of <I></I>$LIB<I></I>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The alternative form of these tokens - <I>${</I><FONT SIZE="-1"><I>ORIGIN</I></FONT><I>}</I> and
|
|
<I>${</I><FONT SIZE="-1"><I>LIB</I></FONT><I>}</I> can also be used. The token <I></I>$PLATFORM<I></I> is not
|
|
supported.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The linker uses the following search paths to locate required shared
|
|
libraries:
|
|
<DL COMPACT><DT id="233"><DD>
|
|
<DL COMPACT>
|
|
<DT id="234">1.<DD>
|
|
Any directories specified by <B>-rpath-link</B> options.
|
|
<DT id="235">2.<DD>
|
|
Any directories specified by <B>-rpath</B> options. The difference
|
|
between <B>-rpath</B> and <B>-rpath-link</B> is that directories
|
|
specified by <B>-rpath</B> options are included in the executable and
|
|
used at runtime, whereas the <B>-rpath-link</B> option is only effective
|
|
at link time. Searching <B>-rpath</B> in this way is only supported
|
|
by native linkers and cross linkers which have been configured with
|
|
the <B>--with-sysroot</B> option.
|
|
<DT id="236">3.<DD>
|
|
On an <FONT SIZE="-1">ELF</FONT> system, for native linkers, if the <B>-rpath</B> and
|
|
<B>-rpath-link</B> options were not used, search the contents of the
|
|
environment variable <TT>"LD_RUN_PATH"</TT>.
|
|
<DT id="237">4.<DD>
|
|
On SunOS, if the <B>-rpath</B> option was not used, search any
|
|
directories specified using <B>-L</B> options.
|
|
<DT id="238">5.<DD>
|
|
For a native linker, search the contents of the environment
|
|
variable <TT>"LD_LIBRARY_PATH"</TT>.
|
|
<DT id="239">6.<DD>
|
|
For a native <FONT SIZE="-1">ELF</FONT> linker, the directories in <TT>"DT_RUNPATH"</TT> or
|
|
<TT>"DT_RPATH"</TT> of a shared library are searched for shared
|
|
libraries needed by it. The <TT>"DT_RPATH"</TT> entries are ignored if
|
|
<TT>"DT_RUNPATH"</TT> entries exist.
|
|
<DT id="240">7.<DD>
|
|
The default directories, normally <I>/lib</I> and <I>/usr/lib</I>.
|
|
<DT id="241">8.<DD>
|
|
For a native linker on an <FONT SIZE="-1">ELF</FONT> system, if the file <I>/etc/ld.so.conf</I>
|
|
exists, the list of directories found in that file.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="242"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If the required shared library is not found, the linker will issue a
|
|
warning and continue with the link.
|
|
</DL>
|
|
|
|
<DT id="243"><B>-shared</B><DD>
|
|
|
|
|
|
|
|
<DT id="244"><B>-Bshareable</B><DD>
|
|
|
|
|
|
|
|
Create a shared library. This is currently only supported on <FONT SIZE="-1">ELF, XCOFF</FONT>
|
|
and SunOS platforms. On SunOS, the linker will automatically create a
|
|
shared library if the <B>-e</B> option is not used and there are
|
|
undefined symbols in the link.
|
|
<DT id="245"><B>--sort-common</B><DD>
|
|
|
|
|
|
|
|
<DT id="246"><B>--sort-common=ascending</B><DD>
|
|
|
|
|
|
<DT id="247"><B>--sort-common=descending</B><DD>
|
|
|
|
|
|
|
|
This option tells <B>ld</B> 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.
|
|
<DT id="248"><B>--sort-section=name</B><DD>
|
|
|
|
|
|
This option will apply <TT>"SORT_BY_NAME"</TT> to all wildcard section
|
|
patterns in the linker script.
|
|
<DT id="249"><B>--sort-section=alignment</B><DD>
|
|
|
|
|
|
This option will apply <TT>"SORT_BY_ALIGNMENT"</TT> to all wildcard section
|
|
patterns in the linker script.
|
|
<DT id="250"><B>--spare-dynamic-tags=</B><I>count</I><DD>
|
|
|
|
|
|
This option specifies the number of empty slots to leave in the
|
|
.dynamic section of <FONT SIZE="-1">ELF</FONT> shared objects. Empty slots may be needed by
|
|
post processing tools, such as the prelinker. The default is 5.
|
|
<DT id="251"><B>--split-by-file[=</B><I>size</I><B>]</B><DD>
|
|
|
|
|
|
Similar to <B>--split-by-reloc</B> but creates a new output section for
|
|
each input file when <I>size</I> is reached. <I>size</I> defaults to a
|
|
size of 1 if not given.
|
|
<DT id="252"><B>--split-by-reloc[=</B><I>count</I><B>]</B><DD>
|
|
|
|
|
|
Tries to creates extra sections in the output file so that no single
|
|
output section in the file contains more than <I>count</I> relocations.
|
|
This is useful when generating huge relocatable files for downloading into
|
|
certain real time kernels with the <FONT SIZE="-1">COFF</FONT> object file format; since <FONT SIZE="-1">COFF</FONT>
|
|
cannot represent more than 65535 relocations in a single section. Note
|
|
that this will fail to work with object file formats which do not
|
|
support arbitrary sections. The linker will not split up individual
|
|
input sections for redistribution, so if a single input section contains
|
|
more than <I>count</I> relocations one output section will contain that
|
|
many relocations. <I>count</I> defaults to a value of 32768.
|
|
<DT id="253"><B>--stats</B><DD>
|
|
|
|
|
|
Compute and display statistics about the operation of the linker, such
|
|
as execution time and memory usage.
|
|
<DT id="254"><B>--sysroot=</B><I>directory</I><DD>
|
|
|
|
|
|
Use <I>directory</I> as the location of the sysroot, overriding the
|
|
configure-time default. This option is only supported by linkers
|
|
that were configured using <B>--with-sysroot</B>.
|
|
<DT id="255"><B>--task-link</B><DD>
|
|
|
|
|
|
This is used by <FONT SIZE="-1">COFF/PE</FONT> based targets to create a task-linked object
|
|
file where all of the global symbols have been converted to statics.
|
|
<DT id="256"><B>--traditional-format</B><DD>
|
|
|
|
|
|
For some targets, the output of <B>ld</B> is different in some ways from
|
|
the output of some existing linker. This switch requests <B>ld</B> to
|
|
use the traditional format instead.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For example, on SunOS, <B>ld</B> 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
|
|
<TT>"dbx"</TT> program can not read the resulting program (<TT>"gdb"</TT> has no
|
|
trouble). The <B>--traditional-format</B> switch tells <B>ld</B> to not
|
|
combine duplicate entries.
|
|
<DT id="257"><B>--section-start=</B><I>sectionname</I><B>=</B><I>org</I><DD>
|
|
|
|
|
|
Locate a section in the output file at the absolute
|
|
address given by <I>org</I>. You may use this option as many
|
|
times as necessary to locate multiple sections in the command
|
|
line.
|
|
<I>org</I> must be a single hexadecimal integer;
|
|
for compatibility with other linkers, you may omit the leading
|
|
<B>0x</B> usually associated with hexadecimal values. <I>Note:</I> there
|
|
should be no white space between <I>sectionname</I>, the equals
|
|
sign ("<B>=</B>"), and <I>org</I>.
|
|
<DT id="258"><B>-Tbss=</B><I>org</I><DD>
|
|
|
|
|
|
|
|
<DT id="259"><B>-Tdata=</B><I>org</I><DD>
|
|
|
|
|
|
<DT id="260"><B>-Ttext=</B><I>org</I><DD>
|
|
|
|
|
|
|
|
Same as <B>--section-start</B>, with <TT>".bss"</TT>, <TT>".data"</TT> or
|
|
<TT>".text"</TT> as the <I>sectionname</I>.
|
|
<DT id="261"><B>-Ttext-segment=</B><I>org</I><DD>
|
|
|
|
|
|
When creating an <FONT SIZE="-1">ELF</FONT> executable, it will set the address of the first
|
|
byte of the text segment.
|
|
<DT id="262"><B>-Trodata-segment=</B><I>org</I><DD>
|
|
|
|
|
|
When creating an <FONT SIZE="-1">ELF</FONT> 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.
|
|
<DT id="263"><B>-Tldata-segment=</B><I>org</I><DD>
|
|
|
|
|
|
When creating an <FONT SIZE="-1">ELF</FONT> executable or shared object for x86-64 medium memory
|
|
model, it will set the address of the first byte of the ldata segment.
|
|
<DT id="264"><B>--unresolved-symbols=</B><I>method</I><DD>
|
|
|
|
|
|
Determine how to handle unresolved symbols. There are four possible
|
|
values for <B>method</B>:
|
|
<DL COMPACT><DT id="265"><DD>
|
|
<DL COMPACT>
|
|
<DT id="266"><B>ignore-all</B><DD>
|
|
|
|
|
|
Do not report any unresolved symbols.
|
|
<DT id="267"><B>report-all</B><DD>
|
|
|
|
|
|
Report all unresolved symbols. This is the default.
|
|
<DT id="268"><B>ignore-in-object-files</B><DD>
|
|
|
|
|
|
Report unresolved symbols that are contained in shared libraries, but
|
|
ignore them if they come from regular object files.
|
|
<DT id="269"><B>ignore-in-shared-libs</B><DD>
|
|
|
|
|
|
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.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="270"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The behaviour for shared libraries on their own can also be controlled
|
|
by the <B>--[no-]allow-shlib-undefined</B> option.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Normally the linker will generate an error message for each reported
|
|
unresolved symbol but the option <B>--warn-unresolved-symbols</B>
|
|
can change this to a warning.
|
|
</DL>
|
|
|
|
<DT id="271"><B>--dll-verbose</B><DD>
|
|
|
|
|
|
|
|
<DT id="272"><B>--verbose[=</B><I></I><FONT SIZE="-1"><I>NUMBER</I></FONT><I></I><B>]</B><DD>
|
|
|
|
|
|
|
|
Display the version number for <B>ld</B> 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 <I></I><FONT SIZE="-1"><I>NUMBER</I></FONT><I></I>
|
|
argument > 1, plugin symbol status will also be displayed.
|
|
<DT id="273"><B>--version-script=</B><I>version-scriptfile</I><DD>
|
|
|
|
|
|
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 <FONT SIZE="-1">ELF</FONT> platforms which support shared libraries;
|
|
see <B></B><FONT SIZE="-1"><B>VERSION</B></FONT><B></B>. It is partially supported on <FONT SIZE="-1">PE</FONT> platforms, which can
|
|
use version scripts to filter symbol visibility in auto-export mode: any
|
|
symbols marked <B>local</B> in the version script will not be exported.
|
|
<DT id="274"><B>--warn-common</B><DD>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
There are three kinds of global symbols, illustrated here by C examples:
|
|
<DL COMPACT><DT id="275"><DD>
|
|
<DL COMPACT>
|
|
<DT id="276"><B>int i = 1;</B><DD>
|
|
|
|
|
|
A definition, which goes in the initialized data section of the output
|
|
file.
|
|
<DT id="277"><B>extern int i;</B><DD>
|
|
|
|
|
|
An undefined reference, which does not allocate space.
|
|
There must be either a definition or a common symbol for the
|
|
variable somewhere.
|
|
<DT id="278"><B>int i;</B><DD>
|
|
|
|
|
|
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.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="279"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <B>--warn-common</B> 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.
|
|
<DL COMPACT>
|
|
<DT id="280">1.<DD>
|
|
Turning a common symbol into a reference, because there is already a
|
|
definition for the symbol.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
<file>(<section>): warning: common of `<symbol>'
|
|
overridden by definition
|
|
<file>(<section>): warning: defined here
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="281">2.<DD>
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
<file>(<section>): warning: definition of `<symbol>'
|
|
overriding common
|
|
<file>(<section>): warning: common is here
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="282">3.<DD>
|
|
Merging a common symbol with a previous same-sized common symbol.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
<file>(<section>): warning: multiple common
|
|
of `<symbol>'
|
|
<file>(<section>): warning: previous common is here
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="283">4.<DD>
|
|
Merging a common symbol with a previous larger common symbol.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
<file>(<section>): warning: common of `<symbol>'
|
|
overridden by larger common
|
|
<file>(<section>): warning: larger common is here
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="284">5.<DD>
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
<file>(<section>): warning: common of `<symbol>'
|
|
overriding smaller common
|
|
<file>(<section>): warning: smaller common is here
|
|
|
|
</PRE>
|
|
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="285"><DD>
|
|
</DL>
|
|
|
|
<DT id="286"><B>--warn-constructors</B><DD>
|
|
|
|
|
|
Warn if any global constructors are used. This is only useful for a few
|
|
object file formats. For formats like <FONT SIZE="-1">COFF</FONT> or <FONT SIZE="-1">ELF,</FONT> the linker can not
|
|
detect the use of global constructors.
|
|
<DT id="287"><B>--warn-multiple-gp</B><DD>
|
|
|
|
|
|
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.
|
|
<DT id="288"><B>--warn-once</B><DD>
|
|
|
|
|
|
Only warn once for each undefined symbol, rather than once per module
|
|
which refers to it.
|
|
<DT id="289"><B>--warn-section-align</B><DD>
|
|
|
|
|
|
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 <TT>"SECTIONS"</TT> command does not specify a start address for
|
|
the section.
|
|
<DT id="290"><B>--warn-shared-textrel</B><DD>
|
|
|
|
|
|
Warn if the linker adds a <FONT SIZE="-1">DT_TEXTREL</FONT> to a shared object.
|
|
<DT id="291"><B>--warn-alternate-em</B><DD>
|
|
|
|
|
|
Warn if an object has alternate <FONT SIZE="-1">ELF</FONT> machine code.
|
|
<DT id="292"><B>--warn-unresolved-symbols</B><DD>
|
|
|
|
|
|
If the linker is going to report an unresolved symbol (see the option
|
|
<B>--unresolved-symbols</B>) it will normally generate an error.
|
|
This option makes it generate a warning instead.
|
|
<DT id="293"><B>--error-unresolved-symbols</B><DD>
|
|
|
|
|
|
This restores the linker's default behaviour of generating errors when
|
|
it is reporting unresolved symbols.
|
|
<DT id="294"><B>--whole-archive</B><DD>
|
|
|
|
|
|
For each archive mentioned on the command line after the
|
|
<B>--whole-archive</B> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Two notes when using this option from gcc: First, gcc doesn't know
|
|
about this option, so you have to use <B>-Wl,-whole-archive</B>.
|
|
Second, don't forget to use <B>-Wl,-no-whole-archive</B> 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.
|
|
<DT id="295"><B>--wrap=</B><I>symbol</I><DD>
|
|
|
|
|
|
Use a wrapper function for <I>symbol</I>. Any undefined reference to
|
|
<I>symbol</I> will be resolved to <TT>"__wrap_</TT>symbol<TT>"</TT>. Any
|
|
undefined reference to <TT>"__real_</TT>symbol<TT>"</TT> will be resolved to
|
|
<I>symbol</I>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
This can be used to provide a wrapper for a system function. The
|
|
wrapper function should be called <TT>"__wrap_</TT>symbol<TT>"</TT>. If it
|
|
wishes to call the system function, it should call
|
|
<TT>"__real_</TT>symbol<TT>"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Here is a trivial example:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
void *
|
|
__wrap_malloc (size_t c)
|
|
{
|
|
printf ("malloc called with %zu\n", c);
|
|
return __real_malloc (c);
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you link other code with this file using <B>--wrap malloc</B>, then
|
|
all calls to <TT>"malloc"</TT> will call the function <TT>"__wrap_malloc"</TT>
|
|
instead. The call to <TT>"__real_malloc"</TT> in <TT>"__wrap_malloc"</TT> will
|
|
call the real <TT>"malloc"</TT> function.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
You may wish to provide a <TT>"__real_malloc"</TT> function as well, so that
|
|
links without the <B>--wrap</B> option will succeed. If you do this,
|
|
you should not put the definition of <TT>"__real_malloc"</TT> in the same
|
|
file as <TT>"__wrap_malloc"</TT>; if you do, the assembler may resolve the
|
|
call before the linker has a chance to wrap it to <TT>"malloc"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Only undefined references are replaced by the linker. So, translation unit
|
|
internal references to <I>symbol</I> are not resolved to
|
|
<TT>"__wrap_</TT>symbol<TT>"</TT>. In the next example, the call to <TT>"f"</TT> in
|
|
<TT>"g"</TT> is not resolved to <TT>"__wrap_f"</TT>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
int
|
|
f (void)
|
|
{
|
|
return 123;
|
|
}
|
|
|
|
int
|
|
g (void)
|
|
{
|
|
return f();
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="296"><B>--eh-frame-hdr</B><DD>
|
|
|
|
|
|
|
|
<DT id="297"><B>--no-eh-frame-hdr</B><DD>
|
|
|
|
|
|
|
|
Request (<B>--eh-frame-hdr</B>) or suppress
|
|
(<B>--no-eh-frame-hdr</B>) the creation of <TT>".eh_frame_hdr"</TT>
|
|
section and <FONT SIZE="-1">ELF</FONT> <TT>"PT_GNU_EH_FRAME"</TT> segment header.
|
|
<DT id="298"><B>--no-ld-generated-unwind-info</B><DD>
|
|
|
|
|
|
Request creation of <TT>".eh_frame"</TT> unwind info for linker
|
|
generated code sections like <FONT SIZE="-1">PLT.</FONT> This option is on by default
|
|
if linker generated unwind info is supported.
|
|
<DT id="299"><B>--enable-new-dtags</B><DD>
|
|
|
|
|
|
|
|
<DT id="300"><B>--disable-new-dtags</B><DD>
|
|
|
|
|
|
|
|
This linker can create the new dynamic tags in <FONT SIZE="-1">ELF.</FONT> But the older <FONT SIZE="-1">ELF</FONT>
|
|
systems may not understand them. If you specify
|
|
<B>--enable-new-dtags</B>, the new dynamic tags will be created as needed
|
|
and older dynamic tags will be omitted.
|
|
If you specify <B>--disable-new-dtags</B>, no new dynamic tags will be
|
|
created. By default, the new dynamic tags are not created. Note that
|
|
those options are only available for <FONT SIZE="-1">ELF</FONT> systems.
|
|
<DT id="301"><B>--hash-size=</B><I>number</I><DD>
|
|
|
|
|
|
Set the default size of the linker's hash tables to a prime number
|
|
close to <I>number</I>. 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.
|
|
<DT id="302"><B>--hash-style=</B><I>style</I><DD>
|
|
|
|
|
|
Set the type of linker's hash table(s). <I>style</I> can be either
|
|
<TT>"sysv"</TT> for classic <FONT SIZE="-1">ELF</FONT> <TT>".hash"</TT> section, <TT>"gnu"</TT> for
|
|
new style <FONT SIZE="-1">GNU</FONT> <TT>".gnu.hash"</TT> section or <TT>"both"</TT> for both
|
|
the classic <FONT SIZE="-1">ELF</FONT> <TT>".hash"</TT> and new style <FONT SIZE="-1">GNU</FONT> <TT>".gnu.hash"</TT>
|
|
hash tables. The default depends upon how the linker was configured,
|
|
but for most Linux based systems it will be <TT>"both"</TT>.
|
|
<DT id="303"><B>--compress-debug-sections=none</B><DD>
|
|
|
|
|
|
|
|
<DT id="304"><B>--compress-debug-sections=zlib</B><DD>
|
|
|
|
|
|
<DT id="305"><B>--compress-debug-sections=zlib-gnu</B><DD>
|
|
|
|
|
|
<DT id="306"><B>--compress-debug-sections=zlib-gabi</B><DD>
|
|
|
|
|
|
|
|
On <FONT SIZE="-1">ELF</FONT> platforms, these options control how <FONT SIZE="-1">DWARF</FONT> debug sections are
|
|
compressed using zlib.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
<B>--compress-debug-sections=none</B> doesn't compress <FONT SIZE="-1">DWARF</FONT> debug
|
|
sections. <B>--compress-debug-sections=zlib-gnu</B> compresses
|
|
<FONT SIZE="-1">DWARF</FONT> debug sections and renames them to begin with <B>.zdebug</B>
|
|
instead of <B>.debug</B>. <B>--compress-debug-sections=zlib-gabi</B>
|
|
also compresses <FONT SIZE="-1">DWARF</FONT> debug sections, but rather than renaming them it
|
|
sets the <FONT SIZE="-1">SHF_COMPRESSED</FONT> flag in the sections' headers.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <B>--compress-debug-sections=zlib</B> option is an alias for
|
|
<B>--compress-debug-sections=zlib-gabi</B>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note that this option overrides any compression in input debug
|
|
sections, so if a binary is linked with <B>--compress-debug-sections=none</B>
|
|
for example, then any compressed debug sections in input files will be
|
|
uncompressed before they are copied into the output binary.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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
|
|
<B>--help</B> option.
|
|
<DT id="307"><B>--reduce-memory-overheads</B><DD>
|
|
|
|
|
|
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 <A HREF="/cgi-bin/man/man2html?n+O">O</A>(n) algorithm which uses
|
|
about 40% more memory for symbol storage.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <B>--hash-size</B> switch
|
|
has been used.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <B>--reduce-memory-overheads</B> switch may be also be used to
|
|
enable other tradeoffs in future versions of the linker.
|
|
<DT id="308"><B>--build-id</B><DD>
|
|
|
|
|
|
|
|
<DT id="309"><B>--build-id=</B><I>style</I><DD>
|
|
|
|
|
|
|
|
Request the creation of a <TT>".note.gnu.build-id"</TT> <FONT SIZE="-1">ELF</FONT> note section
|
|
or a <TT>".buildid"</TT> <FONT SIZE="-1">COFF</FONT> section. The contents of the note are
|
|
unique bits identifying this linked file. <I>style</I> can be
|
|
<TT>"uuid"</TT> to use 128 random bits, <TT>"sha1"</TT> to use a 160-bit
|
|
<FONT SIZE="-1">SHA1</FONT> hash on the normative parts of the output contents,
|
|
<TT>"md5"</TT> to use a 128-bit <FONT SIZE="-1">MD5</FONT> hash on the normative parts of
|
|
the output contents, or <TT>"0x</TT>hexstring<TT>"</TT> to use a chosen bit
|
|
string specified as an even number of hexadecimal digits (<TT>"-"</TT> and
|
|
<TT>":"</TT> characters between digit pairs are ignored). If <I>style</I>
|
|
is omitted, <TT>"sha1"</TT> is used.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <TT>"md5"</TT> and <TT>"sha1"</TT> 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 <FONT SIZE="-1">ID</FONT> bit
|
|
string identifying the original linked file does not change.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Passing <TT>"none"</TT> for <I>style</I> disables the setting from any
|
|
<TT>"--build-id"</TT> options earlier on the command line.
|
|
</DL>
|
|
<P>
|
|
|
|
The i386 <FONT SIZE="-1">PE</FONT> linker supports the <B>-shared</B> option, which causes
|
|
the output to be a dynamically linked library (<FONT SIZE="-1">DLL</FONT>) instead of a
|
|
normal executable. You should name the output <TT>"*.dll"</TT> when you
|
|
use this option. In addition, the linker fully supports the standard
|
|
<TT>"*.def"</TT> 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).
|
|
<P>
|
|
|
|
In addition to the options common to all targets, the i386 <FONT SIZE="-1">PE</FONT> linker
|
|
support additional command-line options that are specific to the i386
|
|
<FONT SIZE="-1">PE</FONT> target. Options that take values may be separated from their
|
|
values by either a space or an equals sign.
|
|
<DL COMPACT>
|
|
<DT id="310"><B>--add-stdcall-alias</B><DD>
|
|
|
|
|
|
If given, symbols with a stdcall suffix (@<I>nn</I>) will be exported
|
|
as-is and also with the suffix stripped.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="311"><B>--base-file</B> <I>file</I><DD>
|
|
|
|
|
|
Use <I>file</I> as the name of a file in which to save the base
|
|
addresses of all the relocations needed for generating DLLs with
|
|
<I>dlltool</I>.
|
|
[This is an i386 <FONT SIZE="-1">PE</FONT> specific option]
|
|
<DT id="312"><B>--dll</B><DD>
|
|
|
|
|
|
Create a <FONT SIZE="-1">DLL</FONT> instead of a regular executable. You may also use
|
|
<B>-shared</B> or specify a <TT>"LIBRARY"</TT> in a given <TT>".def"</TT>
|
|
file.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="313"><B>--enable-long-section-names</B><DD>
|
|
|
|
|
|
|
|
<DT id="314"><B>--disable-long-section-names</B><DD>
|
|
|
|
|
|
|
|
The <FONT SIZE="-1">PE</FONT> variants of the <FONT SIZE="-1">COFF</FONT> object format add an extension that permits
|
|
the use of section names longer than eight characters, the normal limit
|
|
for <FONT SIZE="-1">COFF.</FONT> By default, these names are only allowed in object files, as
|
|
fully-linked executable images do not carry the <FONT SIZE="-1">COFF</FONT> string table required
|
|
to support the longer names. As a <FONT SIZE="-1">GNU</FONT> 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,
|
|
<FONT SIZE="-1">GDB</FONT> relies on the use of <FONT SIZE="-1">PE</FONT> 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, <B>ld</B> 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 <FONT SIZE="-1">PE</FONT> targeted ports of the linker]
|
|
<DT id="315"><B>--enable-stdcall-fixup</B><DD>
|
|
|
|
|
|
|
|
<DT id="316"><B>--disable-stdcall-fixup</B><DD>
|
|
|
|
|
|
|
|
If the link finds a symbol that it cannot resolve, it will attempt to
|
|
do ``fuzzy linking'' by looking for another defined symbol that differs
|
|
only in the format of the symbol name (cdecl vs stdcall) and will
|
|
resolve that symbol by linking to the match. For example, the
|
|
undefined symbol <TT>"_foo"</TT> might be linked to the function
|
|
<TT>"_foo@12"</TT>, or the undefined symbol <TT>"_bar@16"</TT> might be linked
|
|
to the function <TT>"_bar"</TT>. 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 <B>--enable-stdcall-fixup</B>, this
|
|
feature is fully enabled and warnings are not printed. If you specify
|
|
<B>--disable-stdcall-fixup</B>, this feature is disabled and such
|
|
mismatches are considered to be errors.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="317"><B>--leading-underscore</B><DD>
|
|
|
|
|
|
|
|
<DT id="318"><B>--no-leading-underscore</B><DD>
|
|
|
|
|
|
|
|
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.
|
|
<DT id="319"><B>--export-all-symbols</B><DD>
|
|
|
|
|
|
If given, all global symbols in the objects used to build a <FONT SIZE="-1">DLL</FONT> will
|
|
be exported by the <FONT SIZE="-1">DLL.</FONT> Note that this is the default if there
|
|
otherwise wouldn't be any exported symbols. When symbols are
|
|
explicitly exported via <FONT SIZE="-1">DEF</FONT> files or implicitly exported via function
|
|
attributes, the default is to not export anything else unless this
|
|
option is given. Note that the symbols <TT>"DllMain@12"</TT>,
|
|
<TT>"DllEntryPoint@0"</TT>, <TT>"DllMainCRTStartup@12"</TT>, and
|
|
<TT>"impure_ptr"</TT> will not be automatically
|
|
exported. Also, symbols imported from other DLLs will not be
|
|
re-exported, nor will symbols specifying the <FONT SIZE="-1">DLL</FONT>'s internal layout
|
|
such as those beginning with <TT>"_head_"</TT> or ending with
|
|
<TT>"_iname"</TT>. In addition, no symbols from <TT>"libgcc"</TT>,
|
|
<TT>"libstd++"</TT>, <TT>"libmingw32"</TT>, or <TT>"crtX.o"</TT> will be exported.
|
|
Symbols whose names begin with <TT>"__rtti_"</TT> or <TT>"__builtin_"</TT> will
|
|
not be exported, to help with C<FONT SIZE="-2">++</FONT> 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: <TT>"_cygwin_dll_entry@12"</TT>,
|
|
<TT>"_cygwin_crt0_common@8"</TT>, <TT>"_cygwin_noncygwin_dll_entry@12"</TT>,
|
|
<TT>"_fmode"</TT>, <TT>"_impure_ptr"</TT>, <TT>"cygwin_attach_dll"</TT>,
|
|
<TT>"cygwin_premain0"</TT>, <TT>"cygwin_premain1"</TT>, <TT>"cygwin_premain2"</TT>,
|
|
<TT>"cygwin_premain3"</TT>, and <TT>"environ"</TT>.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="320"><B>--exclude-symbols</B> <I>symbol</I><B>,</B><I>symbol</I><B>,...</B><DD>
|
|
|
|
|
|
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 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="321"><B>--exclude-all-symbols</B><DD>
|
|
|
|
|
|
Specifies no symbols should be automatically exported.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="322"><B>--file-alignment</B><DD>
|
|
|
|
|
|
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 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="323"><B>--heap</B> <I>reserve</I><DD>
|
|
|
|
|
|
|
|
<DT id="324"><B>--heap</B> <I>reserve</I><B>,</B><I>commit</I><DD>
|
|
|
|
|
|
|
|
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 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="325"><B>--image-base</B> <I>value</I><DD>
|
|
|
|
|
|
Use <I>value</I> 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 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="326"><B>--kill-at</B><DD>
|
|
|
|
|
|
If given, the stdcall suffixes (@<I>nn</I>) will be stripped from
|
|
symbols before they are exported.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="327"><B>--large-address-aware</B><DD>
|
|
|
|
|
|
If given, the appropriate bit in the ``Characteristics'' field of the <FONT SIZE="-1">COFF</FONT>
|
|
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=<I>value</I> megabytes switch in the ``[operating systems]''
|
|
section of the <FONT SIZE="-1">BOOT.INI.</FONT> Otherwise, this bit has no effect.
|
|
[This option is specific to <FONT SIZE="-1">PE</FONT> targeted ports of the linker]
|
|
<DT id="328"><B>--disable-large-address-aware</B><DD>
|
|
|
|
|
|
Reverts the effect of a previous <B>--large-address-aware</B> option.
|
|
This is useful if <B>--large-address-aware</B> 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 <FONT SIZE="-1">PE</FONT> targeted ports of the linker]
|
|
<DT id="329"><B>--major-image-version</B> <I>value</I><DD>
|
|
|
|
|
|
Sets the major number of the ``image version''. Defaults to 1.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="330"><B>--major-os-version</B> <I>value</I><DD>
|
|
|
|
|
|
Sets the major number of the ``os version''. Defaults to 4.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="331"><B>--major-subsystem-version</B> <I>value</I><DD>
|
|
|
|
|
|
Sets the major number of the ``subsystem version''. Defaults to 4.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="332"><B>--minor-image-version</B> <I>value</I><DD>
|
|
|
|
|
|
Sets the minor number of the ``image version''. Defaults to 0.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="333"><B>--minor-os-version</B> <I>value</I><DD>
|
|
|
|
|
|
Sets the minor number of the ``os version''. Defaults to 0.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="334"><B>--minor-subsystem-version</B> <I>value</I><DD>
|
|
|
|
|
|
Sets the minor number of the ``subsystem version''. Defaults to 0.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="335"><B>--output-def</B> <I>file</I><DD>
|
|
|
|
|
|
The linker will create the file <I>file</I> which will contain a <FONT SIZE="-1">DEF</FONT>
|
|
file corresponding to the <FONT SIZE="-1">DLL</FONT> the linker is generating. This <FONT SIZE="-1">DEF</FONT> file
|
|
(which should be called <TT>"*.def"</TT>) may be used to create an import
|
|
library with <TT>"dlltool"</TT> or may be used as a reference to
|
|
automatically or implicitly exported symbols.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="336"><B>--enable-auto-image-base</B><DD>
|
|
|
|
|
|
|
|
<DT id="337"><B>--enable-auto-image-base=</B><I>value</I><DD>
|
|
|
|
|
|
|
|
Automatically choose the image base for DLLs, optionally starting with base
|
|
<I>value</I>, unless one is specified using the <TT>"--image-base"</TT> argument.
|
|
By using a hash generated from the dllname to create unique image bases
|
|
for each <FONT SIZE="-1">DLL,</FONT> in-memory collisions and relocations which can delay program
|
|
execution are avoided.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="338"><B>--disable-auto-image-base</B><DD>
|
|
|
|
|
|
Do not automatically generate a unique image base. If there is no
|
|
user-specified image base (<TT>"--image-base"</TT>) then use the platform
|
|
default.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="339"><B>--dll-search-prefix</B> <I>string</I><DD>
|
|
|
|
|
|
When linking dynamically to a dll without an import library,
|
|
search for <TT>"<string><basename>.dll"</TT> in preference to
|
|
<TT>"lib<basename>.dll"</TT>. This behaviour allows easy distinction
|
|
between DLLs built for the various ``subplatforms'': native, cygwin,
|
|
uwin, pw, etc. For instance, cygwin DLLs typically use
|
|
<TT>"--dll-search-prefix=cyg"</TT>.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="340"><B>--enable-auto-import</B><DD>
|
|
|
|
|
|
Do sophisticated linking of <TT>"_symbol"</TT> to <TT>"__imp__symbol"</TT> for
|
|
<FONT SIZE="-1">DATA</FONT> imports from DLLs, thus making it possible to bypass the dllimport
|
|
mechanism on the user side and to reference unmangled symbol names.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The following remarks pertain to the original implementation of the
|
|
feature and are obsolete nowadays for Cygwin and MinGW targets.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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:
|
|
<A HREF="http://www.cygwin.com/ml/cygwin/2004-09/msg01101.html">http://www.cygwin.com/ml/cygwin/2004-09/msg01101.html</A>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Using 'auto-import' generally will 'just work' --- but sometimes you may
|
|
see this message:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
"variable '<var>' can't be auto-imported. Please read the
|
|
documentation for ld's <TT>"--enable-auto-import"</TT> for details."
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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 <FONT SIZE="-1">DLL,</FONT> as well as using a
|
|
constant index into an array variable imported from a <FONT SIZE="-1">DLL.</FONT> 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
There are several ways to address this difficulty, regardless of the
|
|
data type of the exported variable:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
extern type extern_array[];
|
|
extern_array[1] -->
|
|
{ volatile type *t=extern_array; t[1] }
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
or
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
extern type extern_array[];
|
|
extern_array[1] -->
|
|
{ volatile int t=1; extern_array[t] }
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For structs (and most other multiword data types) the only option
|
|
is to make the struct itself (or the long long, or the ...) variable:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
extern struct s extern_struct;
|
|
extern_struct.field -->
|
|
{ volatile struct s *t=&extern_struct; t->field }
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
or
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
extern long long extern_ll;
|
|
extern_ll -->
|
|
{ volatile long long * local_ll=&extern_ll; *local_ll }
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
A third method of dealing with this difficulty is to abandon
|
|
'auto-import' for the offending symbol and mark it with
|
|
<TT>"__declspec(dllimport)"</TT>. However, in practice that
|
|
requires using compile-time #defines to indicate whether you are
|
|
building a <FONT SIZE="-1">DLL,</FONT> building client code that will link to the <FONT SIZE="-1">DLL,</FONT> 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:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Original:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
--foo.h
|
|
extern int arr[];
|
|
--foo.c
|
|
#include "foo.h"
|
|
void main(int argc, char **argv){
|
|
printf("%d\n",arr[1]);
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Solution 1:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
--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\n",parr[1]);
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Solution 2:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
--foo.h
|
|
/* Note: auto-export is assumed (no __declspec(dllexport)) */
|
|
#if (defined(_WIN32) || defined(__CYGWIN__)) && \
|
|
!(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\n",arr[1]);
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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. <B>set_foo()</B> and <B>get_foo()</B> accessor
|
|
functions).
|
|
<DT id="341"><B>--disable-auto-import</B><DD>
|
|
|
|
|
|
Do not attempt to do sophisticated linking of <TT>"_symbol"</TT> to
|
|
<TT>"__imp__symbol"</TT> for <FONT SIZE="-1">DATA</FONT> imports from DLLs.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="342"><B>--enable-runtime-pseudo-reloc</B><DD>
|
|
|
|
|
|
If your code contains expressions described in --enable-auto-import section,
|
|
that is, <FONT SIZE="-1">DATA</FONT> imports from <FONT SIZE="-1">DLL</FONT> 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 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="343"><B>--disable-runtime-pseudo-reloc</B><DD>
|
|
|
|
|
|
Do not create pseudo relocations for non-zero offset <FONT SIZE="-1">DATA</FONT> imports from DLLs.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="344"><B>--enable-extra-pe-debug</B><DD>
|
|
|
|
|
|
Show additional debug info related to auto-import symbol thunking.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="345"><B>--section-alignment</B><DD>
|
|
|
|
|
|
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 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="346"><B>--stack</B> <I>reserve</I><DD>
|
|
|
|
|
|
|
|
<DT id="347"><B>--stack</B> <I>reserve</I><B>,</B><I>commit</I><DD>
|
|
|
|
|
|
|
|
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 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
<DT id="348"><B>--subsystem</B> <I>which</I><DD>
|
|
|
|
|
|
|
|
<DT id="349"><B>--subsystem</B> <I>which</I><B>:</B><I>major</I><DD>
|
|
|
|
|
|
<DT id="350"><B>--subsystem</B> <I>which</I><B>:</B><I>major</I><B>.</B><I>minor</I><DD>
|
|
|
|
|
|
|
|
Specifies the subsystem under which your program will execute. The
|
|
legal values for <I>which</I> are <TT>"native"</TT>, <TT>"windows"</TT>,
|
|
<TT>"console"</TT>, <TT>"posix"</TT>, and <TT>"xbox"</TT>. You may optionally set
|
|
the subsystem version also. Numeric values are also accepted for
|
|
<I>which</I>.
|
|
[This option is specific to the i386 <FONT SIZE="-1">PE</FONT> targeted port of the linker]
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The following options set flags in the <TT>"DllCharacteristics"</TT> field
|
|
of the <FONT SIZE="-1">PE</FONT> file header:
|
|
[These options are specific to <FONT SIZE="-1">PE</FONT> targeted ports of the linker]
|
|
<DT id="351"><B>--high-entropy-va</B><DD>
|
|
|
|
|
|
Image is compatible with 64-bit address space layout randomization
|
|
(<FONT SIZE="-1">ASLR</FONT>).
|
|
This option also implies <B>--dynamicbase</B> and
|
|
<B>--enable-reloc-section</B>.
|
|
<DT id="352"><B>--dynamicbase</B><DD>
|
|
|
|
|
|
The image base address may be relocated using address space layout
|
|
randomization (<FONT SIZE="-1">ASLR</FONT>). This feature was introduced with <FONT SIZE="-1">MS</FONT> Windows
|
|
Vista for i386 <FONT SIZE="-1">PE</FONT> targets.
|
|
This option also implies <B>--enable-reloc-section</B>.
|
|
<DT id="353"><B>--forceinteg</B><DD>
|
|
|
|
|
|
Code integrity checks are enforced.
|
|
<DT id="354"><B>--nxcompat</B><DD>
|
|
|
|
|
|
The image is compatible with the Data Execution Prevention.
|
|
This feature was introduced with <FONT SIZE="-1">MS</FONT> Windows <FONT SIZE="-1">XP SP2</FONT> for i386 <FONT SIZE="-1">PE</FONT> targets.
|
|
<DT id="355"><B>--no-isolation</B><DD>
|
|
|
|
|
|
Although the image understands isolation, do not isolate the image.
|
|
<DT id="356"><B>--no-seh</B><DD>
|
|
|
|
|
|
The image does not use <FONT SIZE="-1">SEH.</FONT> No <FONT SIZE="-1">SE</FONT> handler may be called from
|
|
this image.
|
|
<DT id="357"><B>--no-bind</B><DD>
|
|
|
|
|
|
Do not bind this image.
|
|
<DT id="358"><B>--wdmdriver</B><DD>
|
|
|
|
|
|
The driver uses the <FONT SIZE="-1">MS</FONT> Windows Driver Model.
|
|
<DT id="359"><B>--tsaware</B><DD>
|
|
|
|
|
|
The image is Terminal Server aware.
|
|
<DT id="360"><B>--insert-timestamp</B><DD>
|
|
|
|
|
|
|
|
<DT id="361"><B>--no-insert-timestamp</B><DD>
|
|
|
|
|
|
|
|
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 <B>--no-insert-timestamp</B>
|
|
can be used to insert a zero value for the timestamp, this ensuring
|
|
that binaries produced from identical sources will compare
|
|
identically.
|
|
<DT id="362"><B>--enable-reloc-section</B><DD>
|
|
|
|
|
|
Create the base relocation table, which is necessary if the image
|
|
is loaded at a different image base than specified in the <FONT SIZE="-1">PE</FONT> header.
|
|
</DL>
|
|
<P>
|
|
|
|
The C6X uClinux target uses a binary format called <FONT SIZE="-1">DSBT</FONT> to support shared
|
|
libraries. Each shared library in the system needs to have a unique index;
|
|
all executables use an index of 0.
|
|
<DL COMPACT>
|
|
<DT id="363"><B>--dsbt-size</B> <I>size</I><DD>
|
|
|
|
|
|
This option sets the number of entries in the <FONT SIZE="-1">DSBT</FONT> of the current executable
|
|
or shared library to <I>size</I>. The default is to create a table with 64
|
|
entries.
|
|
<DT id="364"><B>--dsbt-index</B> <I>index</I><DD>
|
|
|
|
|
|
This option sets the <FONT SIZE="-1">DSBT</FONT> index of the current executable or shared library
|
|
to <I>index</I>. The default is 0, which is appropriate for generating
|
|
executables. If a shared library is generated with a <FONT SIZE="-1">DSBT</FONT> index of 0, the
|
|
<TT>"R_C6000_DSBT_INDEX"</TT> relocs are copied into the output file.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <B>--no-merge-exidx-entries</B> switch disables the merging of adjacent
|
|
exidx entries in frame unwind info.
|
|
<DT id="365"><B>--branch-stub</B><DD>
|
|
|
|
|
|
This option enables linker branch relaxation by inserting branch stub
|
|
sections when needed to extend the range of branches. This option is
|
|
usually not required since C-SKY supports branch and call instructions that
|
|
can access the full memory range and branch relaxation is normally handled by
|
|
the compiler or assembler.
|
|
<DT id="366"><B>--stub-group-size=</B><I>N</I><DD>
|
|
|
|
|
|
This option allows finer control of linker branch stub creation.
|
|
It sets the maximum size of a group of input sections that can
|
|
be handled by one stub section. A negative value of <I>N</I> locates
|
|
stub sections after their branches, while a positive value allows stub
|
|
sections to appear either before or after the branches. Values of
|
|
<B>1</B> or <B>-1</B> indicate that the
|
|
linker should choose suitable defaults.
|
|
</DL>
|
|
<P>
|
|
|
|
The 68HC11 and 68HC12 linkers support specific options to control the
|
|
memory bank switching mapping and trampoline code generation.
|
|
<DL COMPACT>
|
|
<DT id="367"><B>--no-trampoline</B><DD>
|
|
|
|
|
|
This option disables the generation of trampoline. By default a trampoline
|
|
is generated for each far function which is called using a <TT>"jsr"</TT>
|
|
instruction (this happens when a pointer to a far function is taken).
|
|
<DT id="368"><B>--bank-window</B> <I>name</I><DD>
|
|
|
|
|
|
This option indicates to the linker the name of the memory region in
|
|
the <B></B><FONT SIZE="-1"><B>MEMORY</B></FONT><B></B> 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.
|
|
</DL>
|
|
<P>
|
|
|
|
The following options are supported to control handling of <FONT SIZE="-1">GOT</FONT> generation
|
|
when linking for 68K targets.
|
|
<DL COMPACT>
|
|
<DT id="369"><B>--got=</B><I>type</I><DD>
|
|
|
|
|
|
This option tells the linker which <FONT SIZE="-1">GOT</FONT> generation scheme to use.
|
|
<I>type</I> should be one of <B>single</B>, <B>negative</B>,
|
|
<B>multigot</B> or <B>target</B>. For more information refer to the
|
|
Info entry for <I>ld</I>.
|
|
</DL>
|
|
<P>
|
|
|
|
The following options are supported to control microMIPS instruction
|
|
generation and branch relocation checks for <FONT SIZE="-1">ISA</FONT> mode transitions when
|
|
linking for <FONT SIZE="-1">MIPS</FONT> targets.
|
|
<DL COMPACT>
|
|
<DT id="370"><B>--insn32</B><DD>
|
|
|
|
|
|
|
|
<DT id="371"><B>--no-insn32</B><DD>
|
|
|
|
|
|
|
|
These options control the choice of microMIPS instructions used in code
|
|
generated by the linker, such as that in the <FONT SIZE="-1">PLT</FONT> or lazy binding stubs,
|
|
or in relaxation. If <B>--insn32</B> is used, then the linker only uses
|
|
32-bit instruction encodings. By default or if <B>--no-insn32</B> is
|
|
used, all instruction encodings are used, including 16-bit ones where
|
|
possible.
|
|
<DT id="372"><B>--ignore-branch-isa</B><DD>
|
|
|
|
|
|
|
|
<DT id="373"><B>--no-ignore-branch-isa</B><DD>
|
|
|
|
|
|
|
|
These options control branch relocation checks for invalid <FONT SIZE="-1">ISA</FONT> mode
|
|
transitions. If <B>--ignore-branch-isa</B> is used, then the linker
|
|
accepts any branch relocations and any <FONT SIZE="-1">ISA</FONT> mode transition required
|
|
is lost in relocation calculation, except for some cases of <TT>"BAL"</TT>
|
|
instructions which meet relaxation conditions and are converted to
|
|
equivalent <TT>"JALX"</TT> instructions as the associated relocation is
|
|
calculated. By default or if <B>--no-ignore-branch-isa</B> is used
|
|
a check is made causing the loss of an <FONT SIZE="-1">ISA</FONT> mode transition to produce
|
|
an error.
|
|
<DT id="374"><B>--compact-branches</B><DD>
|
|
|
|
|
|
|
|
<DT id="375"><B>--compact-branches</B><DD>
|
|
|
|
|
|
|
|
These options control the generation of compact instructions by the linker
|
|
in the <FONT SIZE="-1">PLT</FONT> entries for <FONT SIZE="-1">MIPS R6.</FONT>
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>ENVIRONMENT</H2>
|
|
|
|
|
|
|
|
You can change the behaviour of <B>ld</B> with the environment variables
|
|
<TT>"GNUTARGET"</TT>,
|
|
<TT>"LDEMULATION"</TT> and <TT>"COLLECT_NO_DEMANGLE"</TT>.
|
|
<P>
|
|
|
|
<TT>"GNUTARGET"</TT> determines the input-file object format if you don't
|
|
use <B>-b</B> (or its synonym <B>--format</B>). Its value should be one
|
|
of the <FONT SIZE="-1">BFD</FONT> names for an input format. If there is no
|
|
<TT>"GNUTARGET"</TT> in the environment, <B>ld</B> uses the natural format
|
|
of the target. If <TT>"GNUTARGET"</TT> is set to <TT>"default"</TT> then <FONT SIZE="-1">BFD</FONT>
|
|
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
|
|
<FONT SIZE="-1">BFD</FONT> on each system places the conventional format for that system first
|
|
in the search-list, so ambiguities are resolved in favor of convention.
|
|
<P>
|
|
|
|
<TT>"LDEMULATION"</TT> determines the default emulation if you don't use the
|
|
<B>-m</B> option. The emulation can affect various aspects of linker
|
|
behaviour, particularly the default linker script. You can list the
|
|
available emulations with the <B>--verbose</B> or <B>-V</B> options. If
|
|
the <B>-m</B> option is not used, and the <TT>"LDEMULATION"</TT> environment
|
|
variable is not defined, the default emulation depends upon how the
|
|
linker was configured.
|
|
<P>
|
|
|
|
Normally, the linker will default to demangling symbols. However, if
|
|
<TT>"COLLECT_NO_DEMANGLE"</TT> is set in the environment, then it will
|
|
default to not demangling symbols. This environment variable is used in
|
|
a similar fashion by the <TT>"gcc"</TT> linker wrapper program. The default
|
|
may be overridden by the <B>--demangle</B> and <B>--no-demangle</B>
|
|
options.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+ar">ar</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+nm">nm</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+objcopy">objcopy</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+objdump">objdump</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+readelf">readelf</A></B>(1) and
|
|
the Info entries for <I>binutils</I> and
|
|
<I>ld</I>.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>COPYRIGHT</H2>
|
|
|
|
|
|
|
|
Copyright (c) 1991-2020 Free Software Foundation, Inc.
|
|
<P>
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the <FONT SIZE="-1">GNU</FONT> 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 ``<FONT SIZE="-1">GNU</FONT> Free Documentation License''.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="376"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="377"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="378"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="379"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DT id="380"><A HREF="#lbAF">ENVIRONMENT</A><DD>
|
|
<DT id="381"><A HREF="#lbAG">SEE ALSO</A><DD>
|
|
<DT id="382"><A HREF="#lbAH">COPYRIGHT</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:18 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|