options.html

gcc手册

object files.  The <small>GNU</small> linker uses other mechanisms for this
purpose: the <code>-b</code>, <code>--format</code>, <code>--oformat</code> options, the
<code>TARGET</code> command in linker scripts, and the <code>GNUTARGET</code>
environment variable.  The <small>GNU</small> linker will ignore the <code>-F</code>
option when not creating an ELF shared object.

     <br><dt><code>-fini </code><var>name</var><code></code>
     <dd>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.

     <br><dt><code>-g</code>
     <dd>Ignored.  Provided for compatibility with other tools.

     <br><dt><code>-G</code><var>value</var><code></code>
     <dd><dt><code>--gpsize=</code><var>value</var><code></code>
     <dd>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 ECOFF which supports putting large and small objects into different
sections.  This is ignored for other object file formats.

     <br><dt><code>-h</code><var>name</var><code></code>
     <dd><dt><code>-soname=</code><var>name</var><code></code>
     <dd>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.

     <br><dt><code>-i</code>
     <dd>Perform an incremental link (same as option <code>-r</code>).

     <br><dt><code>-init </code><var>name</var><code></code>
     <dd>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.

     <br><dt><code>-l</code><var>archive</var><code></code>
     <dd><dt><code>--library=</code><var>archive</var><code></code>
     <dd>Add archive file <var>archive</var> to the list of files to link.  This
option may be used any number of times.  <code>ld</code> will search its
path-list for occurrences of <code>lib</code><var>archive</var><code>.a</code> for every
<var>archive</var> specified.

     <p>On systems which support shared libraries, <code>ld</code> may also search for
libraries with extensions other than <code>.a</code>.  Specifically, on ELF
and SunOS systems, <code>ld</code> will search a directory for a library with
an extension of <code>.so</code> before searching for one with an extension of
<code>.a</code>.  By convention, a <code>.so</code> extension indicates a shared
library.

     <p>The linker will search an archive only once, at the location where it is
