options.html

gcc手册

          <dd>A common symbol.  If there are only (one or more) common symbols for a
variable, it goes in the uninitialized data area of the output file. 
The linker merges multiple common symbols for the same variable into a
single symbol.  If they are of different sizes, it picks the largest
size.  The linker turns a common symbol into a declaration, if there is
a definition of the same variable. 
</dl>

     <p>The <code>--warn-common</code> 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.

          <ol type=1 start=1>
<li>Turning a common symbol into a reference, because there is already a
definition for the symbol.
          <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>

          <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.
          <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>

          <li>Merging a common symbol with a previous same-sized common symbol.
          <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>

          <li>Merging a common symbol with a previous larger common symbol.
          <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>

          <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.
          <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>
          </ol>

     <br><dt><code>--warn-constructors</code>
     <dd>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.

     <br><dt><code>--warn-multiple-gp</code>
     <dd>Warn if multiple global pointer values are required in the output file. 
This is only meaningful for certain processors, such as the Alpha. 
Specifically, some processors put large-valued constants in a special
section.  A special register (the global pointer) points into the middle
of this section, so that constants can be loaded efficiently via a
base-register relative addressing mode.  Since the offset in
base-register relative mode is fixed and relatively small (e.g., 16
bits), this limits the maximum size of the constant pool.  Thus, in
large programs, it is often necessary to use multiple global pointer
values in order to be able to address all possible constants.  This
option causes a warning to be issued whenever this case occurs.

     <br><dt><code>--warn-once</code>
     <dd>Only warn once for each undefined symbol, rather than once per module
which refers to it.

     <br><dt><code>--warn-section-align</code>
     <dd>Warn if the address of an output section is changed because of
alignment.  Typically, the alignment will be set by an input section. 
The address will only be changed if it not explicitly specified; that
is, if the <code>SECTIONS</code> command does not specify a start address for
the section (see <a href="SECTIONS.html#SECTIONS">SECTIONS</a>).

     <br><dt><code>--whole-archive</code>
     <dd>For each archive mentioned on the command line after the
<code>--whole-archive</code> option, include every object file in the archive
in the link, rather than searching the archive for the required object
files.  This is normally used to turn an archive file into a shared
library, forcing every object to be included in the resulting shared
library.  This option may be used more than once.

     <p>Two notes when using this option from gcc: First, gcc doesn't know
about this option, so you have to use <code>-Wl,-whole-archive</code>. 
Second, don't forget to use <code>-Wl,-no-whole-archive</code> 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.

     <br><dt><code>--wrap </code><var>symbol</var><code></code>
     <dd>Use a wrapper function for <var>symbol</var>.  Any undefined reference to
<var>symbol</var> will be resolved to <code>__wrap_</code><var>symbol</var><code></code>.  Any
undefined reference to <code>__real_</code><var>symbol</var><code></code> will be resolved to
<var>symbol</var>.

     <p>This can be used to provide a wrapper for a system function.  The
wrapper function should be called <code>__wrap_</code><var>symbol</var><code></code>.  If it
wishes to call the system function, it should call
<code>__real_</code><var>symbol</var><code></code>.

     <p>Here is a trivial example:

     <pre class="smallexample">          void *
          __wrap_malloc (int c)
          {
            printf ("malloc called with %ld\n", c);
            return __real_malloc (c);
          }
          </pre>

     <p>If you link other code with this file using <code>--wrap malloc</code>, 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>You may wish to provide a <code>__real_malloc</code> function as well, so that
links without the <code>--wrap</code> 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>.

     <br><dt><code>--enable-new-dtags</code>
     <dd><dt><code>--disable-new-dtags</code>
     <dd>This linker can create the new dynamic tags in ELF. But the older ELF
systems may not understand them. If you specify
<code>--enable-new-dtags</code>, the dynamic tags will be created as needed. 
If you specify <code>--disable-new-dtags</code>, 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.

   </dl>

<h4 class="subsection">Options specific to i386 PE targets</h4>

   <p>The i386 PE linker supports the <code>-shared</code> 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>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.

     <dl>

     <br><dt><code>--add-stdcall-alias</code>
     <dd>If given, symbols with a stdcall suffix (@<var>nn</var>) will be exported
as-is and also with the suffix stripped.

     <br><dt><code>--base-file </code><var>file</var><code></code>
     <dd>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
<code>dlltool</code>.

     <br><dt><code>--dll</code>
     <dd>Create a DLL instead of a regular executable.  You may also use
<code>-shared</code> or specify a <code>LIBRARY</code> in a given <code>.def</code>
file.

     <br><dt><code>--enable-stdcall-fixup</code>
     <dd><dt><code>--disable-stdcall-fixup</code>
     <dd>If the link finds a symbol that it cannot resolve, it will attempt to
do "fuzzy linking" by looking for another defined symbol that differs
only in the format of the symbol name (cdecl vs stdcall) and will
resolve that symbol by linking to the match.  For example, the
undefined symbol <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 <code>--enable-stdcall-fixup</code>, this
feature is fully enabled and warnings are not printed.  If you specify
<code>--disable-stdcall-fixup</code>, this feature is disabled and such
mismatches are considered to be errors.

     <br><dt><code>--export-all-symbols</code>
     <dd>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>.

     <br><dt><code>--exclude-symbols </code><var>symbol</var><code>,</code><var>symbol</var><code>,...</code>
     <dd>Specifies a list of symbols which should not be automatically
exported.  The symbol names may be delimited by commas or colons.

     <br><dt><code>--exclude-libs </code><var>lib</var><code>,</code><var>lib</var><code>,...</code>
     <dd>Specifies a list of archive libraries from which symbols should not be automatically
exported. The library names may be delimited by commas or colons.  Specifying
<code>--exclude-libs ALL</code> excludes symbols in all archive libraries from
automatic export. Symbols explicitly listed in a .def file are still exported,
regardless of this option.

     <br><dt><code>--file-alignment</code>
     <dd>Specify the file alignment.  Sections in the file will always begin at
file offsets which are multiples of this number.  This defaults to
512.

     <br><dt><code>--heap </code><var>reserve</var><code></code>
     <dd><dt><code>--heap </code><var>reserve</var><code>,</code><var>commit</var><code></code>
     <dd>Specify the amount of memory to reserve (and optionally commit) to be
used as heap for this program.  The default is 1Mb reserved, 4K
committed.

     <br><dt><code>--image-base </code><var>value</var><code></code>
     <dd>Use <var>value</var> as the base address of your program or dll.  This is
the lowest