You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
3186 lines
145 KiB
HTML
3186 lines
145 KiB
HTML
4 years ago
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html>
|
||
|
|
<!-- This file documents the GNU linker LD
|
||
|
|
(SiFive Binutils 2.32.0-2020.04.1)
|
||
|
|
version 2.32.
|
||
|
|
|
||
|
|
Copyright (C) 1991-2019 Free Software Foundation, Inc.
|
||
|
|
|
||
|
|
Permission is granted to copy, distribute and/or modify this document
|
||
|
|
under the terms of the GNU 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 "GNU Free Documentation License". -->
|
||
|
|
<!-- Created by GNU Texinfo 6.4, http://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<title>Options (LD)</title>
|
||
|
|
|
||
|
|
<meta name="description" content="Options (LD)">
|
||
|
|
<meta name="keywords" content="Options (LD)">
|
||
|
|
<meta name="resource-type" content="document">
|
||
|
|
<meta name="distribution" content="global">
|
||
|
|
<meta name="Generator" content="makeinfo">
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<link href="index.html#Top" rel="start" title="Top">
|
||
|
|
<link href="LD-Index.html#LD-Index" rel="index" title="LD Index">
|
||
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||
|
|
<link href="Invocation.html#Invocation" rel="up" title="Invocation">
|
||
|
|
<link href="Environment.html#Environment" rel="next" title="Environment">
|
||
|
|
<link href="Invocation.html#Invocation" rel="prev" title="Invocation">
|
||
|
|
<style type="text/css">
|
||
|
|
<!--
|
||
|
|
a.summary-letter {text-decoration: none}
|
||
|
|
blockquote.indentedblock {margin-right: 0em}
|
||
|
|
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
|
||
|
|
blockquote.smallquotation {font-size: smaller}
|
||
|
|
div.display {margin-left: 3.2em}
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
div.lisp {margin-left: 3.2em}
|
||
|
|
div.smalldisplay {margin-left: 3.2em}
|
||
|
|
div.smallexample {margin-left: 3.2em}
|
||
|
|
div.smalllisp {margin-left: 3.2em}
|
||
|
|
kbd {font-style: oblique}
|
||
|
|
pre.display {font-family: inherit}
|
||
|
|
pre.format {font-family: inherit}
|
||
|
|
pre.menu-comment {font-family: serif}
|
||
|
|
pre.menu-preformatted {font-family: serif}
|
||
|
|
pre.smalldisplay {font-family: inherit; font-size: smaller}
|
||
|
|
pre.smallexample {font-size: smaller}
|
||
|
|
pre.smallformat {font-family: inherit; font-size: smaller}
|
||
|
|
pre.smalllisp {font-size: smaller}
|
||
|
|
span.nolinebreak {white-space: nowrap}
|
||
|
|
span.roman {font-family: initial; font-weight: normal}
|
||
|
|
span.sansserif {font-family: sans-serif; font-weight: normal}
|
||
|
|
ul.no-bullet {list-style: none}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en">
|
||
|
|
<a name="Options"></a>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Next: <a href="Environment.html#Environment" accesskey="n" rel="next">Environment</a>, Up: <a href="Invocation.html#Invocation" accesskey="u" rel="up">Invocation</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="LD-Index.html#LD-Index" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<a name="Command_002dline-Options"></a>
|
||
|
|
<h3 class="section">2.1 Command-line Options</h3>
|
||
|
|
|
||
|
|
<a name="index-command-line"></a>
|
||
|
|
<a name="index-options"></a>
|
||
|
|
|
||
|
|
|
||
|
|
<p>The linker supports a plethora of command-line options, but in actual
|
||
|
|
practice few of them are used in any particular context.
|
||
|
|
<a name="index-standard-Unix-system"></a>
|
||
|
|
For instance, a frequent use of <code>ld</code> is to link standard Unix
|
||
|
|
object files on a standard, supported Unix system. On such a system, to
|
||
|
|
link a file <code>hello.o</code>:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">ld -o <var>output</var> /lib/crt0.o hello.o -lc
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>This tells <code>ld</code> to produce a file called <var>output</var> as the
|
||
|
|
result of linking the file <code>/lib/crt0.o</code> with <code>hello.o</code> and
|
||
|
|
the library <code>libc.a</code>, which will come from the standard search
|
||
|
|
directories. (See the discussion of the ‘<samp>-l</samp>’ option below.)
|
||
|
|
</p>
|
||
|
|
<p>Some of the command-line options to <code>ld</code> may be specified at any
|
||
|
|
point in the command line. However, options which refer to files, such
|
||
|
|
as ‘<samp>-l</samp>’ or ‘<samp>-T</samp>’, 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>
|
||
|
|
<a name="index-object-files"></a>
|
||
|
|
<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>
|
||
|
|
<p>Usually the linker is invoked with at least one object file, but you can
|
||
|
|
specify other forms of binary input files using ‘<samp>-l</samp>’, ‘<samp>-R</samp>’,
|
||
|
|
and the script command language. If <em>no</em> binary input files at all
|
||
|
|
are specified, the linker does not produce any output, and issues the
|
||
|
|
message ‘<samp>No input files</samp>’.
|
||
|
|
</p>
|
||
|
|
<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 ‘<samp>-T</samp>’). 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
|
||
|
|
<code>INPUT</code> or <code>GROUP</code> 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 ‘<samp>-T</samp>’ option
|
||
|
|
to replace the default linker script entirely, but note the effect of
|
||
|
|
the <code>INSERT</code> command. See <a href="Scripts.html#Scripts">Scripts</a>.
|
||
|
|
</p>
|
||
|
|
<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>
|
||
|
|
<p>For options whose names are multiple letters, either one dash or two can
|
||
|
|
precede the option name; for example, ‘<samp>-trace-symbol</samp>’ and
|
||
|
|
‘<samp>--trace-symbol</samp>’ 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
|
||
|
|
‘<samp>-o</samp>’ option. So for example ‘<samp>-omagic</samp>’ sets the output file
|
||
|
|
name to ‘<samp>magic</samp>’ whereas ‘<samp>--omagic</samp>’ sets the NMAGIC flag on the
|
||
|
|
output.
|
||
|
|
</p>
|
||
|
|
<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,
|
||
|
|
‘<samp>--trace-symbol foo</samp>’ and ‘<samp>--trace-symbol=foo</samp>’ are equivalent.
|
||
|
|
Unique abbreviations of the names of multiple-letter options are
|
||
|
|
accepted.
|
||
|
|
</p>
|
||
|
|
<p>Note—if the linker is being invoked indirectly, via a compiler driver
|
||
|
|
(e.g. ‘<samp>gcc</samp>’) then all the linker command-line options should be
|
||
|
|
prefixed by ‘<samp>-Wl,</samp>’ (or whatever is appropriate for the particular
|
||
|
|
compiler driver) like this:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample"> gcc -Wl,--start-group foo.o bar.o -Wl,--end-group
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample"> gcc foo.o bar.o -Wl,-eENTRY -Wl,-Map=a.map
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>Here is a table of the generic command-line switches accepted by the GNU
|
||
|
|
linker:
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dt><code>@<var>file</var></code></dt>
|
||
|
|
<dd><p>Read command-line options from <var>file</var>. The options read are
|
||
|
|
inserted in place of the original @<var>file</var> option. If <var>file</var>
|
||
|
|
does not exist, or cannot be read, then the option will be treated
|
||
|
|
literally, and not removed.
|
||
|
|
</p>
|
||
|
|
<p>Options in <var>file</var> 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 <var>file</var> may itself contain additional
|
||
|
|
@<var>file</var> options; any such options will be processed recursively.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002da-keyword"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-a <var>keyword</var></code></dt>
|
||
|
|
<dd><p>This option is supported for HP/UX compatibility. The <var>keyword</var>
|
||
|
|
argument must be one of the strings ‘<samp>archive</samp>’, ‘<samp>shared</samp>’, or
|
||
|
|
‘<samp>default</samp>’. ‘<samp>-aarchive</samp>’ is functionally equivalent to
|
||
|
|
‘<samp>-Bstatic</samp>’, and the other two keywords are functionally equivalent
|
||
|
|
to ‘<samp>-Bdynamic</samp>’. This option may be used any number of times.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002daudit-AUDITLIB"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--audit <var>AUDITLIB</var></code></dt>
|
||
|
|
<dd><p>Adds <var>AUDITLIB</var> to the <code>DT_AUDIT</code> entry of the dynamic section.
|
||
|
|
<var>AUDITLIB</var> is not checked for existence, nor will it use the DT_SONAME
|
||
|
|
specified in the library. If specified multiple times <code>DT_AUDIT</code>
|
||
|
|
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 <code>DT_DEPAUDIT</code> entry in the output file.
|
||
|
|
This option is only meaningful on ELF platforms supporting the rtld-audit
|
||
|
|
interface.
|
||
|
|
</p>
|
||
|
|
<a name="index-binary-input-format"></a>
|
||
|
|
<a name="index-_002db-format"></a>
|
||
|
|
<a name="index-_002d_002dformat_003dformat"></a>
|
||
|
|
<a name="index-input-format"></a>
|
||
|
|
<a name="index-input-format-1"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-b <var>input-format</var></code></dt>
|
||
|
|
<dt><code>--format=<var>input-format</var></code></dt>
|
||
|
|
<dd><p><code>ld</code> may be configured to support more than one kind of object
|
||
|
|
file. If your <code>ld</code> is configured this way, you can use the
|
||
|
|
‘<samp>-b</samp>’ option to specify the binary format for input object files
|
||
|
|
that follow this option on the command line. Even when <code>ld</code> is
|
||
|
|
configured to support alternative object formats, you don’t usually need
|
||
|
|
to specify this, as <code>ld</code> should be configured to expect as a
|
||
|
|
default input format the most usual format on each machine.
|
||
|
|
<var>input-format</var> is a text string, the name of a particular format
|
||
|
|
supported by the BFD libraries. (You can list the available binary
|
||
|
|
formats with ‘<samp>objdump -i</samp>’.)
|
||
|
|
See <a href="BFD.html#BFD">BFD</a>.
|
||
|
|
</p>
|
||
|
|
<p>You may want to use this option if you are linking files with an unusual
|
||
|
|
binary format. You can also use ‘<samp>-b</samp>’ to switch formats explicitly (when
|
||
|
|
linking object files of different formats), by including
|
||
|
|
‘<samp>-b <var>input-format</var></samp>’ before each group of object files in a
|
||
|
|
particular format.
|
||
|
|
</p>
|
||
|
|
<p>The default format is taken from the environment variable
|
||
|
|
<code>GNUTARGET</code>.
|
||
|
|
See <a href="Environment.html#Environment">Environment</a>.
|
||
|
|
You can also define the input format from a script, using the command
|
||
|
|
<code>TARGET</code>;
|
||
|
|
see <a href="Format-Commands.html#Format-Commands">Format Commands</a>.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dc-MRI_002dcmdfile"></a>
|
||
|
|
<a name="index-_002d_002dmri_002dscript_003dMRI_002dcmdfile"></a>
|
||
|
|
<a name="index-compatibility_002c-MRI"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-c <var>MRI-commandfile</var></code></dt>
|
||
|
|
<dt><code>--mri-script=<var>MRI-commandfile</var></code></dt>
|
||
|
|
<dd><p>For compatibility with linkers produced by MRI, <code>ld</code> accepts script
|
||
|
|
files written in an alternate, restricted command language, described in
|
||
|
|
<a href="MRI.html#MRI">MRI Compatible Script Files</a>.
|
||
|
|
Introduce MRI script files with
|
||
|
|
the option ‘<samp>-c</samp>’; use the ‘<samp>-T</samp>’ option to run linker
|
||
|
|
scripts written in the general-purpose <code>ld</code> scripting language.
|
||
|
|
If <var>MRI-cmdfile</var> does not exist, <code>ld</code> looks for it in the directories
|
||
|
|
specified by any ‘<samp>-L</samp>’ options.
|
||
|
|
</p>
|
||
|
|
<a name="index-common-allocation"></a>
|
||
|
|
<a name="index-_002dd"></a>
|
||
|
|
<a name="index-_002ddc"></a>
|
||
|
|
<a name="index-_002ddp"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-d</code></dt>
|
||
|
|
<dt><code>-dc</code></dt>
|
||
|
|
<dt><code>-dp</code></dt>
|
||
|
|
<dd><p>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 ‘<samp>-r</samp>’). The
|
||
|
|
script command <code>FORCE_COMMON_ALLOCATION</code> has the same effect.
|
||
|
|
See <a href="Miscellaneous-Commands.html#Miscellaneous-Commands">Miscellaneous Commands</a>.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002ddepaudit-AUDITLIB"></a>
|
||
|
|
<a name="index-_002dP-AUDITLIB"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--depaudit <var>AUDITLIB</var></code></dt>
|
||
|
|
<dt><code>-P <var>AUDITLIB</var></code></dt>
|
||
|
|
<dd><p>Adds <var>AUDITLIB</var> to the <code>DT_DEPAUDIT</code> entry of the dynamic section.
|
||
|
|
<var>AUDITLIB</var> is not checked for existence, nor will it use the DT_SONAME
|
||
|
|
specified in the library. If specified multiple times <code>DT_DEPAUDIT</code>
|
||
|
|
will contain a colon separated list of audit interfaces to use. This
|
||
|
|
option is only meaningful on ELF platforms supporting the rtld-audit interface.
|
||
|
|
The -P option is provided for Solaris compatibility.
|
||
|
|
</p>
|
||
|
|
<a name="index-entry-point_002c-from-command-line"></a>
|
||
|
|
<a name="index-_002de-entry"></a>
|
||
|
|
<a name="index-_002d_002dentry_003dentry"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-e <var>entry</var></code></dt>
|
||
|
|
<dt><code>--entry=<var>entry</var></code></dt>
|
||
|
|
<dd><p>Use <var>entry</var> as the explicit symbol for beginning execution of your
|
||
|
|
program, rather than the default entry point. If there is no symbol
|
||
|
|
named <var>entry</var>, the linker will try to parse <var>entry</var> as a number,
|
||
|
|
and use that as the entry address (the number will be interpreted in
|
||
|
|
base 10; you may use a leading ‘<samp>0x</samp>’ for base 16, or a leading
|
||
|
|
‘<samp>0</samp>’ for base 8). See <a href="Entry-Point.html#Entry-Point">Entry Point</a>, for a discussion of defaults
|
||
|
|
and other ways of specifying the entry point.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dexclude_002dlibs"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--exclude-libs <var>lib</var>,<var>lib</var>,...</code></dt>
|
||
|
|
<dd><p>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
|
||
|
|
<code>--exclude-libs ALL</code> excludes symbols in all archive libraries from
|
||
|
|
automatic export. This option is available only for the i386 PE targeted
|
||
|
|
port of the linker and for ELF targeted ports. For i386 PE, symbols
|
||
|
|
explicitly listed in a .def file are still exported, regardless of this
|
||
|
|
option. For ELF targeted ports, symbols affected by this option will
|
||
|
|
be treated as hidden.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dexclude_002dmodules_002dfor_002dimplib"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--exclude-modules-for-implib <var>module</var>,<var>module</var>,...</code></dt>
|
||
|
|
<dd><p>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 <code>ld</code> 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 PE targeted port
|
||
|
|
of the linker. Symbols explicitly listed in a .def file are still exported,
|
||
|
|
regardless of this option.
|
||
|
|
</p>
|
||
|
|
<a name="index-dynamic-symbol-table"></a>
|
||
|
|
<a name="index-_002dE"></a>
|
||
|
|
<a name="index-_002d_002dexport_002ddynamic"></a>
|
||
|
|
<a name="index-_002d_002dno_002dexport_002ddynamic"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-E</code></dt>
|
||
|
|
<dt><code>--export-dynamic</code></dt>
|
||
|
|
<dt><code>--no-export-dynamic</code></dt>
|
||
|
|
<dd><p>When creating a dynamically linked executable, using the <samp>-E</samp>
|
||
|
|
option or the <samp>--export-dynamic</samp> 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>
|
||
|
|
<p>If you do not use either of these options (or use the
|
||
|
|
<samp>--no-export-dynamic</samp> 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>
|
||
|
|
<p>If you use <code>dlopen</code> 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>
|
||
|
|
<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 ‘<samp>--dynamic-list</samp>’.
|
||
|
|
</p>
|
||
|
|
<p>Note that this option is specific to ELF targeted ports. PE targets
|
||
|
|
support a similar function to export all symbols from a DLL or EXE; see
|
||
|
|
the description of ‘<samp>--export-all-symbols</samp>’ below.
|
||
|
|
</p>
|
||
|
|
<a name="index-big_002dendian-objects"></a>
|
||
|
|
<a name="index-endianness"></a>
|
||
|
|
<a name="index-_002dEB"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-EB</code></dt>
|
||
|
|
<dd><p>Link big-endian objects. This affects the default output format.
|
||
|
|
</p>
|
||
|
|
<a name="index-little_002dendian-objects"></a>
|
||
|
|
<a name="index-_002dEL"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-EL</code></dt>
|
||
|
|
<dd><p>Link little-endian objects. This affects the default output format.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002df-name"></a>
|
||
|
|
<a name="index-_002d_002dauxiliary_003dname"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-f <var>name</var></code></dt>
|
||
|
|
<dt><code>--auxiliary=<var>name</var></code></dt>
|
||
|
|
<dd><p>When creating an ELF shared object, set the internal DT_AUXILIARY field
|
||
|
|
to the specified name. This tells the dynamic linker that the symbol
|
||
|
|
table of the shared object should be used as an auxiliary filter on the
|
||
|
|
symbol table of the shared object <var>name</var>.
|
||
|
|
</p>
|
||
|
|
<p>If you later link a program against this filter object, then, when you
|
||
|
|
run the program, the dynamic linker will see the DT_AUXILIARY field. If
|
||
|
|
the dynamic linker resolves any symbols from the filter object, it will
|
||
|
|
first check whether there is a definition in the shared object
|
||
|
|
<var>name</var>. If there is one, it will be used instead of the definition
|
||
|
|
in the filter object. The shared object <var>name</var> need not exist.
|
||
|
|
Thus the shared object <var>name</var> may be used to provide an alternative
|
||
|
|
implementation of certain functions, perhaps for debugging or for
|
||
|
|
machine specific performance.
|
||
|
|
</p>
|
||
|
|
<p>This option may be specified more than once. The DT_AUXILIARY entries
|
||
|
|
will be created in the order in which they appear on the command line.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dF-name"></a>
|
||
|
|
<a name="index-_002d_002dfilter_003dname"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-F <var>name</var></code></dt>
|
||
|
|
<dt><code>--filter=<var>name</var></code></dt>
|
||
|
|
<dd><p>When creating an ELF shared object, set the internal DT_FILTER field to
|
||
|
|
the specified name. This tells the dynamic linker that the symbol table
|
||
|
|
of the shared object which is being created should be used as a filter
|
||
|
|
on the symbol table of the shared object <var>name</var>.
|
||
|
|
</p>
|
||
|
|
<p>If you later link a program against this filter object, then, when you
|
||
|
|
run the program, the dynamic linker will see the DT_FILTER field. The
|
||
|
|
dynamic linker will resolve symbols according to the symbol table of the
|
||
|
|
filter object as usual, but it will actually link to the definitions
|
||
|
|
found in the shared object <var>name</var>. Thus the filter object can be
|
||
|
|
used to select a subset of the symbols provided by the object
|
||
|
|
<var>name</var>.
|
||
|
|
</p>
|
||
|
|
<p>Some older linkers used the <samp>-F</samp> option throughout a compilation
|
||
|
|
toolchain for specifying object-file format for both input and output
|
||
|
|
object files.
|
||
|
|
The <small>GNU</small> linker uses other mechanisms for this purpose: the
|
||
|
|
<samp>-b</samp>, <samp>--format</samp>, <samp>--oformat</samp> options, the
|
||
|
|
<code>TARGET</code> command in linker scripts, and the <code>GNUTARGET</code>
|
||
|
|
environment variable.
|
||
|
|
The <small>GNU</small> linker will ignore the <samp>-F</samp> option when not
|
||
|
|
creating an ELF shared object.
|
||
|
|
</p>
|
||
|
|
<a name="index-finalization-function"></a>
|
||
|
|
<a name="index-_002dfini_003dname"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-fini=<var>name</var></code></dt>
|
||
|
|
<dd><p>When creating an ELF executable or shared object, call NAME when the
|
||
|
|
executable or shared object is unloaded, by setting DT_FINI to the
|
||
|
|
address of the function. By default, the linker uses <code>_fini</code> as
|
||
|
|
the function to call.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dg"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-g</code></dt>
|
||
|
|
<dd><p>Ignored. Provided for compatibility with other tools.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dG-value"></a>
|
||
|
|
<a name="index-_002d_002dgpsize_003dvalue"></a>
|
||
|
|
<a name="index-object-size"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-G <var>value</var></code></dt>
|
||
|
|
<dt><code>--gpsize=<var>value</var></code></dt>
|
||
|
|
<dd><p>Set the maximum size of objects to be optimized using the GP register to
|
||
|
|
<var>size</var>. This is only meaningful for object file formats such as
|
||
|
|
MIPS ELF that support putting large and small objects into different
|
||
|
|
sections. This is ignored for other object file formats.
|
||
|
|
</p>
|
||
|
|
<a name="index-runtime-library-name"></a>
|
||
|
|
<a name="index-_002dh-name"></a>
|
||
|
|
<a name="index-_002dsoname_003dname"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-h <var>name</var></code></dt>
|
||
|
|
<dt><code>-soname=<var>name</var></code></dt>
|
||
|
|
<dd><p>When creating an ELF shared object, set the internal DT_SONAME field to
|
||
|
|
the specified name. When an executable is linked with a shared object
|
||
|
|
which has a DT_SONAME field, then when the executable is run the dynamic
|
||
|
|
linker will attempt to load the shared object specified by the DT_SONAME
|
||
|
|
field rather than the using the file name given to the linker.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002di"></a>
|
||
|
|
<a name="index-incremental-link"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-i</code></dt>
|
||
|
|
<dd><p>Perform an incremental link (same as option ‘<samp>-r</samp>’).
|
||
|
|
</p>
|
||
|
|
<a name="index-initialization-function"></a>
|
||
|
|
<a name="index-_002dinit_003dname"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-init=<var>name</var></code></dt>
|
||
|
|
<dd><p>When creating an ELF executable or shared object, call NAME when the
|
||
|
|
executable or shared object is loaded, by setting DT_INIT to the address
|
||
|
|
of the function. By default, the linker uses <code>_init</code> as the
|
||
|
|
function to call.
|
||
|
|
</p>
|
||
|
|
<a name="index-archive-files_002c-from-cmd-line"></a>
|
||
|
|
<a name="index-_002dl-namespec"></a>
|
||
|
|
<a name="index-_002d_002dlibrary_003dnamespec"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-l <var>namespec</var></code></dt>
|
||
|
|
<dt><code>--library=<var>namespec</var></code></dt>
|
||
|
|
<dd><p>Add the archive or object file specified by <var>namespec</var> to the
|
||
|
|
list of files to link. This option may be used any number of times.
|
||
|
|
If <var>namespec</var> is of the form <samp>:<var>filename</var></samp>, <code>ld</code>
|
||
|
|
will search the library path for a file called <var>filename</var>, otherwise it
|
||
|
|
will search the library path for a file called <samp>lib<var>namespec</var>.a</samp>.
|
||
|
|
</p>
|
||
|
|
<p>On systems which support shared libraries, <code>ld</code> may also search for
|
||
|
|
files other than <samp>lib<var>namespec</var>.a</samp>. Specifically, on ELF
|
||
|
|
and SunOS systems, <code>ld</code> will search a directory for a library
|
||
|
|
called <samp>lib<var>namespec</var>.so</samp> before searching for one called
|
||
|
|
<samp>lib<var>namespec</var>.a</samp>. (By convention, a <code>.so</code> extension
|
||
|
|
indicates a shared library.) Note that this behavior does not apply
|
||
|
|
to <samp>:<var>filename</var></samp>, which always specifies a file called
|
||
|
|
<var>filename</var>.
|
||
|
|
</p>
|
||
|
|
<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>
|
||
|
|
<p>See the <samp>-(</samp> option for a way to force the linker to search
|
||
|
|
archives multiple times.
|
||
|
|
</p>
|
||
|
|
<p>You may list the same archive multiple times on the command line.
|
||
|
|
</p>
|
||
|
|
<p>This type of archive searching is standard for Unix linkers. However,
|
||
|
|
if you are using <code>ld</code> on AIX, note that it is different from the
|
||
|
|
behaviour of the AIX linker.
|
||
|
|
</p>
|
||
|
|
<a name="index-search-directory_002c-from-cmd-line"></a>
|
||
|
|
<a name="index-_002dL-dir"></a>
|
||
|
|
<a name="index-_002d_002dlibrary_002dpath_003ddir"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-L <var>searchdir</var></code></dt>
|
||
|
|
<dt><code>--library-path=<var>searchdir</var></code></dt>
|
||
|
|
<dd><p>Add path <var>searchdir</var> to the list of paths that <code>ld</code> will search
|
||
|
|
for archive libraries and <code>ld</code> 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
|
||
|
|
<samp>-L</samp> options apply to all <samp>-l</samp> options, regardless of the
|
||
|
|
order in which the options appear. <samp>-L</samp> options do not affect
|
||
|
|
how <code>ld</code> searches for a linker script unless <samp>-T</samp>
|
||
|
|
option is specified.
|
||
|
|
</p>
|
||
|
|
<p>If <var>searchdir</var> begins with <code>=</code> or <code>$SYSROOT</code>, then this
|
||
|
|
prefix will be replaced by the <em>sysroot prefix</em>, controlled by the
|
||
|
|
‘<samp>--sysroot</samp>’ option, or specified when the linker is configured.
|
||
|
|
</p>
|
||
|
|
<p>The default set of paths searched (without being specified with
|
||
|
|
‘<samp>-L</samp>’) depends on which emulation mode <code>ld</code> is using, and in
|
||
|
|
some cases also on how it was configured. See <a href="Environment.html#Environment">Environment</a>.
|
||
|
|
</p>
|
||
|
|
<p>The paths can also be specified in a link script with the
|
||
|
|
<code>SEARCH_DIR</code> command. Directories specified this way are searched
|
||
|
|
at the point in which the linker script appears in the command line.
|
||
|
|
</p>
|
||
|
|
<a name="index-emulation"></a>
|
||
|
|
<a name="index-_002dm-emulation"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-m <var>emulation</var></code></dt>
|
||
|
|
<dd><p>Emulate the <var>emulation</var> linker. You can list the available
|
||
|
|
emulations with the ‘<samp>--verbose</samp>’ or ‘<samp>-V</samp>’ options.
|
||
|
|
</p>
|
||
|
|
<p>If the ‘<samp>-m</samp>’ option is not used, the emulation is taken from the
|
||
|
|
<code>LDEMULATION</code> environment variable, if that is defined.
|
||
|
|
</p>
|
||
|
|
<p>Otherwise, the default emulation depends upon how the linker was
|
||
|
|
configured.
|
||
|
|
</p>
|
||
|
|
<a name="index-link-map"></a>
|
||
|
|
<a name="index-_002dM"></a>
|
||
|
|
<a name="index-_002d_002dprint_002dmap"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-M</code></dt>
|
||
|
|
<dt><code>--print-map</code></dt>
|
||
|
|
<dd><p>Print a link map to the standard output. A link map provides
|
||
|
|
information about the link, including the following:
|
||
|
|
</p>
|
||
|
|
<ul>
|
||
|
|
<li> Where object files are mapped into memory.
|
||
|
|
</li><li> How common symbols are allocated.
|
||
|
|
</li><li> All archive members included in the link, with a mention of the symbol
|
||
|
|
which caused the archive member to be brought in.
|
||
|
|
</li><li> 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>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample"> foo = 1
|
||
|
|
foo = foo * 4
|
||
|
|
foo = foo + 8
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>will produce the following output in the link map if the <samp>-M</samp>
|
||
|
|
option is used:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample"> 0x00000001 foo = 0x1
|
||
|
|
[0x0000000c] foo = (foo * 0x4)
|
||
|
|
[0x0000000c] foo = (foo + 0x8)
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>See <a href="Expressions.html#Expressions">Expressions</a> for more information about expressions in linker
|
||
|
|
scripts.
|
||
|
|
</p>
|
||
|
|
</li><li> How GNU properties are merged.
|
||
|
|
|
||
|
|
<p>When linker merges input .note.gnu.property sections into one output
|
||
|
|
.note.gnu.property section, some properties are removed or updated,
|
||
|
|
which are reported in the link map as
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">Removed property 0xc0000002 to merge foo.o (0x1) and bar.o (not found)
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>It indicates that property 0xc0000002 is removed from output when
|
||
|
|
merging properties in <samp>foo.o</samp>, whose property 0xc0000002 value
|
||
|
|
is 0x1, and <samp>bar.o</samp>, which doesn’t have property 0xc0000002.
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">Updated property 0xc0000002 (0x1) to merge foo.o (0x1) and bar.o (0x1)
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>It indicates that property 0xc0010001 value is updated to 0x1 in output
|
||
|
|
when merging properties in <samp>foo.o</samp>, whose 0xc0010001 property value
|
||
|
|
is 0x1, and <samp>bar.o</samp>, whose 0xc0010001 property value is 0x1.
|
||
|
|
</p></li></ul>
|
||
|
|
|
||
|
|
<a name="index-_002dn"></a>
|
||
|
|
<a name="index-read_002donly-text"></a>
|
||
|
|
<a name="index-NMAGIC"></a>
|
||
|
|
<a name="index-_002d_002dnmagic"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-n</code></dt>
|
||
|
|
<dt><code>--nmagic</code></dt>
|
||
|
|
<dd><p>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 <code>NMAGIC</code>.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dN"></a>
|
||
|
|
<a name="index-_002d_002domagic"></a>
|
||
|
|
<a name="index-read_002fwrite-from-cmd-line"></a>
|
||
|
|
<a name="index-OMAGIC"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-N</code></dt>
|
||
|
|
<dt><code>--omagic</code></dt>
|
||
|
|
<dd><p>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 <code>OMAGIC</code>. Note: Although a writable text section
|
||
|
|
is allowed for PE-COFF targets, it does not conform to the format
|
||
|
|
specification published by Microsoft.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dno_002domagic"></a>
|
||
|
|
<a name="index-OMAGIC-1"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--no-omagic</code></dt>
|
||
|
|
<dd><p>This option negates most of the effects of the <samp>-N</samp> 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 <samp>-Bdynamic</samp> for this.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002do-output"></a>
|
||
|
|
<a name="index-_002d_002doutput_003doutput"></a>
|
||
|
|
<a name="index-naming-the-output-file"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-o <var>output</var></code></dt>
|
||
|
|
<dt><code>--output=<var>output</var></code></dt>
|
||
|
|
<dd><p>Use <var>output</var> as the name for the program produced by <code>ld</code>; if this
|
||
|
|
option is not specified, the name <samp>a.out</samp> is used by default. The
|
||
|
|
script command <code>OUTPUT</code> can also specify the output file name.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dO-level"></a>
|
||
|
|
<a name="index-generating-optimized-output"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-O <var>level</var></code></dt>
|
||
|
|
<dd><p>If <var>level</var> is a numeric values greater than zero <code>ld</code> 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 ELF 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.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dplugin-name"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-plugin <var>name</var></code></dt>
|
||
|
|
<dd><p>Involve a plugin in the linking process. The <var>name</var> 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>
|
||
|
|
<p>Note that the location of the compiler originated plugins is different
|
||
|
|
from the place where the <code>ar</code>, <code>nm</code> and
|
||
|
|
<code>ranlib</code> 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 <samp>${libdir}/bfd-plugins</samp> directory. All gcc
|
||
|
|
based linker plugins are backward compatible, so it is sufficient to
|
||
|
|
just copy in the newest one.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dpush_002dstate"></a>
|
||
|
|
<a name="index-push-state-governing-input-file-handling"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--push-state</code></dt>
|
||
|
|
<dd><p>The <samp>--push-state</samp> 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 <samp>--pop-state</samp> option.
|
||
|
|
</p>
|
||
|
|
<p>The option which are covered are: <samp>-Bdynamic</samp>, <samp>-Bstatic</samp>,
|
||
|
|
<samp>-dn</samp>, <samp>-dy</samp>, <samp>-call_shared</samp>, <samp>-non_shared</samp>,
|
||
|
|
<samp>-static</samp>, <samp>-N</samp>, <samp>-n</samp>, <samp>--whole-archive</samp>,
|
||
|
|
<samp>--no-whole-archive</samp>, <samp>-r</samp>, <samp>-Ur</samp>,
|
||
|
|
<samp>--copy-dt-needed-entries</samp>, <samp>--no-copy-dt-needed-entries</samp>,
|
||
|
|
<samp>--as-needed</samp>, <samp>--no-as-needed</samp>, and <samp>-a</samp>.
|
||
|
|
</p>
|
||
|
|
<p>One target for this option are specifications for <samp>pkg-config</samp>. When
|
||
|
|
used with the <samp>--libs</samp> option all possibly needed libraries are
|
||
|
|
listed and then possibly linked with all the time. It is better to return
|
||
|
|
something as follows:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">-Wl,--push-state,--as-needed -libone -libtwo -Wl,--pop-state
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<a name="index-_002d_002dpop_002dstate"></a>
|
||
|
|
<a name="index-pop-state-governing-input-file-handling"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--pop-state</code></dt>
|
||
|
|
<dd><p>Undoes the effect of –push-state, restores the previous values of the
|
||
|
|
flags governing input file handling.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dq"></a>
|
||
|
|
<a name="index-_002d_002demit_002drelocs"></a>
|
||
|
|
<a name="index-retain-relocations-in-final-executable"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-q</code></dt>
|
||
|
|
<dt><code>--emit-relocs</code></dt>
|
||
|
|
<dd><p>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>
|
||
|
|
<p>This option is currently only supported on ELF platforms.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dforce_002ddynamic"></a>
|
||
|
|
<a name="index-forcing-the-creation-of-dynamic-sections"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--force-dynamic</code></dt>
|
||
|
|
<dd><p>Force the output file to have dynamic sections. This option is specific
|
||
|
|
to VxWorks targets.
|
||
|
|
</p>
|
||
|
|
<a name="index-partial-link"></a>
|
||
|
|
<a name="index-relocatable-output"></a>
|
||
|
|
<a name="index-_002dr"></a>
|
||
|
|
<a name="index-_002d_002drelocatable"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-r</code></dt>
|
||
|
|
<dt><code>--relocatable</code></dt>
|
||
|
|
<dd><p>Generate relocatable output—i.e., generate an output file that can in
|
||
|
|
turn serve as input to <code>ld</code>. This is often called <em>partial
|
||
|
|
linking</em>. As a side effect, in environments that support standard Unix
|
||
|
|
magic numbers, this option also sets the output file’s magic number to
|
||
|
|
<code>OMAGIC</code>.
|
||
|
|
If this option is not specified, an absolute file is produced. When
|
||
|
|
linking C++ programs, this option <em>will not</em> resolve references to
|
||
|
|
constructors; to do that, use ‘<samp>-Ur</samp>’.
|
||
|
|
</p>
|
||
|
|
<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 <code>a.out</code>-based formats do not support partial linking
|
||
|
|
with input files in other formats at all.
|
||
|
|
</p>
|
||
|
|
<p>This option does the same thing as ‘<samp>-i</samp>’.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dR-file"></a>
|
||
|
|
<a name="index-_002d_002djust_002dsymbols_003dfile"></a>
|
||
|
|
<a name="index-symbol_002donly-input"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-R <var>filename</var></code></dt>
|
||
|
|
<dt><code>--just-symbols=<var>filename</var></code></dt>
|
||
|
|
<dd><p>Read symbol names and their addresses from <var>filename</var>, 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>
|
||
|
|
<p>For compatibility with other ELF linkers, if the <samp>-R</samp> option is
|
||
|
|
followed by a directory name, rather than a file name, it is treated as
|
||
|
|
the <samp>-rpath</samp> option.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002ds"></a>
|
||
|
|
<a name="index-_002d_002dstrip_002dall"></a>
|
||
|
|
<a name="index-strip-all-symbols"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-s</code></dt>
|
||
|
|
<dt><code>--strip-all</code></dt>
|
||
|
|
<dd><p>Omit all symbol information from the output file.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dS"></a>
|
||
|
|
<a name="index-_002d_002dstrip_002ddebug"></a>
|
||
|
|
<a name="index-strip-debugger-symbols"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-S</code></dt>
|
||
|
|
<dt><code>--strip-debug</code></dt>
|
||
|
|
<dd><p>Omit debugger symbol information (but not all symbols) from the output file.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dstrip_002ddiscarded"></a>
|
||
|
|
<a name="index-_002d_002dno_002dstrip_002ddiscarded"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--strip-discarded</code></dt>
|
||
|
|
<dt><code>--no-strip-discarded</code></dt>
|
||
|
|
<dd><p>Omit (or do not omit) global symbols defined in discarded sections.
|
||
|
|
Enabled by default.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dt"></a>
|
||
|
|
<a name="index-_002d_002dtrace"></a>
|
||
|
|
<a name="index-input-files_002c-displaying"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-t</code></dt>
|
||
|
|
<dt><code>--trace</code></dt>
|
||
|
|
<dd><p>Print the names of the input files as <code>ld</code> processes them. If
|
||
|
|
‘<samp>-t</samp>’ is given twice then members within archives are also printed.
|
||
|
|
‘<samp>-t</samp>’ 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.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dT-script"></a>
|
||
|
|
<a name="index-_002d_002dscript_003dscript"></a>
|
||
|
|
<a name="index-script-files"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-T <var>scriptfile</var></code></dt>
|
||
|
|
<dt><code>--script=<var>scriptfile</var></code></dt>
|
||
|
|
<dd><p>Use <var>scriptfile</var> as the linker script. This script replaces
|
||
|
|
<code>ld</code>’s default linker script (rather than adding to it), so
|
||
|
|
<var>commandfile</var> must specify everything necessary to describe the
|
||
|
|
output file. See <a href="Scripts.html#Scripts">Scripts</a>. If <var>scriptfile</var> does not exist in
|
||
|
|
the current directory, <code>ld</code> looks for it in the directories
|
||
|
|
specified by any preceding ‘<samp>-L</samp>’ options. Multiple ‘<samp>-T</samp>’
|
||
|
|
options accumulate.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002ddT-script"></a>
|
||
|
|
<a name="index-_002d_002ddefault_002dscript_003dscript"></a>
|
||
|
|
<a name="index-script-files-1"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-dT <var>scriptfile</var></code></dt>
|
||
|
|
<dt><code>--default-script=<var>scriptfile</var></code></dt>
|
||
|
|
<dd><p>Use <var>scriptfile</var> as the default linker script. See <a href="Scripts.html#Scripts">Scripts</a>.
|
||
|
|
</p>
|
||
|
|
<p>This option is similar to the <samp>--script</samp> 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
|
||
|
|
<samp>--default-script</samp> 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
|
||
|
|
‘<samp>gcc</samp>’).
|
||
|
|
</p>
|
||
|
|
<a name="index-_002du-symbol"></a>
|
||
|
|
<a name="index-_002d_002dundefined_003dsymbol"></a>
|
||
|
|
<a name="index-undefined-symbol"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-u <var>symbol</var></code></dt>
|
||
|
|
<dt><code>--undefined=<var>symbol</var></code></dt>
|
||
|
|
<dd><p>Force <var>symbol</var> to be entered in the output file as an undefined
|
||
|
|
symbol. Doing this may, for example, trigger linking of additional
|
||
|
|
modules from standard libraries. ‘<samp>-u</samp>’ may be repeated with
|
||
|
|
different option arguments to enter additional undefined symbols. This
|
||
|
|
option is equivalent to the <code>EXTERN</code> linker script command.
|
||
|
|
</p>
|
||
|
|
<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 <samp>--require-defined</samp> should be used
|
||
|
|
instead.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002drequire_002ddefined_003dsymbol"></a>
|
||
|
|
<a name="index-symbols_002c-require-defined"></a>
|
||
|
|
<a name="index-defined-symbol"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--require-defined=<var>symbol</var></code></dt>
|
||
|
|
<dd><p>Require that <var>symbol</var> is defined in the output file. This option
|
||
|
|
is the same as option <samp>--undefined</samp> except that if <var>symbol</var>
|
||
|
|
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
|
||
|
|
<code>EXTERN</code>, <code>ASSERT</code> and <code>DEFINED</code> together. This option
|
||
|
|
can be used multiple times to require additional symbols.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dUr"></a>
|
||
|
|
<a name="index-constructors"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-Ur</code></dt>
|
||
|
|
<dd><p>For anything other than C++ programs, this option is equivalent to
|
||
|
|
‘<samp>-r</samp>’: it generates relocatable output—i.e., an output file that can in
|
||
|
|
turn serve as input to <code>ld</code>. When linking C++ programs, ‘<samp>-Ur</samp>’
|
||
|
|
<em>does</em> resolve references to constructors, unlike ‘<samp>-r</samp>’.
|
||
|
|
It does not work to use ‘<samp>-Ur</samp>’ on files that were themselves linked
|
||
|
|
with ‘<samp>-Ur</samp>’; once the constructor table has been built, it cannot
|
||
|
|
be added to. Use ‘<samp>-Ur</samp>’ only for the last partial link, and
|
||
|
|
‘<samp>-r</samp>’ for the others.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dorphan_002dhandling_003dMODE"></a>
|
||
|
|
<a name="index-orphan-sections"></a>
|
||
|
|
<a name="index-sections_002c-orphan"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--orphan-handling=<var>MODE</var></code></dt>
|
||
|
|
<dd><p>Control how orphan sections are handled. An orphan section is one not
|
||
|
|
specifically mentioned in a linker script. See <a href="Orphan-Sections.html#Orphan-Sections">Orphan Sections</a>.
|
||
|
|
</p>
|
||
|
|
<p><var>MODE</var> can have any of the following values:
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dt><code>place</code></dt>
|
||
|
|
<dd><p>Orphan sections are placed into a suitable output section following
|
||
|
|
the strategy described in <a href="Orphan-Sections.html#Orphan-Sections">Orphan Sections</a>. The option
|
||
|
|
‘<samp>--unique</samp>’ also affects how sections are placed.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>discard</code></dt>
|
||
|
|
<dd><p>All orphan sections are discarded, by placing them in the
|
||
|
|
‘<samp>/DISCARD/</samp>’ section (see <a href="Output-Section-Discarding.html#Output-Section-Discarding">Output Section Discarding</a>).
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>warn</code></dt>
|
||
|
|
<dd><p>The linker will place the orphan section as for <code>place</code> and also
|
||
|
|
issue a warning.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>error</code></dt>
|
||
|
|
<dd><p>The linker will exit with an error if any orphan section is found.
|
||
|
|
</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>The default if ‘<samp>--orphan-handling</samp>’ is not given is <code>place</code>.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dunique_005b_003dSECTION_005d"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--unique[=<var>SECTION</var>]</code></dt>
|
||
|
|
<dd><p>Creates a separate output section for every input section matching
|
||
|
|
<var>SECTION</var>, or if the optional wildcard <var>SECTION</var> 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.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dv"></a>
|
||
|
|
<a name="index-_002dV"></a>
|
||
|
|
<a name="index-_002d_002dversion"></a>
|
||
|
|
<a name="index-version"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-v</code></dt>
|
||
|
|
<dt><code>--version</code></dt>
|
||
|
|
<dt><code>-V</code></dt>
|
||
|
|
<dd><p>Display the version number for <code>ld</code>. The <samp>-V</samp> option also
|
||
|
|
lists the supported emulations.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dx"></a>
|
||
|
|
<a name="index-_002d_002ddiscard_002dall"></a>
|
||
|
|
<a name="index-deleting-local-symbols"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-x</code></dt>
|
||
|
|
<dt><code>--discard-all</code></dt>
|
||
|
|
<dd><p>Delete all local symbols.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dX"></a>
|
||
|
|
<a name="index-_002d_002ddiscard_002dlocals"></a>
|
||
|
|
<a name="index-local-symbols_002c-deleting"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-X</code></dt>
|
||
|
|
<dt><code>--discard-locals</code></dt>
|
||
|
|
<dd><p>Delete all temporary local symbols. (These symbols start with
|
||
|
|
system-specific local label prefixes, typically ‘<samp>.L</samp>’ for ELF systems
|
||
|
|
or ‘<samp>L</samp>’ for traditional a.out systems.)
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dy-symbol"></a>
|
||
|
|
<a name="index-_002d_002dtrace_002dsymbol_003dsymbol"></a>
|
||
|
|
<a name="index-symbol-tracing"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-y <var>symbol</var></code></dt>
|
||
|
|
<dt><code>--trace-symbol=<var>symbol</var></code></dt>
|
||
|
|
<dd><p>Print the name of each linked file in which <var>symbol</var> appears. This
|
||
|
|
option may be given any number of times. On many systems it is necessary
|
||
|
|
to prepend an underscore.
|
||
|
|
</p>
|
||
|
|
<p>This option is useful when you have an undefined symbol in your link but
|
||
|
|
don’t know where the reference is coming from.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dY-path"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-Y <var>path</var></code></dt>
|
||
|
|
<dd><p>Add <var>path</var> to the default library search path. This option exists
|
||
|
|
for Solaris compatibility.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dz-keyword"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-z <var>keyword</var></code></dt>
|
||
|
|
<dd><p>The recognized keywords are:
|
||
|
|
</p><dl compact="compact">
|
||
|
|
<dt>‘<samp>bndplt</samp>’</dt>
|
||
|
|
<dd><p>Always generate BND prefix in PLT entries. Supported for Linux/x86_64.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>call-nop=prefix-addr</samp>’</dt>
|
||
|
|
<dt>‘<samp>call-nop=suffix-nop</samp>’</dt>
|
||
|
|
<dt>‘<samp>call-nop=prefix-<var>byte</var></samp>’</dt>
|
||
|
|
<dt>‘<samp>call-nop=suffix-<var>byte</var></samp>’</dt>
|
||
|
|
<dd><p>Specify the 1-byte <code>NOP</code> padding when transforming indirect call
|
||
|
|
to a locally defined function, foo, via its GOT slot.
|
||
|
|
<samp>call-nop=prefix-addr</samp> generates <code>0x67 call foo</code>.
|
||
|
|
<samp>call-nop=suffix-nop</samp> generates <code>call foo 0x90</code>.
|
||
|
|
<samp>call-nop=prefix-<var>byte</var></samp> generates <code><var>byte</var> call foo</code>.
|
||
|
|
<samp>call-nop=suffix-<var>byte</var></samp> generates <code>call foo <var>byte</var></code>.
|
||
|
|
Supported for i386 and x86_64.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>combreloc</samp>’</dt>
|
||
|
|
<dt>‘<samp>nocombreloc</samp>’</dt>
|
||
|
|
<dd><p>Combine multiple dynamic relocation sections and sort to improve
|
||
|
|
dynamic symbol lookup caching. Do not do this if ‘<samp>nocombreloc</samp>’.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>common</samp>’</dt>
|
||
|
|
<dt>‘<samp>nocommon</samp>’</dt>
|
||
|
|
<dd><p>Generate common symbols with STT_COMMON type during a relocatable
|
||
|
|
link. Use STT_OBJECT type if ‘<samp>nocommon</samp>’.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>common-page-size=<var>value</var></samp>’</dt>
|
||
|
|
<dd><p>Set the page size most commonly used to <var>value</var>. Memory image
|
||
|
|
layout will be optimized to minimize memory pages if the system is
|
||
|
|
using pages of this size.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>defs</samp>’</dt>
|
||
|
|
<dd><p>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 ‘<samp>-z undefs</samp>’.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>dynamic-undefined-weak</samp>’</dt>
|
||
|
|
<dt>‘<samp>nodynamic-undefined-weak</samp>’</dt>
|
||
|
|
<dd><p>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
|
||
|
|
‘<samp>nodynamic-undefined-weak</samp>’. 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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>execstack</samp>’</dt>
|
||
|
|
<dd><p>Marks the object as requiring executable stack.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>global</samp>’</dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>globalaudit</samp>’</dt>
|
||
|
|
<dd><p>This option is only meaningful when building a dynamic executable.
|
||
|
|
This option marks the executable as requiring global auditing by
|
||
|
|
setting the <code>DF_1_GLOBAUDIT</code> bit in the <code>DT_FLAGS_1</code> dynamic
|
||
|
|
tag. Global auditing requires that any auditing library defined via
|
||
|
|
the <samp>--depaudit</samp> or <samp>-P</samp> command-line options be run for
|
||
|
|
all dynamic objects loaded by the application.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>ibtplt</samp>’</dt>
|
||
|
|
<dd><p>Generate Intel Indirect Branch Tracking (IBT) enabled PLT entries.
|
||
|
|
Supported for Linux/i386 and Linux/x86_64.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>ibt</samp>’</dt>
|
||
|
|
<dd><p>Generate GNU_PROPERTY_X86_FEATURE_1_IBT in .note.gnu.property section
|
||
|
|
to indicate compatibility with IBT. This also implies <samp>ibtplt</samp>.
|
||
|
|
Supported for Linux/i386 and Linux/x86_64.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>initfirst</samp>’</dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>interpose</samp>’</dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>lazy</samp>’</dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>loadfltr</samp>’</dt>
|
||
|
|
<dd><p>Specify that the object’s filters be processed immediately at runtime.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>max-page-size=<var>value</var></samp>’</dt>
|
||
|
|
<dd><p>Set the maximum memory page size supported to <var>value</var>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>muldefs</samp>’</dt>
|
||
|
|
<dd><p>Allow multiple definitions.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>nocopyreloc</samp>’</dt>
|
||
|
|
<dd><p>Disable linker generated .dynbss variables used in place of variables
|
||
|
|
defined in shared libraries. May result in dynamic text relocations.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>nodefaultlib</samp>’</dt>
|
||
|
|
<dd><p>Specify that the dynamic loader search for dependencies of this object
|
||
|
|
should ignore any default library search paths.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>nodelete</samp>’</dt>
|
||
|
|
<dd><p>Specify that the object shouldn’t be unloaded at runtime.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>nodlopen</samp>’</dt>
|
||
|
|
<dd><p>Specify that the object is not available to <code>dlopen</code>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>nodump</samp>’</dt>
|
||
|
|
<dd><p>Specify that the object can not be dumped by <code>dldump</code>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>noexecstack</samp>’</dt>
|
||
|
|
<dd><p>Marks the object as not requiring executable stack.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>noextern-protected-data</samp>’</dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>noreloc-overflow</samp>’</dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>now</samp>’</dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>origin</samp>’</dt>
|
||
|
|
<dd><p>Specify that the object requires ‘<samp>$ORIGIN</samp>’ handling in paths.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>relro</samp>’</dt>
|
||
|
|
<dt>‘<samp>norelro</samp>’</dt>
|
||
|
|
<dd><p>Create an ELF <code>PT_GNU_RELRO</code> segment header in the object. This
|
||
|
|
specifies a memory segment that should be made read-only after
|
||
|
|
relocation, if supported. Specifying ‘<samp>common-page-size</samp>’ smaller
|
||
|
|
than the system page size will render this protection ineffective.
|
||
|
|
Don’t create an ELF <code>PT_GNU_RELRO</code> segment if ‘<samp>norelro</samp>’.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>separate-code</samp>’</dt>
|
||
|
|
<dt>‘<samp>noseparate-code</samp>’</dt>
|
||
|
|
<dd><p>Create separate code <code>PT_LOAD</code> 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 <code>PT_LOAD</code> segment if ‘<samp>noseparate-code</samp>’ is used.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>shstk</samp>’</dt>
|
||
|
|
<dd><p>Generate GNU_PROPERTY_X86_FEATURE_1_SHSTK in .note.gnu.property section
|
||
|
|
to indicate compatibility with Intel Shadow Stack. Supported for
|
||
|
|
Linux/i386 and Linux/x86_64.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>stack-size=<var>value</var></samp>’</dt>
|
||
|
|
<dd><p>Specify a stack size for an ELF <code>PT_GNU_STACK</code> segment.
|
||
|
|
Specifying zero will override any default non-zero sized
|
||
|
|
<code>PT_GNU_STACK</code> segment creation.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>text</samp>’</dt>
|
||
|
|
<dt>‘<samp>notext</samp>’</dt>
|
||
|
|
<dt>‘<samp>textoff</samp>’</dt>
|
||
|
|
<dd><p>Report an error if DT_TEXTREL is set, i.e., if the binary has dynamic
|
||
|
|
relocations in read-only sections. Don’t report an error if
|
||
|
|
‘<samp>notext</samp>’ or ‘<samp>textoff</samp>’.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>undefs</samp>’</dt>
|
||
|
|
<dd><p>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 ‘<samp>-z defs</samp>’.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>Other keywords are ignored for Solaris compatibility.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_0028"></a>
|
||
|
|
<a name="index-groups-of-archives"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-( <var>archives</var> -)</code></dt>
|
||
|
|
<dt><code>--start-group <var>archives</var> --end-group</code></dt>
|
||
|
|
<dd><p>The <var>archives</var> should be a list of archive files. They may be
|
||
|
|
either explicit file names, or ‘<samp>-l</samp>’ options.
|
||
|
|
</p>
|
||
|
|
<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 all be searched repeatedly until all possible references are
|
||
|
|
resolved.
|
||
|
|
</p>
|
||
|
|
<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.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002daccept_002dunknown_002dinput_002darch"></a>
|
||
|
|
<a name="index-_002d_002dno_002daccept_002dunknown_002dinput_002darch"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--accept-unknown-input-arch</code></dt>
|
||
|
|
<dt><code>--no-accept-unknown-input-arch</code></dt>
|
||
|
|
<dd><p>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 ‘<samp>--accept-unknown-input-arch</samp>’ option has been added to
|
||
|
|
restore the old behaviour.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002das_002dneeded"></a>
|
||
|
|
<a name="index-_002d_002dno_002das_002dneeded"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--as-needed</code></dt>
|
||
|
|
<dt><code>--no-as-needed</code></dt>
|
||
|
|
<dd><p>This option affects ELF DT_NEEDED tags for dynamic libraries mentioned
|
||
|
|
on the command line after the <samp>--as-needed</samp> option. Normally
|
||
|
|
the linker will add a DT_NEEDED tag for each dynamic library mentioned
|
||
|
|
on the command line, regardless of whether the library is actually
|
||
|
|
needed or not. <samp>--as-needed</samp> causes a DT_NEEDED tag to only be
|
||
|
|
emitted for a library that <em>at that point in the link</em> satisfies a
|
||
|
|
non-weak undefined symbol reference from a regular object file or, if
|
||
|
|
the library is not found in the DT_NEEDED 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 <em>after</em>
|
||
|
|
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. <samp>--no-as-needed</samp> restores the default behaviour.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dadd_002dneeded"></a>
|
||
|
|
<a name="index-_002d_002dno_002dadd_002dneeded"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--add-needed</code></dt>
|
||
|
|
<dt><code>--no-add-needed</code></dt>
|
||
|
|
<dd><p>These two options have been deprecated because of the similarity of
|
||
|
|
their names to the <samp>--as-needed</samp> and <samp>--no-as-needed</samp>
|
||
|
|
options. They have been replaced by <samp>--copy-dt-needed-entries</samp>
|
||
|
|
and <samp>--no-copy-dt-needed-entries</samp>.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dassert-keyword"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-assert <var>keyword</var></code></dt>
|
||
|
|
<dd><p>This option is ignored for SunOS compatibility.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dBdynamic"></a>
|
||
|
|
<a name="index-_002ddy"></a>
|
||
|
|
<a name="index-_002dcall_005fshared"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-Bdynamic</code></dt>
|
||
|
|
<dt><code>-dy</code></dt>
|
||
|
|
<dt><code>-call_shared</code></dt>
|
||
|
|
<dd><p>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
|
||
|
|
<samp>-l</samp> options which follow it.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dBgroup"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-Bgroup</code></dt>
|
||
|
|
<dd><p>Set the <code>DF_1_GROUP</code> flag in the <code>DT_FLAGS_1</code> 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.
|
||
|
|
<samp>--unresolved-symbols=report-all</samp> is implied. This option is
|
||
|
|
only meaningful on ELF platforms which support shared libraries.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dBstatic"></a>
|
||
|
|
<a name="index-_002ddn"></a>
|
||
|
|
<a name="index-_002dnon_005fshared"></a>
|
||
|
|
<a name="index-_002dstatic"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-Bstatic</code></dt>
|
||
|
|
<dt><code>-dn</code></dt>
|
||
|
|
<dt><code>-non_shared</code></dt>
|
||
|
|
<dt><code>-static</code></dt>
|
||
|
|
<dd><p>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 <samp>-l</samp> options which follow it. This
|
||
|
|
option also implies <samp>--unresolved-symbols=report-all</samp>. This
|
||
|
|
option can be used with <samp>-shared</samp>. 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.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dBsymbolic"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-Bsymbolic</code></dt>
|
||
|
|
<dd><p>When creating a shared library, bind references to global symbols to the
|
||
|
|
definition within the shared library, if any. Normally, it is possible
|
||
|
|
for a program linked against a shared library to override the definition
|
||
|
|
within the shared library. This option can also be used with the
|
||
|
|
<samp>--export-dynamic</samp> option, when creating a position independent
|
||
|
|
executable, to bind references to global symbols to the definition within
|
||
|
|
the executable. This option is only meaningful on ELF platforms which
|
||
|
|
support shared libraries and position independent executables.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dBsymbolic_002dfunctions"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-Bsymbolic-functions</code></dt>
|
||
|
|
<dd><p>When creating a shared library, bind references to global function
|
||
|
|
symbols to the definition within the shared library, if any.
|
||
|
|
This option can also be used with the <samp>--export-dynamic</samp> option,
|
||
|
|
when creating a position independent executable, to bind references
|
||
|
|
to global function symbols to the definition within the executable.
|
||
|
|
This option is only meaningful on ELF platforms which support shared
|
||
|
|
libraries and position independent executables.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002ddynamic_002dlist_003ddynamic_002dlist_002dfile"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--dynamic-list=<var>dynamic-list-file</var></code></dt>
|
||
|
|
<dd><p>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 ELF platforms
|
||
|
|
which support shared libraries.
|
||
|
|
</p>
|
||
|
|
<p>The format of the dynamic list is the same as the version node without
|
||
|
|
scope and node name. See <a href="VERSION.html#VERSION">VERSION</a> for more information.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002ddynamic_002dlist_002ddata"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--dynamic-list-data</code></dt>
|
||
|
|
<dd><p>Include all global data symbols to the dynamic list.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002ddynamic_002dlist_002dcpp_002dnew"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--dynamic-list-cpp-new</code></dt>
|
||
|
|
<dd><p>Provide the builtin dynamic list for C++ operator new and delete. It
|
||
|
|
is mainly useful for building shared libstdc++.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002ddynamic_002dlist_002dcpp_002dtypeinfo"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--dynamic-list-cpp-typeinfo</code></dt>
|
||
|
|
<dd><p>Provide the builtin dynamic list for C++ runtime type identification.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dcheck_002dsections"></a>
|
||
|
|
<a name="index-_002d_002dno_002dcheck_002dsections"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--check-sections</code></dt>
|
||
|
|
<dt><code>--no-check-sections</code></dt>
|
||
|
|
<dd><p>Asks the linker <em>not</em> 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 <samp>--check-sections</samp>.
|
||
|
|
Section overlap is not usually checked for relocatable links. You can
|
||
|
|
force checking in that case by using the <samp>--check-sections</samp>
|
||
|
|
option.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dcopy_002ddt_002dneeded_002dentries"></a>
|
||
|
|
<a name="index-_002d_002dno_002dcopy_002ddt_002dneeded_002dentries"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--copy-dt-needed-entries</code></dt>
|
||
|
|
<dt><code>--no-copy-dt-needed-entries</code></dt>
|
||
|
|
<dd><p>This option affects the treatment of dynamic libraries referred to
|
||
|
|
by DT_NEEDED tags <em>inside</em> ELF dynamic libraries mentioned on the
|
||
|
|
command line. Normally the linker won’t add a DT_NEEDED tag to the
|
||
|
|
output binary for each library mentioned in a DT_NEEDED tag in an
|
||
|
|
input dynamic library. With <samp>--copy-dt-needed-entries</samp>
|
||
|
|
specified on the command line however any dynamic libraries that
|
||
|
|
follow it will have their DT_NEEDED entries added. The default
|
||
|
|
behaviour can be restored with <samp>--no-copy-dt-needed-entries</samp>.
|
||
|
|
</p>
|
||
|
|
<p>This option also has an effect on the resolution of symbols in dynamic
|
||
|
|
libraries. With <samp>--copy-dt-needed-entries</samp> dynamic libraries
|
||
|
|
mentioned on the command line will be recursively searched, following
|
||
|
|
their DT_NEEDED 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 DT_NEEDED links will be traversed to resolve
|
||
|
|
symbols.
|
||
|
|
</p>
|
||
|
|
<a name="index-cross-reference-table"></a>
|
||
|
|
<a name="index-_002d_002dcref"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--cref</code></dt>
|
||
|
|
<dd><p>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>
|
||
|
|
<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.
|
||
|
|
</p>
|
||
|
|
<a name="index-common-allocation-1"></a>
|
||
|
|
<a name="index-_002d_002dno_002ddefine_002dcommon"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--no-define-common</code></dt>
|
||
|
|
<dd><p>This option inhibits the assignment of addresses to common symbols.
|
||
|
|
The script command <code>INHIBIT_COMMON_ALLOCATION</code> has the same effect.
|
||
|
|
See <a href="Miscellaneous-Commands.html#Miscellaneous-Commands">Miscellaneous Commands</a>.
|
||
|
|
</p>
|
||
|
|
<p>The ‘<samp>--no-define-common</samp>’ 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 ‘<samp>--no-define-common</samp>’ 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.
|
||
|
|
</p>
|
||
|
|
<a name="index-group-allocation-in-linker-script"></a>
|
||
|
|
<a name="index-section-groups"></a>
|
||
|
|
<a name="index-COMDAT"></a>
|
||
|
|
<a name="index-_002d_002dforce_002dgroup_002dallocation"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--force-group-allocation</code></dt>
|
||
|
|
<dd><p>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 (‘<samp>-r</samp>’). The script
|
||
|
|
command <code>FORCE_GROUP_ALLOCATION</code> has the same
|
||
|
|
effect. See <a href="Miscellaneous-Commands.html#Miscellaneous-Commands">Miscellaneous Commands</a>.
|
||
|
|
</p>
|
||
|
|
<a name="index-symbols_002c-from-command-line"></a>
|
||
|
|
<a name="index-_002d_002ddefsym_003dsymbol_003dexp"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--defsym=<var>symbol</var>=<var>expression</var></code></dt>
|
||
|
|
<dd><p>Create a global symbol in the output file, containing the absolute
|
||
|
|
address given by <var>expression</var>. 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 <var>expression</var> in this
|
||
|
|
context: you may give a hexadecimal constant or the name of an existing
|
||
|
|
symbol, or use <code>+</code> and <code>-</code> to add or subtract hexadecimal
|
||
|
|
constants or symbols. If you need more elaborate expressions, consider
|
||
|
|
using the linker command language from a script (see <a href="Assignments.html#Assignments">Assignments</a>).
|
||
|
|
<em>Note:</em> there should be no white space between <var>symbol</var>, the
|
||
|
|
equals sign (“<tt class="key">=</tt>”), and <var>expression</var>.
|
||
|
|
</p>
|
||
|
|
<a name="index-demangling_002c-from-command-line"></a>
|
||
|
|
<a name="index-_002d_002ddemangle_005b_003dstyle_005d"></a>
|
||
|
|
<a name="index-_002d_002dno_002ddemangle"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--demangle[=<var>style</var>]</code></dt>
|
||
|
|
<dt><code>--no-demangle</code></dt>
|
||
|
|
<dd><p>These options control whether to demangle symbol names in error messages
|
||
|
|
and other output. When the linker is told to demangle, it tries to
|
||
|
|
present symbol names in a readable fashion: it strips leading
|
||
|
|
underscores if they are used by the object file format, and converts C++
|
||
|
|
mangled symbol names into user readable names. Different compilers have
|
||
|
|
different mangling styles. The optional demangling style argument can be used
|
||
|
|
to choose an appropriate demangling style for your compiler. The linker will
|
||
|
|
demangle by default unless the environment variable ‘<samp>COLLECT_NO_DEMANGLE</samp>’
|
||
|
|
is set. These options may be used to override the default.
|
||
|
|
</p>
|
||
|
|
<a name="index-dynamic-linker_002c-from-command-line"></a>
|
||
|
|
<a name="index-_002dIfile"></a>
|
||
|
|
<a name="index-_002d_002ddynamic_002dlinker_003dfile"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-I<var>file</var></code></dt>
|
||
|
|
<dt><code>--dynamic-linker=<var>file</var></code></dt>
|
||
|
|
<dd><p>Set the name of the dynamic linker. This is only meaningful when
|
||
|
|
generating dynamically linked ELF executables. The default dynamic
|
||
|
|
linker is normally correct; don’t use this unless you know what you are
|
||
|
|
doing.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dno_002ddynamic_002dlinker"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--no-dynamic-linker</code></dt>
|
||
|
|
<dd><p>When producing an executable file, omit the request for a dynamic
|
||
|
|
linker to be used at load-time. This is only meaningful for ELF
|
||
|
|
executables that contain dynamic relocations, and usually requires
|
||
|
|
entry point code that is capable of processing these relocations.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dembedded_002drelocs"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--embedded-relocs</code></dt>
|
||
|
|
<dd><p>This option is similar to the <samp>--emit-relocs</samp> option except
|
||
|
|
that the relocs are stored in a target specific section. This option
|
||
|
|
is only supported by the ‘<samp>BFIN</samp>’, ‘<samp>CR16</samp>’ and <em>M68K</em>
|
||
|
|
targets.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002ddisable_002dmultiple_002dabs_002ddefs"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--disable-multiple-abs-defs</code></dt>
|
||
|
|
<dd><p>Do not allow multiple definitions with symbols included
|
||
|
|
in filename invoked by -R or –just-symbols
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dfatal_002dwarnings"></a>
|
||
|
|
<a name="index-_002d_002dno_002dfatal_002dwarnings"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--fatal-warnings</code></dt>
|
||
|
|
<dt><code>--no-fatal-warnings</code></dt>
|
||
|
|
<dd><p>Treat all warnings as errors. The default behaviour can be restored
|
||
|
|
with the option <samp>--no-fatal-warnings</samp>.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dforce_002dexe_002dsuffix"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--force-exe-suffix</code></dt>
|
||
|
|
<dd><p>Make sure that an output file has a .exe suffix.
|
||
|
|
</p>
|
||
|
|
<p>If a successfully built fully linked output file does not have a
|
||
|
|
<code>.exe</code> or <code>.dll</code> suffix, this option forces the linker to copy
|
||
|
|
the output file to one of the same name with a <code>.exe</code> 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 <code>.exe</code> suffix.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dgc_002dsections"></a>
|
||
|
|
<a name="index-_002d_002dno_002dgc_002dsections"></a>
|
||
|
|
<a name="index-garbage-collection"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--gc-sections</code></dt>
|
||
|
|
<dt><code>--no-gc-sections</code></dt>
|
||
|
|
<dd><p>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
|
||
|
|
‘<samp>--no-gc-sections</samp>’ on the command line. Note that garbage
|
||
|
|
collection for COFF and PE format targets is supported, but the
|
||
|
|
implementation is currently considered to be experimental.
|
||
|
|
</p>
|
||
|
|
<p>‘<samp>--gc-sections</samp>’ 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 ‘<samp>--entry</samp>’, ‘<samp>--undefined</samp>’, and
|
||
|
|
‘<samp>--gc-keep-exported</samp>’.
|
||
|
|
</p>
|
||
|
|
<p>This option can be set when doing a partial link (enabled with option
|
||
|
|
‘<samp>-r</samp>’). In this case the root of symbols kept must be explicitly
|
||
|
|
specified either by one of the options ‘<samp>--entry</samp>’,
|
||
|
|
‘<samp>--undefined</samp>’, or ‘<samp>--gc-keep-exported</samp>’ or by a <code>ENTRY</code>
|
||
|
|
command in the linker script.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dprint_002dgc_002dsections"></a>
|
||
|
|
<a name="index-_002d_002dno_002dprint_002dgc_002dsections"></a>
|
||
|
|
<a name="index-garbage-collection-1"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--print-gc-sections</code></dt>
|
||
|
|
<dt><code>--no-print-gc-sections</code></dt>
|
||
|
|
<dd><p>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 ‘<samp>--gc-sections</samp>’) option. The
|
||
|
|
default behaviour (of not listing the sections that are removed) can
|
||
|
|
be restored by specifying ‘<samp>--no-print-gc-sections</samp>’ on the command
|
||
|
|
line.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dgc_002dkeep_002dexported"></a>
|
||
|
|
<a name="index-garbage-collection-2"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--gc-keep-exported</code></dt>
|
||
|
|
<dd><p>When ‘<samp>--gc-sections</samp>’ 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
|
||
|
|
ELF format targets.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dprint_002doutput_002dformat"></a>
|
||
|
|
<a name="index-output-format"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--print-output-format</code></dt>
|
||
|
|
<dd><p>Print the name of the default output format (perhaps influenced by
|
||
|
|
other command-line options). This is the string that would appear
|
||
|
|
in an <code>OUTPUT_FORMAT</code> linker script command (see <a href="File-Commands.html#File-Commands">File Commands</a>).
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dprint_002dmemory_002dusage"></a>
|
||
|
|
<a name="index-memory-usage"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--print-memory-usage</code></dt>
|
||
|
|
<dd><p>Print used size, total size and used size of memory regions created with
|
||
|
|
the <a href="MEMORY.html#MEMORY">MEMORY</a> 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>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">Memory region Used Size Region Size %age Used
|
||
|
|
ROM: 256 KB 1 MB 25.00%
|
||
|
|
RAM: 32 B 2 GB 0.00%
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<a name="index-help"></a>
|
||
|
|
<a name="index-usage"></a>
|
||
|
|
<a name="index-_002d_002dhelp"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--help</code></dt>
|
||
|
|
<dd><p>Print a summary of the command-line options on the standard output and exit.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dtarget_002dhelp"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--target-help</code></dt>
|
||
|
|
<dd><p>Print a summary of all target specific options on the standard output and exit.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dMap_003dmapfile"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-Map=<var>mapfile</var></code></dt>
|
||
|
|
<dd><p>Print a link map to the file <var>mapfile</var>. See the description of the
|
||
|
|
<samp>-M</samp> option, above.
|
||
|
|
</p>
|
||
|
|
<a name="index-memory-usage-1"></a>
|
||
|
|
<a name="index-_002d_002dno_002dkeep_002dmemory"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--no-keep-memory</code></dt>
|
||
|
|
<dd><p><code>ld</code> normally optimizes for speed over memory usage by caching the
|
||
|
|
symbol tables of input files in memory. This option tells <code>ld</code> to
|
||
|
|
instead optimize for memory usage, by rereading the symbol tables as
|
||
|
|
necessary. This may be required if <code>ld</code> runs out of memory space
|
||
|
|
while linking a large executable.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dno_002dundefined"></a>
|
||
|
|
<a name="index-_002dz-defs"></a>
|
||
|
|
<a name="index-_002dz-undefs"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--no-undefined</code></dt>
|
||
|
|
<dt><code>-z defs</code></dt>
|
||
|
|
<dd><p>Report unresolved symbol references from regular object files. This
|
||
|
|
is done even if the linker is creating a non-symbolic shared library.
|
||
|
|
The switch <samp>--[no-]allow-shlib-undefined</samp> controls the
|
||
|
|
behaviour for reporting unresolved references found in shared
|
||
|
|
libraries being linked in.
|
||
|
|
</p>
|
||
|
|
<p>The effects of this option can be reverted by using <code>-z undefs</code>.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dallow_002dmultiple_002ddefinition"></a>
|
||
|
|
<a name="index-_002dz-muldefs"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--allow-multiple-definition</code></dt>
|
||
|
|
<dt><code>-z muldefs</code></dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dallow_002dshlib_002dundefined"></a>
|
||
|
|
<a name="index-_002d_002dno_002dallow_002dshlib_002dundefined"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--allow-shlib-undefined</code></dt>
|
||
|
|
<dt><code>--no-allow-shlib-undefined</code></dt>
|
||
|
|
<dd><p>Allows or disallows undefined symbols in shared libraries.
|
||
|
|
This switch is similar to <samp>--no-undefined</samp> 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>
|
||
|
|
<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>
|
||
|
|
<p>The reasons for allowing undefined symbol references in shared
|
||
|
|
libraries specified at link time are that:
|
||
|
|
</p>
|
||
|
|
<ul>
|
||
|
|
<li> 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.
|
||
|
|
</li><li> There are some operating systems, eg BeOS and HPPA, 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.
|
||
|
|
</p></li></ul>
|
||
|
|
|
||
|
|
<a name="index-_002d_002dno_002dundefined_002dversion"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--no-undefined-version</code></dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002ddefault_002dsymver"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--default-symver</code></dt>
|
||
|
|
<dd><p>Create and use a default symbol version (the soname) for unversioned
|
||
|
|
exported symbols.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002ddefault_002dimported_002dsymver"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--default-imported-symver</code></dt>
|
||
|
|
<dd><p>Create and use a default symbol version (the soname) for unversioned
|
||
|
|
imported symbols.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dno_002dwarn_002dmismatch"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--no-warn-mismatch</code></dt>
|
||
|
|
<dd><p>Normally <code>ld</code> 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 <code>ld</code> 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.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dno_002dwarn_002dsearch_002dmismatch"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--no-warn-search-mismatch</code></dt>
|
||
|
|
<dd><p>Normally <code>ld</code> will give a warning if it finds an incompatible
|
||
|
|
library during a library search. This option silences the warning.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dno_002dwhole_002darchive"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--no-whole-archive</code></dt>
|
||
|
|
<dd><p>Turn off the effect of the <samp>--whole-archive</samp> option for subsequent
|
||
|
|
archive files.
|
||
|
|
</p>
|
||
|
|
<a name="index-output-file-after-errors"></a>
|
||
|
|
<a name="index-_002d_002dnoinhibit_002dexec"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--noinhibit-exec</code></dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dnostdlib"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-nostdlib</code></dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002doformat_003doutput_002dformat"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--oformat=<var>output-format</var></code></dt>
|
||
|
|
<dd><p><code>ld</code> may be configured to support more than one kind of object
|
||
|
|
file. If your <code>ld</code> is configured this way, you can use the
|
||
|
|
‘<samp>--oformat</samp>’ option to specify the binary format for the output
|
||
|
|
object file. Even when <code>ld</code> is configured to support alternative
|
||
|
|
object formats, you don’t usually need to specify this, as <code>ld</code>
|
||
|
|
should be configured to produce as a default output format the most
|
||
|
|
usual format on each machine. <var>output-format</var> is a text string, the
|
||
|
|
name of a particular format supported by the BFD libraries. (You can
|
||
|
|
list the available binary formats with ‘<samp>objdump -i</samp>’.) The script
|
||
|
|
command <code>OUTPUT_FORMAT</code> can also specify the output format, but
|
||
|
|
this option overrides it. See <a href="BFD.html#BFD">BFD</a>.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dout_002dimplib"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--out-implib <var>file</var></code></dt>
|
||
|
|
<dd><p>Create an import library in <var>file</var> corresponding to the executable
|
||
|
|
the linker is generating (eg. a DLL or ELF program). This import
|
||
|
|
library (which should be called <code>*.dll.a</code> or <code>*.a</code> 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. <code>dlltool</code> for DLLs). This option is only available for
|
||
|
|
the i386 PE and ELF targetted ports of the linker.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dpie"></a>
|
||
|
|
<a name="index-_002d_002dpic_002dexecutable"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-pie</code></dt>
|
||
|
|
<dt><code>--pic-executable</code></dt>
|
||
|
|
<dd><a name="index-position-independent-executables"></a>
|
||
|
|
<p>Create a position independent executable. This is currently only supported on
|
||
|
|
ELF platforms. Position independent executables are similar to shared
|
||
|
|
libraries in that they are relocated by the dynamic linker to the virtual
|
||
|
|
address the OS 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.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dqmagic"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-qmagic</code></dt>
|
||
|
|
<dd><p>This option is ignored for Linux compatibility.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dQy"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-Qy</code></dt>
|
||
|
|
<dd><p>This option is ignored for SVR4 compatibility.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002drelax"></a>
|
||
|
|
<a name="index-synthesizing-linker"></a>
|
||
|
|
<a name="index-relaxing-addressing-modes"></a>
|
||
|
|
<a name="index-_002d_002dno_002drelax"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--relax</code></dt>
|
||
|
|
<dt><code>--no-relax</code></dt>
|
||
|
|
<dd><p>An option with machine dependent effects.
|
||
|
|
This option is only supported on a few targets.
|
||
|
|
See <a href="H8_002f300.html#H8_002f300"><code>ld</code> and the H8/300</a>.
|
||
|
|
See <a href="Xtensa.html#Xtensa"><code>ld</code> and Xtensa Processors</a>.
|
||
|
|
See <a href="M68HC11_002f68HC12.html#M68HC11_002f68HC12"><code>ld</code> and the 68HC11 and 68HC12</a>.
|
||
|
|
See <a href="Nios-II.html#Nios-II"><code>ld</code> and the Altera Nios II</a>.
|
||
|
|
See <a href="PowerPC-ELF32.html#PowerPC-ELF32"><code>ld</code> and PowerPC 32-bit ELF Support</a>.
|
||
|
|
</p>
|
||
|
|
<p>On some platforms the ‘<samp>--relax</samp>’ 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>
|
||
|
|
<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 MN10200 and MN10300
|
||
|
|
family of processors.
|
||
|
|
</p>
|
||
|
|
<p>On platforms where this is not supported, ‘<samp>--relax</samp>’ is accepted,
|
||
|
|
but ignored.
|
||
|
|
</p>
|
||
|
|
<p>On platforms where ‘<samp>--relax</samp>’ is accepted the option
|
||
|
|
‘<samp>--no-relax</samp>’ can be used to disable the feature.
|
||
|
|
</p>
|
||
|
|
<a name="index-retaining-specified-symbols"></a>
|
||
|
|
<a name="index-stripping-all-but-some-symbols"></a>
|
||
|
|
<a name="index-symbols_002c-retaining-selectively"></a>
|
||
|
|
<a name="index-_002d_002dretain_002dsymbols_002dfile_003dfilename"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--retain-symbols-file=<var>filename</var></code></dt>
|
||
|
|
<dd><p>Retain <em>only</em> the symbols listed in the file <var>filename</var>,
|
||
|
|
discarding all others. <var>filename</var> 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>
|
||
|
|
<p>‘<samp>--retain-symbols-file</samp>’ does <em>not</em> discard undefined symbols,
|
||
|
|
or symbols needed for relocations.
|
||
|
|
</p>
|
||
|
|
<p>You may only specify ‘<samp>--retain-symbols-file</samp>’ once in the command
|
||
|
|
line. It overrides ‘<samp>-s</samp>’ and ‘<samp>-S</samp>’.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-rpath=<var>dir</var></code></dt>
|
||
|
|
<dd><a name="index-runtime-library-search-path"></a>
|
||
|
|
<a name="index-_002drpath_003ddir"></a>
|
||
|
|
<p>Add a directory to the runtime library search path. This is used when
|
||
|
|
linking an ELF executable with shared objects. All <samp>-rpath</samp>
|
||
|
|
arguments are concatenated and passed to the runtime linker, which uses
|
||
|
|
them to locate shared objects at runtime. The <samp>-rpath</samp> option is
|
||
|
|
also used when locating shared objects which are needed by shared
|
||
|
|
objects explicitly included in the link; see the description of the
|
||
|
|
<samp>-rpath-link</samp> option. If <samp>-rpath</samp> is not used when linking an
|
||
|
|
ELF executable, the contents of the environment variable
|
||
|
|
<code>LD_RUN_PATH</code> will be used if it is defined.
|
||
|
|
</p>
|
||
|
|
<p>The <samp>-rpath</samp> option may also be used on SunOS. By default, on
|
||
|
|
SunOS, the linker will form a runtime search path out of all the
|
||
|
|
<samp>-L</samp> options it is given. If a <samp>-rpath</samp> option is used, the
|
||
|
|
runtime search path will be formed exclusively using the <samp>-rpath</samp>
|
||
|
|
options, ignoring the <samp>-L</samp> options. This can be useful when using
|
||
|
|
gcc, which adds many <samp>-L</samp> options which may be on NFS mounted
|
||
|
|
file systems.
|
||
|
|
</p>
|
||
|
|
<p>For compatibility with other ELF linkers, if the <samp>-R</samp> option is
|
||
|
|
followed by a directory name, rather than a file name, it is treated as
|
||
|
|
the <samp>-rpath</samp> option.
|
||
|
|
</p>
|
||
|
|
<a name="index-link_002dtime-runtime-library-search-path"></a>
|
||
|
|
<a name="index-_002drpath_002dlink_003ddir"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-rpath-link=<var>dir</var></code></dt>
|
||
|
|
<dd><p>When using ELF or SunOS, one shared library may require another. This
|
||
|
|
happens when an <code>ld -shared</code> link includes a shared library as one
|
||
|
|
of the input files.
|
||
|
|
</p>
|
||
|
|
<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 <samp>-rpath-link</samp> option
|
||
|
|
specifies the first set of directories to search. The
|
||
|
|
<samp>-rpath-link</samp> option may specify a sequence of directory names
|
||
|
|
either by specifying a list of names separated by colons, or by
|
||
|
|
appearing multiple times.
|
||
|
|
</p>
|
||
|
|
<p>The tokens <var>$ORIGIN</var> and <var>$LIB</var> 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 <var>$ORIGIN</var>
|
||
|
|
and either ‘<samp>lib</samp>’ - for 32-bit binaries - or ‘<samp>lib64</samp>’ - for
|
||
|
|
64-bit binaries - in the case of <var>$LIB</var>.
|
||
|
|
</p>
|
||
|
|
<p>The alternative form of these tokens - <var>${ORIGIN}</var> and
|
||
|
|
<var>${LIB}</var> can also be used. The token <var>$PLATFORM</var> is not
|
||
|
|
supported.
|
||
|
|
</p>
|
||
|
|
<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>
|
||
|
|
<p>The linker uses the following search paths to locate required shared
|
||
|
|
libraries:
|
||
|
|
</p><ol>
|
||
|
|
<li> Any directories specified by <samp>-rpath-link</samp> options.
|
||
|
|
</li><li> Any directories specified by <samp>-rpath</samp> options. The difference
|
||
|
|
between <samp>-rpath</samp> and <samp>-rpath-link</samp> is that directories
|
||
|
|
specified by <samp>-rpath</samp> options are included in the executable and
|
||
|
|
used at runtime, whereas the <samp>-rpath-link</samp> option is only effective
|
||
|
|
at link time. Searching <samp>-rpath</samp> in this way is only supported
|
||
|
|
by native linkers and cross linkers which have been configured with
|
||
|
|
the <samp>--with-sysroot</samp> option.
|
||
|
|
</li><li> On an ELF system, for native linkers, if the <samp>-rpath</samp> and
|
||
|
|
<samp>-rpath-link</samp> options were not used, search the contents of the
|
||
|
|
environment variable <code>LD_RUN_PATH</code>.
|
||
|
|
</li><li> On SunOS, if the <samp>-rpath</samp> option was not used, search any
|
||
|
|
directories specified using <samp>-L</samp> options.
|
||
|
|
</li><li> For a native linker, search the contents of the environment
|
||
|
|
variable <code>LD_LIBRARY_PATH</code>.
|
||
|
|
</li><li> For a native ELF linker, the directories in <code>DT_RUNPATH</code> or
|
||
|
|
<code>DT_RPATH</code> of a shared library are searched for shared
|
||
|
|
libraries needed by it. The <code>DT_RPATH</code> entries are ignored if
|
||
|
|
<code>DT_RUNPATH</code> entries exist.
|
||
|
|
</li><li> The default directories, normally <samp>/lib</samp> and <samp>/usr/lib</samp>.
|
||
|
|
</li><li> For a native linker on an ELF system, if the file <samp>/etc/ld.so.conf</samp>
|
||
|
|
exists, the list of directories found in that file.
|
||
|
|
</li></ol>
|
||
|
|
|
||
|
|
<p>If the required shared library is not found, the linker will issue a
|
||
|
|
warning and continue with the link.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dshared"></a>
|
||
|
|
<a name="index-_002dBshareable"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-shared</code></dt>
|
||
|
|
<dt><code>-Bshareable</code></dt>
|
||
|
|
<dd><a name="index-shared-libraries"></a>
|
||
|
|
<p>Create a shared library. This is currently only supported on ELF, XCOFF
|
||
|
|
and SunOS platforms. On SunOS, the linker will automatically create a
|
||
|
|
shared library if the <samp>-e</samp> option is not used and there are
|
||
|
|
undefined symbols in the link.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dsort_002dcommon"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--sort-common</code></dt>
|
||
|
|
<dt><code>--sort-common=ascending</code></dt>
|
||
|
|
<dt><code>--sort-common=descending</code></dt>
|
||
|
|
<dd><p>This option tells <code>ld</code> 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.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dsort_002dsection_003dname"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--sort-section=name</code></dt>
|
||
|
|
<dd><p>This option will apply <code>SORT_BY_NAME</code> to all wildcard section
|
||
|
|
patterns in the linker script.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dsort_002dsection_003dalignment"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--sort-section=alignment</code></dt>
|
||
|
|
<dd><p>This option will apply <code>SORT_BY_ALIGNMENT</code> to all wildcard section
|
||
|
|
patterns in the linker script.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dspare_002ddynamic_002dtags"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--spare-dynamic-tags=<var>count</var></code></dt>
|
||
|
|
<dd><p>This option specifies the number of empty slots to leave in the
|
||
|
|
.dynamic section of ELF shared objects. Empty slots may be needed by
|
||
|
|
post processing tools, such as the prelinker. The default is 5.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dsplit_002dby_002dfile"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--split-by-file[=<var>size</var>]</code></dt>
|
||
|
|
<dd><p>Similar to <samp>--split-by-reloc</samp> but creates a new output section for
|
||
|
|
each input file when <var>size</var> is reached. <var>size</var> defaults to a
|
||
|
|
size of 1 if not given.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dsplit_002dby_002dreloc"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--split-by-reloc[=<var>count</var>]</code></dt>
|
||
|
|
<dd><p>Tries to creates extra sections in the output file so that no single
|
||
|
|
output section in the file contains more than <var>count</var> relocations.
|
||
|
|
This is useful when generating huge relocatable files for downloading into
|
||
|
|
certain real time kernels with the COFF object file format; since COFF
|
||
|
|
cannot represent more than 65535 relocations in a single section. Note
|
||
|
|
that this will fail to work with object file formats which do not
|
||
|
|
support arbitrary sections. The linker will not split up individual
|
||
|
|
input sections for redistribution, so if a single input section contains
|
||
|
|
more than <var>count</var> relocations one output section will contain that
|
||
|
|
many relocations. <var>count</var> defaults to a value of 32768.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dstats"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--stats</code></dt>
|
||
|
|
<dd><p>Compute and display statistics about the operation of the linker, such
|
||
|
|
as execution time and memory usage.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dsysroot_003ddirectory"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--sysroot=<var>directory</var></code></dt>
|
||
|
|
<dd><p>Use <var>directory</var> as the location of the sysroot, overriding the
|
||
|
|
configure-time default. This option is only supported by linkers
|
||
|
|
that were configured using <samp>--with-sysroot</samp>.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dtask_002dlink"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--task-link</code></dt>
|
||
|
|
<dd><p>This is used by COFF/PE based targets to create a task-linked object
|
||
|
|
file where all of the global symbols have been converted to statics.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dtraditional_002dformat"></a>
|
||
|
|
<a name="index-traditional-format"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--traditional-format</code></dt>
|
||
|
|
<dd><p>For some targets, the output of <code>ld</code> is different in some ways from
|
||
|
|
the output of some existing linker. This switch requests <code>ld</code> to
|
||
|
|
use the traditional format instead.
|
||
|
|
</p>
|
||
|
|
<a name="index-dbx"></a>
|
||
|
|
<p>For example, on SunOS, <code>ld</code> 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
|
||
|
|
<code>dbx</code> program can not read the resulting program (<code>gdb</code> has no
|
||
|
|
trouble). The ‘<samp>--traditional-format</samp>’ switch tells <code>ld</code> to not
|
||
|
|
combine duplicate entries.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dsection_002dstart_003dsectionname_003dorg"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--section-start=<var>sectionname</var>=<var>org</var></code></dt>
|
||
|
|
<dd><p>Locate a section in the output file at the absolute
|
||
|
|
address given by <var>org</var>. You may use this option as many
|
||
|
|
times as necessary to locate multiple sections in the command
|
||
|
|
line.
|
||
|
|
<var>org</var> must be a single hexadecimal integer;
|
||
|
|
for compatibility with other linkers, you may omit the leading
|
||
|
|
‘<samp>0x</samp>’ usually associated with hexadecimal values. <em>Note:</em> there
|
||
|
|
should be no white space between <var>sectionname</var>, the equals
|
||
|
|
sign (“<tt class="key">=</tt>”), and <var>org</var>.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dTbss_003dorg"></a>
|
||
|
|
<a name="index-_002dTdata_003dorg"></a>
|
||
|
|
<a name="index-_002dTtext_003dorg"></a>
|
||
|
|
<a name="index-segment-origins_002c-cmd-line"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-Tbss=<var>org</var></code></dt>
|
||
|
|
<dt><code>-Tdata=<var>org</var></code></dt>
|
||
|
|
<dt><code>-Ttext=<var>org</var></code></dt>
|
||
|
|
<dd><p>Same as <samp>--section-start</samp>, with <code>.bss</code>, <code>.data</code> or
|
||
|
|
<code>.text</code> as the <var>sectionname</var>.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dTtext_002dsegment_003dorg"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-Ttext-segment=<var>org</var></code></dt>
|
||
|
|
<dd><a name="index-text-segment-origin_002c-cmd-line"></a>
|
||
|
|
<p>When creating an ELF executable, it will set the address of the first
|
||
|
|
byte of the text segment.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dTrodata_002dsegment_003dorg"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-Trodata-segment=<var>org</var></code></dt>
|
||
|
|
<dd><a name="index-rodata-segment-origin_002c-cmd-line"></a>
|
||
|
|
<p>When creating an ELF 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.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002dTldata_002dsegment_003dorg"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>-Tldata-segment=<var>org</var></code></dt>
|
||
|
|
<dd><a name="index-ldata-segment-origin_002c-cmd-line"></a>
|
||
|
|
<p>When creating an ELF executable or shared object for x86-64 medium memory
|
||
|
|
model, it will set the address of the first byte of the ldata segment.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dunresolved_002dsymbols"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--unresolved-symbols=<var>method</var></code></dt>
|
||
|
|
<dd><p>Determine how to handle unresolved symbols. There are four possible
|
||
|
|
values for ‘<samp>method</samp>’:
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dt>‘<samp>ignore-all</samp>’</dt>
|
||
|
|
<dd><p>Do not report any unresolved symbols.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>report-all</samp>’</dt>
|
||
|
|
<dd><p>Report all unresolved symbols. This is the default.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>ignore-in-object-files</samp>’</dt>
|
||
|
|
<dd><p>Report unresolved symbols that are contained in shared libraries, but
|
||
|
|
ignore them if they come from regular object files.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>ignore-in-shared-libs</samp>’</dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>The behaviour for shared libraries on their own can also be controlled
|
||
|
|
by the <samp>--[no-]allow-shlib-undefined</samp> option.
|
||
|
|
</p>
|
||
|
|
<p>Normally the linker will generate an error message for each reported
|
||
|
|
unresolved symbol but the option <samp>--warn-unresolved-symbols</samp>
|
||
|
|
can change this to a warning.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dverbose_005b_003dNUMBER_005d"></a>
|
||
|
|
<a name="index-verbose_005b_003dNUMBER_005d"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--dll-verbose</code></dt>
|
||
|
|
<dt><code>--verbose[=<var>NUMBER</var>]</code></dt>
|
||
|
|
<dd><p>Display the version number for <code>ld</code> 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 <var>NUMBER</var>
|
||
|
|
argument > 1, plugin symbol status will also be displayed.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dversion_002dscript_003dversion_002dscriptfile"></a>
|
||
|
|
<a name="index-version-script_002c-symbol-versions"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--version-script=<var>version-scriptfile</var></code></dt>
|
||
|
|
<dd><p>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 ELF platforms which support shared libraries;
|
||
|
|
see <a href="VERSION.html#VERSION">VERSION</a>. It is partially supported on PE platforms, which can
|
||
|
|
use version scripts to filter symbol visibility in auto-export mode: any
|
||
|
|
symbols marked ‘<samp>local</samp>’ in the version script will not be exported.
|
||
|
|
See <a href="WIN32.html#WIN32">WIN32</a>.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dwarn_002dcommon"></a>
|
||
|
|
<a name="index-warnings_002c-on-combining-symbols"></a>
|
||
|
|
<a name="index-combining-symbols_002c-warnings-on"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--warn-common</code></dt>
|
||
|
|
<dd><p>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>
|
||
|
|
<p>There are three kinds of global symbols, illustrated here by C examples:
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dt>‘<samp>int i = 1;</samp>’</dt>
|
||
|
|
<dd><p>A definition, which goes in the initialized data section of the output
|
||
|
|
file.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>extern int i;</samp>’</dt>
|
||
|
|
<dd><p>An undefined reference, which does not allocate space.
|
||
|
|
There must be either a definition or a common symbol for the
|
||
|
|
variable somewhere.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt>‘<samp>int i;</samp>’</dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>The ‘<samp>--warn-common</samp>’ 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.
|
||
|
|
</p>
|
||
|
|
<ol>
|
||
|
|
<li> Turning a common symbol into a reference, because there is already a
|
||
|
|
definition for the symbol.
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample"><var>file</var>(<var>section</var>): warning: common of `<var>symbol</var>'
|
||
|
|
overridden by definition
|
||
|
|
<var>file</var>(<var>section</var>): warning: defined here
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</li><li> 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.
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample"><var>file</var>(<var>section</var>): warning: definition of `<var>symbol</var>'
|
||
|
|
overriding common
|
||
|
|
<var>file</var>(<var>section</var>): warning: common is here
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</li><li> Merging a common symbol with a previous same-sized common symbol.
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample"><var>file</var>(<var>section</var>): warning: multiple common
|
||
|
|
of `<var>symbol</var>'
|
||
|
|
<var>file</var>(<var>section</var>): warning: previous common is here
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</li><li> Merging a common symbol with a previous larger common symbol.
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample"><var>file</var>(<var>section</var>): warning: common of `<var>symbol</var>'
|
||
|
|
overridden by larger common
|
||
|
|
<var>file</var>(<var>section</var>): warning: larger common is here
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
</li><li> 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.
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample"><var>file</var>(<var>section</var>): warning: common of `<var>symbol</var>'
|
||
|
|
overriding smaller common
|
||
|
|
<var>file</var>(<var>section</var>): warning: smaller common is here
|
||
|
|
</pre></div>
|
||
|
|
</li></ol>
|
||
|
|
|
||
|
|
<a name="index-_002d_002dwarn_002dconstructors"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--warn-constructors</code></dt>
|
||
|
|
<dd><p>Warn if any global constructors are used. This is only useful for a few
|
||
|
|
object file formats. For formats like COFF or ELF, the linker can not
|
||
|
|
detect the use of global constructors.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dwarn_002dmultiple_002dgp"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--warn-multiple-gp</code></dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dwarn_002donce"></a>
|
||
|
|
<a name="index-warnings_002c-on-undefined-symbols"></a>
|
||
|
|
<a name="index-undefined-symbols_002c-warnings-on"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--warn-once</code></dt>
|
||
|
|
<dd><p>Only warn once for each undefined symbol, rather than once per module
|
||
|
|
which refers to it.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dwarn_002dsection_002dalign"></a>
|
||
|
|
<a name="index-warnings_002c-on-section-alignment"></a>
|
||
|
|
<a name="index-section-alignment_002c-warnings-on"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--warn-section-align</code></dt>
|
||
|
|
<dd><p>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 <code>SECTIONS</code> command does not specify a start address for
|
||
|
|
the section (see <a href="SECTIONS.html#SECTIONS">SECTIONS</a>).
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dwarn_002dshared_002dtextrel"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--warn-shared-textrel</code></dt>
|
||
|
|
<dd><p>Warn if the linker adds a DT_TEXTREL to a shared object.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dwarn_002dalternate_002dem"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--warn-alternate-em</code></dt>
|
||
|
|
<dd><p>Warn if an object has alternate ELF machine code.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dwarn_002dunresolved_002dsymbols"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--warn-unresolved-symbols</code></dt>
|
||
|
|
<dd><p>If the linker is going to report an unresolved symbol (see the option
|
||
|
|
<samp>--unresolved-symbols</samp>) it will normally generate an error.
|
||
|
|
This option makes it generate a warning instead.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002derror_002dunresolved_002dsymbols"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--error-unresolved-symbols</code></dt>
|
||
|
|
<dd><p>This restores the linker’s default behaviour of generating errors when
|
||
|
|
it is reporting unresolved symbols.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dwhole_002darchive"></a>
|
||
|
|
<a name="index-including-an-entire-archive"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--whole-archive</code></dt>
|
||
|
|
<dd><p>For each archive mentioned on the command line after the
|
||
|
|
<samp>--whole-archive</samp> 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>
|
||
|
|
<p>Two notes when using this option from gcc: First, gcc doesn’t know
|
||
|
|
about this option, so you have to use <samp>-Wl,-whole-archive</samp>.
|
||
|
|
Second, don’t forget to use <samp>-Wl,-no-whole-archive</samp> 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.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dwrap_003dsymbol"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--wrap=<var>symbol</var></code></dt>
|
||
|
|
<dd><p>Use a wrapper function for <var>symbol</var>. Any undefined reference to
|
||
|
|
<var>symbol</var> will be resolved to <code>__wrap_<var>symbol</var></code>. Any
|
||
|
|
undefined reference to <code>__real_<var>symbol</var></code> will be resolved to
|
||
|
|
<var>symbol</var>.
|
||
|
|
</p>
|
||
|
|
<p>This can be used to provide a wrapper for a system function. The
|
||
|
|
wrapper function should be called <code>__wrap_<var>symbol</var></code>. If it
|
||
|
|
wishes to call the system function, it should call
|
||
|
|
<code>__real_<var>symbol</var></code>.
|
||
|
|
</p>
|
||
|
|
<p>Here is a trivial example:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">void *
|
||
|
|
__wrap_malloc (size_t c)
|
||
|
|
{
|
||
|
|
printf ("malloc called with %zu\n", c);
|
||
|
|
return __real_malloc (c);
|
||
|
|
}
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>If you link other code with this file using <samp>--wrap malloc</samp>, then
|
||
|
|
all calls to <code>malloc</code> will call the function <code>__wrap_malloc</code>
|
||
|
|
instead. The call to <code>__real_malloc</code> in <code>__wrap_malloc</code> will
|
||
|
|
call the real <code>malloc</code> function.
|
||
|
|
</p>
|
||
|
|
<p>You may wish to provide a <code>__real_malloc</code> function as well, so that
|
||
|
|
links without the <samp>--wrap</samp> option will succeed. If you do this,
|
||
|
|
you should not put the definition of <code>__real_malloc</code> in the same
|
||
|
|
file as <code>__wrap_malloc</code>; if you do, the assembler may resolve the
|
||
|
|
call before the linker has a chance to wrap it to <code>malloc</code>.
|
||
|
|
</p>
|
||
|
|
<p>Only undefined references are replaced by the linker. So, translation unit
|
||
|
|
internal references to <var>symbol</var> are not resolved to
|
||
|
|
<code>__wrap_<var>symbol</var></code>. In the next example, the call to <code>f</code> in
|
||
|
|
<code>g</code> is not resolved to <code>__wrap_f</code>.
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">int
|
||
|
|
f (void)
|
||
|
|
{
|
||
|
|
return 123;
|
||
|
|
}
|
||
|
|
|
||
|
|
int
|
||
|
|
g (void)
|
||
|
|
{
|
||
|
|
return f();
|
||
|
|
}
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<a name="index-_002d_002deh_002dframe_002dhdr"></a>
|
||
|
|
<a name="index-_002d_002dno_002deh_002dframe_002dhdr"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--eh-frame-hdr</code></dt>
|
||
|
|
<dt><code>--no-eh-frame-hdr</code></dt>
|
||
|
|
<dd><p>Request (<samp>--eh-frame-hdr</samp>) or suppress
|
||
|
|
(<samp>--no-eh-frame-hdr</samp>) the creation of <code>.eh_frame_hdr</code>
|
||
|
|
section and ELF <code>PT_GNU_EH_FRAME</code> segment header.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dld_002dgenerated_002dunwind_002dinfo"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--no-ld-generated-unwind-info</code></dt>
|
||
|
|
<dd><p>Request creation of <code>.eh_frame</code> unwind info for linker
|
||
|
|
generated code sections like PLT. This option is on by default
|
||
|
|
if linker generated unwind info is supported.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002denable_002dnew_002ddtags"></a>
|
||
|
|
<a name="index-_002d_002ddisable_002dnew_002ddtags"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--enable-new-dtags</code></dt>
|
||
|
|
<dt><code>--disable-new-dtags</code></dt>
|
||
|
|
<dd><p>This linker can create the new dynamic tags in ELF. But the older ELF
|
||
|
|
systems may not understand them. If you specify
|
||
|
|
<samp>--enable-new-dtags</samp>, the new dynamic tags will be created as needed
|
||
|
|
and older dynamic tags will be omitted.
|
||
|
|
If you specify <samp>--disable-new-dtags</samp>, no new dynamic tags will be
|
||
|
|
created. By default, the new dynamic tags are not created. Note that
|
||
|
|
those options are only available for ELF systems.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dhash_002dsize_003dnumber"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--hash-size=<var>number</var></code></dt>
|
||
|
|
<dd><p>Set the default size of the linker’s hash tables to a prime number
|
||
|
|
close to <var>number</var>. 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.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dhash_002dstyle_003dstyle"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--hash-style=<var>style</var></code></dt>
|
||
|
|
<dd><p>Set the type of linker’s hash table(s). <var>style</var> can be either
|
||
|
|
<code>sysv</code> for classic ELF <code>.hash</code> section, <code>gnu</code> for
|
||
|
|
new style GNU <code>.gnu.hash</code> section or <code>both</code> for both
|
||
|
|
the classic ELF <code>.hash</code> and new style GNU <code>.gnu.hash</code>
|
||
|
|
hash tables. The default depends upon how the linker was configured,
|
||
|
|
but for most Linux based systems it will be <code>both</code>.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dcompress_002ddebug_002dsections_003dnone"></a>
|
||
|
|
<a name="index-_002d_002dcompress_002ddebug_002dsections_003dzlib"></a>
|
||
|
|
<a name="index-_002d_002dcompress_002ddebug_002dsections_003dzlib_002dgnu"></a>
|
||
|
|
<a name="index-_002d_002dcompress_002ddebug_002dsections_003dzlib_002dgabi"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--compress-debug-sections=none</code></dt>
|
||
|
|
<dt><code>--compress-debug-sections=zlib</code></dt>
|
||
|
|
<dt><code>--compress-debug-sections=zlib-gnu</code></dt>
|
||
|
|
<dt><code>--compress-debug-sections=zlib-gabi</code></dt>
|
||
|
|
<dd><p>On ELF platforms, these options control how DWARF debug sections are
|
||
|
|
compressed using zlib.
|
||
|
|
</p>
|
||
|
|
<p><samp>--compress-debug-sections=none</samp> doesn’t compress DWARF debug
|
||
|
|
sections. <samp>--compress-debug-sections=zlib-gnu</samp> compresses
|
||
|
|
DWARF debug sections and renames them to begin with ‘<samp>.zdebug</samp>’
|
||
|
|
instead of ‘<samp>.debug</samp>’. <samp>--compress-debug-sections=zlib-gabi</samp>
|
||
|
|
also compresses DWARF debug sections, but rather than renaming them it
|
||
|
|
sets the SHF_COMPRESSED flag in the sections’ headers.
|
||
|
|
</p>
|
||
|
|
<p>The <samp>--compress-debug-sections=zlib</samp> option is an alias for
|
||
|
|
<samp>--compress-debug-sections=zlib-gabi</samp>.
|
||
|
|
</p>
|
||
|
|
<p>Note that this option overrides any compression in input debug
|
||
|
|
sections, so if a binary is linked with <samp>--compress-debug-sections=none</samp>
|
||
|
|
for example, then any compressed debug sections in input files will be
|
||
|
|
uncompressed before they are copied into the output binary.
|
||
|
|
</p>
|
||
|
|
<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
|
||
|
|
<samp>--help</samp> option.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dreduce_002dmemory_002doverheads"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--reduce-memory-overheads</code></dt>
|
||
|
|
<dd><p>This option reduces memory requirements at ld runtime, at the expense of
|
||
|
|
linking speed. This was introduced to select the old O(n^2) algorithm
|
||
|
|
for link map file generation, rather than the new O(n) algorithm which uses
|
||
|
|
about 40% more memory for symbol storage.
|
||
|
|
</p>
|
||
|
|
<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 <samp>--hash-size</samp> switch
|
||
|
|
has been used.
|
||
|
|
</p>
|
||
|
|
<p>The <samp>--reduce-memory-overheads</samp> switch may be also be used to
|
||
|
|
enable other tradeoffs in future versions of the linker.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dbuild_002did"></a>
|
||
|
|
<a name="index-_002d_002dbuild_002did_003dstyle"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--build-id</code></dt>
|
||
|
|
<dt><code>--build-id=<var>style</var></code></dt>
|
||
|
|
<dd><p>Request the creation of a <code>.note.gnu.build-id</code> ELF note section
|
||
|
|
or a <code>.buildid</code> COFF section. The contents of the note are
|
||
|
|
unique bits identifying this linked file. <var>style</var> can be
|
||
|
|
<code>uuid</code> to use 128 random bits, <code>sha1</code> to use a 160-bit
|
||
|
|
<small>SHA1</small> hash on the normative parts of the output contents,
|
||
|
|
<code>md5</code> to use a 128-bit <small>MD5</small> hash on the normative parts of
|
||
|
|
the output contents, or <code>0x<var>hexstring</var></code> to use a chosen bit
|
||
|
|
string specified as an even number of hexadecimal digits (<code>-</code> and
|
||
|
|
<code>:</code> characters between digit pairs are ignored). If <var>style</var>
|
||
|
|
is omitted, <code>sha1</code> is used.
|
||
|
|
</p>
|
||
|
|
<p>The <code>md5</code> and <code>sha1</code> 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 ID bit
|
||
|
|
string identifying the original linked file does not change.
|
||
|
|
</p>
|
||
|
|
<p>Passing <code>none</code> for <var>style</var> disables the setting from any
|
||
|
|
<code>--build-id</code> options earlier on the command line.
|
||
|
|
</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
|
||
|
|
<a name="Options-Specific-to-i386-PE-Targets"></a>
|
||
|
|
<h4 class="subsection">2.1.1 Options Specific to i386 PE Targets</h4>
|
||
|
|
|
||
|
|
|
||
|
|
<p>The i386 PE linker supports the <samp>-shared</samp> option, which causes
|
||
|
|
the output to be a dynamically linked library (DLL) instead of a
|
||
|
|
normal executable. You should name the output <code>*.dll</code> when you
|
||
|
|
use this option. In addition, the linker fully supports the standard
|
||
|
|
<code>*.def</code> 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>
|
||
|
|
<p>In addition to the options common to all targets, the i386 PE linker
|
||
|
|
support additional command-line options that are specific to the i386
|
||
|
|
PE target. Options that take values may be separated from their
|
||
|
|
values by either a space or an equals sign.
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dd>
|
||
|
|
<a name="index-_002d_002dadd_002dstdcall_002dalias"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--add-stdcall-alias</code></dt>
|
||
|
|
<dd><p>If given, symbols with a stdcall suffix (@<var>nn</var>) will be exported
|
||
|
|
as-is and also with the suffix stripped.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dbase_002dfile"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--base-file <var>file</var></code></dt>
|
||
|
|
<dd><p>Use <var>file</var> as the name of a file in which to save the base
|
||
|
|
addresses of all the relocations needed for generating DLLs with
|
||
|
|
<samp>dlltool</samp>.
|
||
|
|
[This is an i386 PE specific option]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002ddll"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--dll</code></dt>
|
||
|
|
<dd><p>Create a DLL instead of a regular executable. You may also use
|
||
|
|
<samp>-shared</samp> or specify a <code>LIBRARY</code> in a given <code>.def</code>
|
||
|
|
file.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002denable_002dlong_002dsection_002dnames"></a>
|
||
|
|
<a name="index-_002d_002ddisable_002dlong_002dsection_002dnames"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--enable-long-section-names</code></dt>
|
||
|
|
<dt><code>--disable-long-section-names</code></dt>
|
||
|
|
<dd><p>The PE variants of the COFF object format add an extension that permits
|
||
|
|
the use of section names longer than eight characters, the normal limit
|
||
|
|
for COFF. By default, these names are only allowed in object files, as
|
||
|
|
fully-linked executable images do not carry the COFF string table required
|
||
|
|
to support the longer names. As a GNU 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,
|
||
|
|
GDB relies on the use of PE 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, <code>ld</code> 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 PE targeted ports of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002denable_002dstdcall_002dfixup"></a>
|
||
|
|
<a name="index-_002d_002ddisable_002dstdcall_002dfixup"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--enable-stdcall-fixup</code></dt>
|
||
|
|
<dt><code>--disable-stdcall-fixup</code></dt>
|
||
|
|
<dd><p>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 <code>_foo</code> might be linked to the function
|
||
|
|
<code>_foo@12</code>, or the undefined symbol <code>_bar@16</code> might be linked
|
||
|
|
to the function <code>_bar</code>. 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 <samp>--enable-stdcall-fixup</samp>, this
|
||
|
|
feature is fully enabled and warnings are not printed. If you specify
|
||
|
|
<samp>--disable-stdcall-fixup</samp>, this feature is disabled and such
|
||
|
|
mismatches are considered to be errors.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dleading_002dunderscore"></a>
|
||
|
|
<a name="index-_002d_002dno_002dleading_002dunderscore"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--leading-underscore</code></dt>
|
||
|
|
<dt><code>--no-leading-underscore</code></dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
<a name="index-DLLs_002c-creating"></a>
|
||
|
|
<a name="index-_002d_002dexport_002dall_002dsymbols"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--export-all-symbols</code></dt>
|
||
|
|
<dd><p>If given, all global symbols in the objects used to build a DLL will
|
||
|
|
be exported by the DLL. Note that this is the default if there
|
||
|
|
otherwise wouldn’t be any exported symbols. When symbols are
|
||
|
|
explicitly exported via DEF files or implicitly exported via function
|
||
|
|
attributes, the default is to not export anything else unless this
|
||
|
|
option is given. Note that the symbols <code>DllMain@12</code>,
|
||
|
|
<code>DllEntryPoint@0</code>, <code>DllMainCRTStartup@12</code>, and
|
||
|
|
<code>impure_ptr</code> will not be automatically
|
||
|
|
exported. Also, symbols imported from other DLLs will not be
|
||
|
|
re-exported, nor will symbols specifying the DLL’s internal layout
|
||
|
|
such as those beginning with <code>_head_</code> or ending with
|
||
|
|
<code>_iname</code>. In addition, no symbols from <code>libgcc</code>,
|
||
|
|
<code>libstd++</code>, <code>libmingw32</code>, or <code>crtX.o</code> will be exported.
|
||
|
|
Symbols whose names begin with <code>__rtti_</code> or <code>__builtin_</code> will
|
||
|
|
not be exported, to help with C++ DLLs. Finally, there is an
|
||
|
|
extensive list of cygwin-private symbols that are not exported
|
||
|
|
(obviously, this applies on when building DLLs for cygwin targets).
|
||
|
|
These cygwin-excludes are: <code>_cygwin_dll_entry@12</code>,
|
||
|
|
<code>_cygwin_crt0_common@8</code>, <code>_cygwin_noncygwin_dll_entry@12</code>,
|
||
|
|
<code>_fmode</code>, <code>_impure_ptr</code>, <code>cygwin_attach_dll</code>,
|
||
|
|
<code>cygwin_premain0</code>, <code>cygwin_premain1</code>, <code>cygwin_premain2</code>,
|
||
|
|
<code>cygwin_premain3</code>, and <code>environ</code>.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dexclude_002dsymbols"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--exclude-symbols <var>symbol</var>,<var>symbol</var>,...</code></dt>
|
||
|
|
<dd><p>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 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dexclude_002dall_002dsymbols"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--exclude-all-symbols</code></dt>
|
||
|
|
<dd><p>Specifies no symbols should be automatically exported.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dfile_002dalignment"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--file-alignment</code></dt>
|
||
|
|
<dd><p>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 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-heap-size"></a>
|
||
|
|
<a name="index-_002d_002dheap"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--heap <var>reserve</var></code></dt>
|
||
|
|
<dt><code>--heap <var>reserve</var>,<var>commit</var></code></dt>
|
||
|
|
<dd><p>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 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-image-base"></a>
|
||
|
|
<a name="index-_002d_002dimage_002dbase"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--image-base <var>value</var></code></dt>
|
||
|
|
<dd><p>Use <var>value</var> 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 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dkill_002dat"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--kill-at</code></dt>
|
||
|
|
<dd><p>If given, the stdcall suffixes (@<var>nn</var>) will be stripped from
|
||
|
|
symbols before they are exported.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dlarge_002daddress_002daware"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--large-address-aware</code></dt>
|
||
|
|
<dd><p>If given, the appropriate bit in the “Characteristics” field of the COFF
|
||
|
|
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=<var>value</var> megabytes switch in the “[operating systems]”
|
||
|
|
section of the BOOT.INI. Otherwise, this bit has no effect.
|
||
|
|
[This option is specific to PE targeted ports of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002ddisable_002dlarge_002daddress_002daware"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--disable-large-address-aware</code></dt>
|
||
|
|
<dd><p>Reverts the effect of a previous ‘<samp>--large-address-aware</samp>’ option.
|
||
|
|
This is useful if ‘<samp>--large-address-aware</samp>’ 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 PE targeted ports of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dmajor_002dimage_002dversion"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--major-image-version <var>value</var></code></dt>
|
||
|
|
<dd><p>Sets the major number of the “image version”. Defaults to 1.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dmajor_002dos_002dversion"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--major-os-version <var>value</var></code></dt>
|
||
|
|
<dd><p>Sets the major number of the “os version”. Defaults to 4.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dmajor_002dsubsystem_002dversion"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--major-subsystem-version <var>value</var></code></dt>
|
||
|
|
<dd><p>Sets the major number of the “subsystem version”. Defaults to 4.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dminor_002dimage_002dversion"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--minor-image-version <var>value</var></code></dt>
|
||
|
|
<dd><p>Sets the minor number of the “image version”. Defaults to 0.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dminor_002dos_002dversion"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--minor-os-version <var>value</var></code></dt>
|
||
|
|
<dd><p>Sets the minor number of the “os version”. Defaults to 0.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dminor_002dsubsystem_002dversion"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--minor-subsystem-version <var>value</var></code></dt>
|
||
|
|
<dd><p>Sets the minor number of the “subsystem version”. Defaults to 0.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-DEF-files_002c-creating"></a>
|
||
|
|
<a name="index-DLLs_002c-creating-1"></a>
|
||
|
|
<a name="index-_002d_002doutput_002ddef"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--output-def <var>file</var></code></dt>
|
||
|
|
<dd><p>The linker will create the file <var>file</var> which will contain a DEF
|
||
|
|
file corresponding to the DLL the linker is generating. This DEF file
|
||
|
|
(which should be called <code>*.def</code>) may be used to create an import
|
||
|
|
library with <code>dlltool</code> or may be used as a reference to
|
||
|
|
automatically or implicitly exported symbols.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-DLLs_002c-creating-2"></a>
|
||
|
|
<a name="index-_002d_002denable_002dauto_002dimage_002dbase"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--enable-auto-image-base</code></dt>
|
||
|
|
<dt><code>--enable-auto-image-base=<var>value</var></code></dt>
|
||
|
|
<dd><p>Automatically choose the image base for DLLs, optionally starting with base
|
||
|
|
<var>value</var>, unless one is specified using the <code>--image-base</code> argument.
|
||
|
|
By using a hash generated from the dllname to create unique image bases
|
||
|
|
for each DLL, in-memory collisions and relocations which can delay program
|
||
|
|
execution are avoided.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002ddisable_002dauto_002dimage_002dbase"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--disable-auto-image-base</code></dt>
|
||
|
|
<dd><p>Do not automatically generate a unique image base. If there is no
|
||
|
|
user-specified image base (<code>--image-base</code>) then use the platform
|
||
|
|
default.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-DLLs_002c-linking-to"></a>
|
||
|
|
<a name="index-_002d_002ddll_002dsearch_002dprefix"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--dll-search-prefix <var>string</var></code></dt>
|
||
|
|
<dd><p>When linking dynamically to a dll without an import library,
|
||
|
|
search for <code><string><basename>.dll</code> in preference to
|
||
|
|
<code>lib<basename>.dll</code>. This behaviour allows easy distinction
|
||
|
|
between DLLs built for the various "subplatforms": native, cygwin,
|
||
|
|
uwin, pw, etc. For instance, cygwin DLLs typically use
|
||
|
|
<code>--dll-search-prefix=cyg</code>.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002denable_002dauto_002dimport"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--enable-auto-import</code></dt>
|
||
|
|
<dd><p>Do sophisticated linking of <code>_symbol</code> to <code>__imp__symbol</code> for
|
||
|
|
DATA 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 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<p>The following remarks pertain to the original implementation of the
|
||
|
|
feature and are obsolete nowadays for Cygwin and MinGW targets.
|
||
|
|
</p>
|
||
|
|
<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>
|
||
|
|
<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:
|
||
|
|
http://www.cygwin.com/ml/cygwin/2004-09/msg01101.html
|
||
|
|
</p>
|
||
|
|
<p>Using ’auto-import’ generally will ’just work’ – but sometimes you may
|
||
|
|
see this message:
|
||
|
|
</p>
|
||
|
|
<p>"variable ’<var>’ can’t be auto-imported. Please read the
|
||
|
|
documentation for ld’s <code>--enable-auto-import</code> for details."
|
||
|
|
</p>
|
||
|
|
<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 DLL, as well as using a
|
||
|
|
constant index into an array variable imported from a DLL. 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>
|
||
|
|
<p>There are several ways to address this difficulty, regardless of the
|
||
|
|
data type of the exported variable:
|
||
|
|
</p>
|
||
|
|
<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>
|
||
|
|
<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>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">extern type extern_array[];
|
||
|
|
extern_array[1] -->
|
||
|
|
{ volatile type *t=extern_array; t[1] }
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>or
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">extern type extern_array[];
|
||
|
|
extern_array[1] -->
|
||
|
|
{ volatile int t=1; extern_array[t] }
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">extern struct s extern_struct;
|
||
|
|
extern_struct.field -->
|
||
|
|
{ volatile struct s *t=&extern_struct; t->field }
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>or
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">extern long long extern_ll;
|
||
|
|
extern_ll -->
|
||
|
|
{ volatile long long * local_ll=&extern_ll; *local_ll }
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>A third method of dealing with this difficulty is to abandon
|
||
|
|
’auto-import’ for the offending symbol and mark it with
|
||
|
|
<code>__declspec(dllimport)</code>. However, in practice that
|
||
|
|
requires using compile-time #defines to indicate whether you are
|
||
|
|
building a DLL, building client code that will link to the DLL, 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>
|
||
|
|
<p>Original:
|
||
|
|
</p><div class="example">
|
||
|
|
<pre class="example">--foo.h
|
||
|
|
extern int arr[];
|
||
|
|
--foo.c
|
||
|
|
#include "foo.h"
|
||
|
|
void main(int argc, char **argv){
|
||
|
|
printf("%d\n",arr[1]);
|
||
|
|
}
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>Solution 1:
|
||
|
|
</p><div class="example">
|
||
|
|
<pre class="example">--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></div>
|
||
|
|
|
||
|
|
<p>Solution 2:
|
||
|
|
</p><div class="example">
|
||
|
|
<pre class="example">--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></div>
|
||
|
|
|
||
|
|
<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. set_foo() and get_foo() accessor
|
||
|
|
functions).
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002ddisable_002dauto_002dimport"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--disable-auto-import</code></dt>
|
||
|
|
<dd><p>Do not attempt to do sophisticated linking of <code>_symbol</code> to
|
||
|
|
<code>__imp__symbol</code> for DATA imports from DLLs.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002denable_002druntime_002dpseudo_002dreloc"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--enable-runtime-pseudo-reloc</code></dt>
|
||
|
|
<dd><p>If your code contains expressions described in –enable-auto-import section,
|
||
|
|
that is, DATA imports from DLL 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 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002ddisable_002druntime_002dpseudo_002dreloc"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--disable-runtime-pseudo-reloc</code></dt>
|
||
|
|
<dd><p>Do not create pseudo relocations for non-zero offset DATA imports from DLLs.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002denable_002dextra_002dpe_002ddebug"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--enable-extra-pe-debug</code></dt>
|
||
|
|
<dd><p>Show additional debug info related to auto-import symbol thunking.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dsection_002dalignment"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--section-alignment</code></dt>
|
||
|
|
<dd><p>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 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-stack-size"></a>
|
||
|
|
<a name="index-_002d_002dstack"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--stack <var>reserve</var></code></dt>
|
||
|
|
<dt><code>--stack <var>reserve</var>,<var>commit</var></code></dt>
|
||
|
|
<dd><p>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 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dsubsystem"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--subsystem <var>which</var></code></dt>
|
||
|
|
<dt><code>--subsystem <var>which</var>:<var>major</var></code></dt>
|
||
|
|
<dt><code>--subsystem <var>which</var>:<var>major</var>.<var>minor</var></code></dt>
|
||
|
|
<dd><p>Specifies the subsystem under which your program will execute. The
|
||
|
|
legal values for <var>which</var> are <code>native</code>, <code>windows</code>,
|
||
|
|
<code>console</code>, <code>posix</code>, and <code>xbox</code>. You may optionally set
|
||
|
|
the subsystem version also. Numeric values are also accepted for
|
||
|
|
<var>which</var>.
|
||
|
|
[This option is specific to the i386 PE targeted port of the linker]
|
||
|
|
</p>
|
||
|
|
<p>The following options set flags in the <code>DllCharacteristics</code> field
|
||
|
|
of the PE file header:
|
||
|
|
[These options are specific to PE targeted ports of the linker]
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dhigh_002dentropy_002dva"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--high-entropy-va</code></dt>
|
||
|
|
<dd><p>Image is compatible with 64-bit address space layout randomization
|
||
|
|
(ASLR).
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002ddynamicbase"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--dynamicbase</code></dt>
|
||
|
|
<dd><p>The image base address may be relocated using address space layout
|
||
|
|
randomization (ASLR). This feature was introduced with MS Windows
|
||
|
|
Vista for i386 PE targets.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dforceinteg"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--forceinteg</code></dt>
|
||
|
|
<dd><p>Code integrity checks are enforced.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dnxcompat"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--nxcompat</code></dt>
|
||
|
|
<dd><p>The image is compatible with the Data Execution Prevention.
|
||
|
|
This feature was introduced with MS Windows XP SP2 for i386 PE targets.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dno_002disolation"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--no-isolation</code></dt>
|
||
|
|
<dd><p>Although the image understands isolation, do not isolate the image.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dno_002dseh"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--no-seh</code></dt>
|
||
|
|
<dd><p>The image does not use SEH. No SE handler may be called from
|
||
|
|
this image.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dno_002dbind"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--no-bind</code></dt>
|
||
|
|
<dd><p>Do not bind this image.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dwdmdriver"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--wdmdriver</code></dt>
|
||
|
|
<dd><p>The driver uses the MS Windows Driver Model.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dtsaware"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--tsaware</code></dt>
|
||
|
|
<dd><p>The image is Terminal Server aware.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dinsert_002dtimestamp"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--insert-timestamp</code></dt>
|
||
|
|
<dt><code>--no-insert-timestamp</code></dt>
|
||
|
|
<dd><p>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 <samp>--no-insert-timestamp</samp>
|
||
|
|
can be used to insert a zero value for the timestamp, this ensuring
|
||
|
|
that binaries produced from identical sources will compare
|
||
|
|
identically.
|
||
|
|
</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
|
||
|
|
<a name="Options-specific-to-C6X-uClinux-targets"></a>
|
||
|
|
<h4 class="subsection">2.1.2 Options specific to C6X uClinux targets</h4>
|
||
|
|
|
||
|
|
|
||
|
|
<p>The C6X uClinux target uses a binary format called DSBT to support shared
|
||
|
|
libraries. Each shared library in the system needs to have a unique index;
|
||
|
|
all executables use an index of 0.
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dd>
|
||
|
|
<a name="index-_002d_002ddsbt_002dsize"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--dsbt-size <var>size</var></code></dt>
|
||
|
|
<dd><p>This option sets the number of entries in the DSBT of the current executable
|
||
|
|
or shared library to <var>size</var>. The default is to create a table with 64
|
||
|
|
entries.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002ddsbt_002dindex"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--dsbt-index <var>index</var></code></dt>
|
||
|
|
<dd><p>This option sets the DSBT index of the current executable or shared library
|
||
|
|
to <var>index</var>. The default is 0, which is appropriate for generating
|
||
|
|
executables. If a shared library is generated with a DSBT index of 0, the
|
||
|
|
<code>R_C6000_DSBT_INDEX</code> relocs are copied into the output file.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dno_002dmerge_002dexidx_002dentries"></a>
|
||
|
|
<p>The ‘<samp>--no-merge-exidx-entries</samp>’ switch disables the merging of adjacent
|
||
|
|
exidx entries in frame unwind info.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
|
||
|
|
<a name="Options-specific-to-C_002dSKY-targets"></a>
|
||
|
|
<h4 class="subsection">2.1.3 Options specific to C-SKY targets</h4>
|
||
|
|
|
||
|
|
|
||
|
|
<dl compact="compact">
|
||
|
|
<dd>
|
||
|
|
<a name="index-_002d_002dbranch_002dstub-on-C_002dSKY"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--branch-stub</code></dt>
|
||
|
|
<dd><p>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.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dstub_002dgroup_002dsize-on-C_002dSKY"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--stub-group-size=<var>N</var></code></dt>
|
||
|
|
<dd><p>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 <var>N</var> locates
|
||
|
|
stub sections after their branches, while a positive value allows stub
|
||
|
|
sections to appear either before or after the branches. Values of
|
||
|
|
‘<samp>1</samp>’ or ‘<samp>-1</samp>’ indicate that the
|
||
|
|
linker should choose suitable defaults.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
|
||
|
|
<a name="Options-specific-to-Motorola-68HC11-and-68HC12-targets"></a>
|
||
|
|
<h4 class="subsection">2.1.4 Options specific to Motorola 68HC11 and 68HC12 targets</h4>
|
||
|
|
|
||
|
|
|
||
|
|
<p>The 68HC11 and 68HC12 linkers support specific options to control the
|
||
|
|
memory bank switching mapping and trampoline code generation.
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dd>
|
||
|
|
<a name="index-_002d_002dno_002dtrampoline"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--no-trampoline</code></dt>
|
||
|
|
<dd><p>This option disables the generation of trampoline. By default a trampoline
|
||
|
|
is generated for each far function which is called using a <code>jsr</code>
|
||
|
|
instruction (this happens when a pointer to a far function is taken).
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dbank_002dwindow"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--bank-window <var>name</var></code></dt>
|
||
|
|
<dd><p>This option indicates to the linker the name of the memory region in
|
||
|
|
the ‘<samp>MEMORY</samp>’ 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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
|
||
|
|
<a name="Options-specific-to-Motorola-68K-target"></a>
|
||
|
|
<h4 class="subsection">2.1.5 Options specific to Motorola 68K target</h4>
|
||
|
|
|
||
|
|
|
||
|
|
<p>The following options are supported to control handling of GOT generation
|
||
|
|
when linking for 68K targets.
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dd>
|
||
|
|
<a name="index-_002d_002dgot"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--got=<var>type</var></code></dt>
|
||
|
|
<dd><p>This option tells the linker which GOT generation scheme to use.
|
||
|
|
<var>type</var> should be one of ‘<samp>single</samp>’, ‘<samp>negative</samp>’,
|
||
|
|
‘<samp>multigot</samp>’ or ‘<samp>target</samp>’. For more information refer to the
|
||
|
|
Info entry for <samp>ld</samp>.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
|
||
|
|
<a name="Options-specific-to-MIPS-targets"></a>
|
||
|
|
<h4 class="subsection">2.1.6 Options specific to MIPS targets</h4>
|
||
|
|
|
||
|
|
|
||
|
|
<p>The following options are supported to control microMIPS instruction
|
||
|
|
generation and branch relocation checks for ISA mode transitions when
|
||
|
|
linking for MIPS targets.
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dd>
|
||
|
|
<a name="index-_002d_002dinsn32"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--insn32</code></dt>
|
||
|
|
<dd><a name="index-_002d_002dno_002dinsn32"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--no-insn32</code></dt>
|
||
|
|
<dd><p>These options control the choice of microMIPS instructions used in code
|
||
|
|
generated by the linker, such as that in the PLT or lazy binding stubs,
|
||
|
|
or in relaxation. If ‘<samp>--insn32</samp>’ is used, then the linker only uses
|
||
|
|
32-bit instruction encodings. By default or if ‘<samp>--no-insn32</samp>’ is
|
||
|
|
used, all instruction encodings are used, including 16-bit ones where
|
||
|
|
possible.
|
||
|
|
</p>
|
||
|
|
<a name="index-_002d_002dignore_002dbranch_002disa"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--ignore-branch-isa</code></dt>
|
||
|
|
<dd><a name="index-_002d_002dno_002dignore_002dbranch_002disa"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><code>--no-ignore-branch-isa</code></dt>
|
||
|
|
<dd><p>These options control branch relocation checks for invalid ISA mode
|
||
|
|
transitions. If ‘<samp>--ignore-branch-isa</samp>’ is used, then the linker
|
||
|
|
accepts any branch relocations and any ISA mode transition required
|
||
|
|
is lost in relocation calculation, except for some cases of <code>BAL</code>
|
||
|
|
instructions which meet relaxation conditions and are converted to
|
||
|
|
equivalent <code>JALX</code> instructions as the associated relocation is
|
||
|
|
calculated. By default or if ‘<samp>--no-ignore-branch-isa</samp>’ is used
|
||
|
|
a check is made causing the loss of an ISA mode transition to produce
|
||
|
|
an error.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Next: <a href="Environment.html#Environment" accesskey="n" rel="next">Environment</a>, Up: <a href="Invocation.html#Invocation" accesskey="u" rel="up">Invocation</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="LD-Index.html#LD-Index" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|