specified on the command line.  If the archive defines a symbol which
was undefined in some object which appeared before the archive on the
command line, the linker will include the appropriate file(s) from the
archive.  However, an undefined symbol in an object appearing later on
the command line will not cause the linker to search the archive again.

     <p>See the <code>-(</code> option for a way to force the linker to search
archives multiple times.

     <p>You may list the same archive multiple times on the command line.

     <p>This type of archive searching is standard for Unix linkers.  However,
if you are using <code>ld</code> on AIX, note that it is different from the
behaviour of the AIX linker.

     <br><dt><code>-L</code><var>searchdir</var><code></code>
     <dd><dt><code>--library-path=</code><var>searchdir</var><code></code>
     <dd>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
<code>-L</code> options apply to all <code>-l</code> options, regardless of the
order in which the options appear.

     <p>The default set of paths searched (without being specified with
<code>-L</code>) 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>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.

     <br><dt><code>-m</code><var>emulation</var><code></code>
     <dd>Emulate the <var>emulation</var> linker.  You can list the available
emulations with the <code>--verbose</code> or <code>-V</code> options.

     <p>If the <code>-m</code> option is not used, the emulation is taken from the
<code>LDEMULATION</code> environment variable, if that is defined.

     <p>Otherwise, the default emulation depends upon how the linker was
configured.

     <br><dt><code>-M</code>
     <dd><dt><code>--print-map</code>
     <dd>Print a link map to the standard output.  A link map provides
information about the link, including the following:

          <ul>
<li>Where object files and symbols are mapped into memory. 
<li>How common symbols are allocated. 
<li>All archive members included in the link, with a mention of the symbol
which caused the archive member to be brought in. 
</ul>

     <br><dt><code>-n</code>
     <dd><dt><code>--nmagic</code>
     <dd>Turn off page alignment of sections, and mark the output as
<code>NMAGIC</code> if possible.

     <br><dt><code>-N</code>
     <dd><dt><code>--omagic</code>
     <dd>Set the text and data sections to be readable and writable.  Also, do
not page-align the data segment.  If the output format supports Unix
style magic numbers, mark the output as <code>OMAGIC</code>.

     <br><dt><code>-o </code><var>output</var><code></code>
     <dd><dt><code>--output=</code><var>output</var><code></code>
     <dd>Use <var>output</var> as the name for the program produced by <code>ld</code>; if this
option is not specified, the name <code>a.out</code> is used by default.  The
script command <code>OUTPUT</code> can also specify the output file name.

     <br><dt><code>-O </code><var>level</var><code></code>
     <dd>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.

     <br><dt><code>-q</code>
     <dd><dt><code>--emit-relocs</code>
     <dd>Leave relocation sections and contents in fully linked exececutables. 
Post link analysis and optimization tools may need this information in
order to perform correct modifications of executables.  This results
in larger executables.

     <p>This option is currently only supported on ELF platforms.

     <br><dt><code>-r</code>
     <dd><dt><code>--relocateable</code>
     <dd>Generate relocatable output--i.e., generate an output file that can in
turn serve as input to <code>ld</code>.  This is often called <dfn>partial
linking</dfn>.  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 <code>-Ur</code>.

     <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>This option does the same thing as <code>-i</code>.

     <br><dt><code>-R </code><var>filename</var><code></code>
     <dd><dt><code>--just-symbols=</code><var>filename</var><code></code>
     <dd>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>For compatibility with other ELF linkers, if the <code>-R</code> option is
followed by a directory name, rather than a file name, it is treated as
the <code>-rpath</code> option.

     <br><dt><code>-s</code>
     <dd><dt><code>--strip-all</code>
     <dd>Omit all symbol information from the output file.

     <br><dt><code>-S</code>
     <dd><dt><code>--strip-debug</code>
     <dd>Omit debugger symbol information (but not all symbols) from the output file.

     <br><dt><code>-t</code>
     <dd><dt><code>--trace</code>
     <dd>Print the names of the input files as <code>ld</code> processes them.

     <br><dt><code>-T </code><var>scriptfile</var><code></code>
     <dd><dt><code>--script=</code><var>scriptfile</var><code></code>
     <dd>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 <code>-L</code> options.  Multiple <code>-T</code>
options accumulate.

     <br><dt><code>-u </code><var>symbol</var><code></code>
     <dd><dt><code>--undefined=</code><var>symbol</var><code></code>
     <dd>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.  <code>-u</code> may be repeated with
different option arguments to enter additional undefined symbols.  This
option is equivalent to the <code>EXTERN</code> linker script command.

     <br><dt><code>-Ur</code>
     <dd>For anything other than C++ programs, this option is equivalent to
<code>-r</code>: it generates relocatable output--i.e., an output file that can in
turn serve as input to <code>ld</code>.  When linking C++ programs, <code>-Ur</code>
<em>does</em> resolve references to constructors, unlike <code>-r</code>. 
It does not work to use <code>-Ur</code> on files that were themselves linked
with <code>-Ur</code>; once the constructor table has been built, it cannot
be added to.  Use <code>-Ur</code> only for the last partial link, and
<code>-r</code> for the others.

     <br><dt><code>--unique[=</code><var>SECTION</var><code>]</code>
     <dd>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.

     <br><dt><code>-v</code>
     <dd><dt><code>--version</code>
     <dd><dt><code>-V</code>
     <dd>Display the version number for <code>ld</code>.  The <code>-V</code> option also
lists the supported emulations.

     <br><dt><code>-x</code>
     <dd><dt><code>--discard-all</code>
     <dd>Delete all local symbols.

     <br><dt><code>-X</code>
     <dd><dt><code>--discard-locals</code>
     <dd>Delete all temporary local symbols.  For most targets, this is all local
symbols whose names begin with <code>L</code>.

     <br><dt><code>-y </code><var>symbol</var><code></code>
     <dd><dt><code>--trace-symbol=</code><var>symbol</var><code></code>
     <dd>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