1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html>
3<!-- This file documents the GNU linker LD
4(GNU Toolchain for the A-profile Architecture 10.3-2021.07 (arm-10.29))
5version 2.36.1.
6
7Copyright (C) 1991-2021 Free Software Foundation, Inc.
8
9Permission is granted to copy, distribute and/or modify this document
10under the terms of the GNU Free Documentation License, Version 1.3
11or any later version published by the Free Software Foundation;
12with no Invariant Sections, with no Front-Cover Texts, and with no
13Back-Cover Texts.  A copy of the license is included in the
14section entitled "GNU Free Documentation License". -->
15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
16<head>
17<title>LD: WIN32</title>
18
19<meta name="description" content="LD: WIN32">
20<meta name="keywords" content="LD: WIN32">
21<meta name="resource-type" content="document">
22<meta name="distribution" content="global">
23<meta name="Generator" content="makeinfo">
24<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
25<link href="index.html#Top" rel="start" title="Top">
26<link href="LD-Index.html#LD-Index" rel="index" title="LD Index">
27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
28<link href="Machine-Dependent.html#Machine-Dependent" rel="up" title="Machine Dependent">
29<link href="Xtensa.html#Xtensa" rel="next" title="Xtensa">
30<link href="TI-COFF.html#TI-COFF" rel="previous" title="TI COFF">
31<style type="text/css">
32<!--
33a.summary-letter {text-decoration: none}
34blockquote.smallquotation {font-size: smaller}
35div.display {margin-left: 3.2em}
36div.example {margin-left: 3.2em}
37div.indentedblock {margin-left: 3.2em}
38div.lisp {margin-left: 3.2em}
39div.smalldisplay {margin-left: 3.2em}
40div.smallexample {margin-left: 3.2em}
41div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
42div.smalllisp {margin-left: 3.2em}
43kbd {font-style:oblique}
44pre.display {font-family: inherit}
45pre.format {font-family: inherit}
46pre.menu-comment {font-family: serif}
47pre.menu-preformatted {font-family: serif}
48pre.smalldisplay {font-family: inherit; font-size: smaller}
49pre.smallexample {font-size: smaller}
50pre.smallformat {font-family: inherit; font-size: smaller}
51pre.smalllisp {font-size: smaller}
52span.nocodebreak {white-space:nowrap}
53span.nolinebreak {white-space:nowrap}
54span.roman {font-family:serif; font-weight:normal}
55span.sansserif {font-family:sans-serif; font-weight:normal}
56ul.no-bullet {list-style: none}
57-->
58</style>
59
60
61</head>
62
63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
64<a name="WIN32"></a>
65<div class="header">
66<p>
67Next: <a href="Xtensa.html#Xtensa" accesskey="n" rel="next">Xtensa</a>, Previous: <a href="TI-COFF.html#TI-COFF" accesskey="p" rel="previous">TI COFF</a>, Up: <a href="Machine-Dependent.html#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> &nbsp; [<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>
68</div>
69<hr>
70<a name="ld-and-WIN32-_0028cygwin_002fmingw_0029"></a>
71<h3 class="section">5.16 <code>ld</code> and WIN32 (cygwin/mingw)</h3>
72
73<p>This section describes some of the win32 specific <code>ld</code> issues.
74See <a href="Options.html#Options">Command-line Options</a> for detailed description of the
75command-line options mentioned here.
76</p>
77<dl compact="compact">
78<dd><a name="index-import-libraries"></a>
79</dd>
80<dt><em>import libraries</em></dt>
81<dd><p>The standard Windows linker creates and uses so-called import
82libraries, which contains information for linking to dll&rsquo;s.  They are
83regular static archives and are handled as any other static
84archive.  The cygwin and mingw ports of <code>ld</code> have specific
85support for creating such libraries provided with the
86&lsquo;<samp>--out-implib</samp>&rsquo; command-line option.
87</p>
88</dd>
89<dt><em>exporting DLL symbols</em></dt>
90<dd><a name="index-exporting-DLL-symbols"></a>
91<p>The cygwin/mingw <code>ld</code> has several ways to export symbols for dll&rsquo;s.
92</p>
93<dl compact="compact">
94<dt><em>using auto-export functionality</em></dt>
95<dd><a name="index-using-auto_002dexport-functionality"></a>
96<p>By default <code>ld</code> exports symbols with the auto-export functionality,
97which is controlled by the following command-line options:
98</p>
99<ul>
100<li> &ndash;export-all-symbols   [This is the default]
101</li><li> &ndash;exclude-symbols
102</li><li> &ndash;exclude-libs
103</li><li> &ndash;exclude-modules-for-implib
104</li><li> &ndash;version-script
105</li></ul>
106
107<p>When auto-export is in operation, <code>ld</code> will export all the non-local
108(global and common) symbols it finds in a DLL, with the exception of a few
109symbols known to belong to the system&rsquo;s runtime and libraries.  As it will
110often not be desirable to export all of a DLL&rsquo;s symbols, which may include
111private functions that are not part of any public interface, the command-line
112options listed above may be used to filter symbols out from the list for
113exporting.  The &lsquo;<samp>--output-def</samp>&rsquo; option can be used in order to see the
114final list of exported symbols with all exclusions taken into effect.
115</p>
116<p>If &lsquo;<samp>--export-all-symbols</samp>&rsquo; is not given explicitly on the
117command line, then the default auto-export behavior will be <em>disabled</em>
118if either of the following are true:
119</p>
120<ul>
121<li> A DEF file is used.
122</li><li> Any symbol in any object file was marked with the __declspec(dllexport) attribute.
123</li></ul>
124
125</dd>
126<dt><em>using a DEF file</em></dt>
127<dd><a name="index-using-a-DEF-file"></a>
128<p>Another way of exporting symbols is using a DEF file.  A DEF file is
129an ASCII file containing definitions of symbols which should be
130exported when a dll is created.  Usually it is named &lsquo;<samp>&lt;dll
131name&gt;.def</samp>&rsquo; and is added as any other object file to the linker&rsquo;s
132command line.  The file&rsquo;s name must end in &lsquo;<samp>.def</samp>&rsquo; or &lsquo;<samp>.DEF</samp>&rsquo;.
133</p>
134<div class="example">
135<pre class="example">gcc -o &lt;output&gt; &lt;objectfiles&gt; &lt;dll name&gt;.def
136</pre></div>
137
138<p>Using a DEF file turns off the normal auto-export behavior, unless the
139&lsquo;<samp>--export-all-symbols</samp>&rsquo; option is also used.
140</p>
141<p>Here is an example of a DEF file for a shared library called &lsquo;<samp>xyz.dll</samp>&rsquo;:
142</p>
143<div class="example">
144<pre class="example">LIBRARY &quot;xyz.dll&quot; BASE=0x20000000
145
146EXPORTS
147foo
148bar
149_bar = bar
150another_foo = abc.dll.afoo
151var1 DATA
152doo = foo == foo2
153eoo DATA == var1
154</pre></div>
155
156<p>This example defines a DLL with a non-default base address and seven
157symbols in the export table. The third exported symbol <code>_bar</code> is an
158alias for the second. The fourth symbol, <code>another_foo</code> is resolved
159by &quot;forwarding&quot; to another module and treating it as an alias for
160<code>afoo</code> exported from the DLL &lsquo;<samp>abc.dll</samp>&rsquo;. The final symbol
161<code>var1</code> is declared to be a data object. The &lsquo;<samp>doo</samp>&rsquo; symbol in
162export library is an alias of &lsquo;<samp>foo</samp>&rsquo;, which gets the string name
163in export table &lsquo;<samp>foo2</samp>&rsquo;. The &lsquo;<samp>eoo</samp>&rsquo; symbol is an data export
164symbol, which gets in export table the name &lsquo;<samp>var1</samp>&rsquo;.
165</p>
166<p>The optional <code>LIBRARY &lt;name&gt;</code> command indicates the <em>internal</em>
167name of the output DLL. If &lsquo;<samp>&lt;name&gt;</samp>&rsquo; does not include a suffix,
168the default library suffix, &lsquo;<samp>.DLL</samp>&rsquo; is appended.
169</p>
170<p>When the .DEF file is used to build an application, rather than a
171library, the <code>NAME &lt;name&gt;</code> command should be used instead of
172<code>LIBRARY</code>. If &lsquo;<samp>&lt;name&gt;</samp>&rsquo; does not include a suffix, the default
173executable suffix, &lsquo;<samp>.EXE</samp>&rsquo; is appended.
174</p>
175<p>With either <code>LIBRARY &lt;name&gt;</code> or <code>NAME &lt;name&gt;</code> the optional
176specification <code>BASE = &lt;number&gt;</code> may be used to specify a
177non-default base address for the image.
178</p>
179<p>If neither <code>LIBRARY &lt;name&gt;</code> nor  <code>NAME &lt;name&gt;</code> is specified,
180or they specify an empty string, the internal name is the same as the
181filename specified on the command line.
182</p>
183<p>The complete specification of an export symbol is:
184</p>
185<div class="example">
186<pre class="example">EXPORTS
187  ( (  ( &lt;name1&gt; [ = &lt;name2&gt; ] )
188     | ( &lt;name1&gt; = &lt;module-name&gt; . &lt;external-name&gt;))
189  [ @ &lt;integer&gt; ] [NONAME] [DATA] [CONSTANT] [PRIVATE] [== &lt;name3&gt;] ) *
190</pre></div>
191
192<p>Declares &lsquo;<samp>&lt;name1&gt;</samp>&rsquo; as an exported symbol from the DLL, or declares
193&lsquo;<samp>&lt;name1&gt;</samp>&rsquo; as an exported alias for &lsquo;<samp>&lt;name2&gt;</samp>&rsquo;; or declares
194&lsquo;<samp>&lt;name1&gt;</samp>&rsquo; as a &quot;forward&quot; alias for the symbol
195&lsquo;<samp>&lt;external-name&gt;</samp>&rsquo; in the DLL &lsquo;<samp>&lt;module-name&gt;</samp>&rsquo;.
196Optionally, the symbol may be exported by the specified ordinal
197&lsquo;<samp>&lt;integer&gt;</samp>&rsquo; alias. The optional &lsquo;<samp>&lt;name3&gt;</samp>&rsquo; is the to be used
198string in import/export table for the symbol.
199</p>
200<p>The optional keywords that follow the declaration indicate:
201</p>
202<p><code>NONAME</code>: Do not put the symbol name in the DLL&rsquo;s export table.  It
203will still be exported by its ordinal alias (either the value specified
204by the .def specification or, otherwise, the value assigned by the
205linker). The symbol name, however, does remain visible in the import
206library (if any), unless <code>PRIVATE</code> is also specified.
207</p>
208<p><code>DATA</code>: The symbol is a variable or object, rather than a function.
209The import lib will export only an indirect reference to <code>foo</code> as
210the symbol <code>_imp__foo</code> (ie, <code>foo</code> must be resolved as
211<code>*_imp__foo</code>).
212</p>
213<p><code>CONSTANT</code>: Like <code>DATA</code>, but put the undecorated <code>foo</code> as
214well as <code>_imp__foo</code> into the import library. Both refer to the
215read-only import address table&rsquo;s pointer to the variable, not to the
216variable itself. This can be dangerous. If the user code fails to add
217the <code>dllimport</code> attribute and also fails to explicitly add the
218extra indirection that the use of the attribute enforces, the
219application will behave unexpectedly.
220</p>
221<p><code>PRIVATE</code>: Put the symbol in the DLL&rsquo;s export table, but do not put
222it into the static import library used to resolve imports at link time. The
223symbol can still be imported using the <code>LoadLibrary/GetProcAddress</code>
224API at runtime or by using the GNU ld extension of linking directly to
225the DLL without an import library.
226</p>
227<p>See ld/deffilep.y in the binutils sources for the full specification of
228other DEF file statements
229</p>
230<a name="index-creating-a-DEF-file"></a>
231<p>While linking a shared dll, <code>ld</code> is able to create a DEF file
232with the &lsquo;<samp>--output-def &lt;file&gt;</samp>&rsquo; command-line option.
233</p>
234</dd>
235<dt><em>Using decorations</em></dt>
236<dd><a name="index-Using-decorations"></a>
237<p>Another way of marking symbols for export is to modify the source code
238itself, so that when building the DLL each symbol to be exported is
239declared as:
240</p>
241<div class="example">
242<pre class="example">__declspec(dllexport) int a_variable
243__declspec(dllexport) void a_function(int with_args)
244</pre></div>
245
246<p>All such symbols will be exported from the DLL.  If, however,
247any of the object files in the DLL contain symbols decorated in
248this way, then the normal auto-export behavior is disabled, unless
249the &lsquo;<samp>--export-all-symbols</samp>&rsquo; option is also used.
250</p>
251<p>Note that object files that wish to access these symbols must <em>not</em>
252decorate them with dllexport.  Instead, they should use dllimport,
253instead:
254</p>
255<div class="example">
256<pre class="example">__declspec(dllimport) int a_variable
257__declspec(dllimport) void a_function(int with_args)
258</pre></div>
259
260<p>This complicates the structure of library header files, because
261when included by the library itself the header must declare the
262variables and functions as dllexport, but when included by client
263code the header must declare them as dllimport.  There are a number
264of idioms that are typically used to do this; often client code can
265omit the __declspec() declaration completely.  See
266&lsquo;<samp>--enable-auto-import</samp>&rsquo; and &lsquo;<samp>automatic data imports</samp>&rsquo; for more
267information.
268</p></dd>
269</dl>
270
271<a name="index-automatic-data-imports"></a>
272</dd>
273<dt><em>automatic data imports</em></dt>
274<dd><p>The standard Windows dll format supports data imports from dlls only
275by adding special decorations (dllimport/dllexport), which let the
276compiler produce specific assembler instructions to deal with this
277issue.  This increases the effort necessary to port existing Un*x
278code to these platforms, especially for large
279c++ libraries and applications.  The auto-import feature, which was
280initially provided by Paul Sokolovsky, allows one to omit the
281decorations to achieve a behavior that conforms to that on POSIX/Un*x
282platforms. This feature is enabled with the &lsquo;<samp>--enable-auto-import</samp>&rsquo;
283command-line option, although it is enabled by default on cygwin/mingw.
284The &lsquo;<samp>--enable-auto-import</samp>&rsquo; option itself now serves mainly to
285suppress any warnings that are ordinarily emitted when linked objects
286trigger the feature&rsquo;s use.
287</p>
288<p>auto-import of variables does not always work flawlessly without
289additional assistance.  Sometimes, you will see this message
290</p>
291<p>&quot;variable &rsquo;&lt;var&gt;&rsquo; can&rsquo;t be auto-imported. Please read the
292documentation for ld&rsquo;s <code>--enable-auto-import</code> for details.&quot;
293</p>
294<p>The &lsquo;<samp>--enable-auto-import</samp>&rsquo; documentation explains why this error
295occurs, and several methods that can be used to overcome this difficulty.
296One of these methods is the <em>runtime pseudo-relocs</em> feature, described
297below.
298</p>
299<a name="index-runtime-pseudo_002drelocation"></a>
300<p>For complex variables imported from DLLs (such as structs or classes),
301object files typically contain a base address for the variable and an
302offset (<em>addend</em>) within the variable&ndash;to specify a particular
303field or public member, for instance.  Unfortunately, the runtime loader used
304in win32 environments is incapable of fixing these references at runtime
305without the additional information supplied by dllimport/dllexport decorations.
306The standard auto-import feature described above is unable to resolve these
307references.
308</p>
309<p>The &lsquo;<samp>--enable-runtime-pseudo-relocs</samp>&rsquo; switch allows these references to
310be resolved without error, while leaving the task of adjusting the references
311themselves (with their non-zero addends) to specialized code provided by the
312runtime environment.  Recent versions of the cygwin and mingw environments and
313compilers provide this runtime support; older versions do not.  However, the
314support is only necessary on the developer&rsquo;s platform; the compiled result will
315run without error on an older system.
316</p>
317<p>&lsquo;<samp>--enable-runtime-pseudo-relocs</samp>&rsquo; is not the default; it must be explicitly
318enabled as needed.
319</p>
320<a name="index-direct-linking-to-a-dll"></a>
321</dd>
322<dt><em>direct linking to a dll</em></dt>
323<dd><p>The cygwin/mingw ports of <code>ld</code> support the direct linking,
324including data symbols, to a dll without the usage of any import
325libraries.  This is much faster and uses much less memory than does the
326traditional import library method, especially when linking large
327libraries or applications.  When <code>ld</code> creates an import lib, each
328function or variable exported from the dll is stored in its own bfd, even
329though a single bfd could contain many exports.  The overhead involved in
330storing, loading, and processing so many bfd&rsquo;s is quite large, and explains the
331tremendous time, memory, and storage needed to link against particularly
332large or complex libraries when using import libs.
333</p>
334<p>Linking directly to a dll uses no extra command-line switches other than
335&lsquo;<samp>-L</samp>&rsquo; and &lsquo;<samp>-l</samp>&rsquo;, because <code>ld</code> already searches for a number
336of names to match each library.  All that is needed from the developer&rsquo;s
337perspective is an understanding of this search, in order to force ld to
338select the dll instead of an import library.
339</p>
340
341<p>For instance, when ld is called with the argument &lsquo;<samp>-lxxx</samp>&rsquo; it will attempt
342to find, in the first directory of its search path,
343</p>
344<div class="example">
345<pre class="example">libxxx.dll.a
346xxx.dll.a
347libxxx.a
348xxx.lib
349libxxx.lib
350cygxxx.dll (*)
351libxxx.dll
352xxx.dll
353</pre></div>
354
355<p>before moving on to the next directory in the search path.
356</p>
357<p>(*) Actually, this is not &lsquo;<samp>cygxxx.dll</samp>&rsquo; but in fact is &lsquo;<samp>&lt;prefix&gt;xxx.dll</samp>&rsquo;,
358where &lsquo;<samp>&lt;prefix&gt;</samp>&rsquo; is set by the <code>ld</code> option
359&lsquo;<samp>--dll-search-prefix=&lt;prefix&gt;</samp>&rsquo;. In the case of cygwin, the standard gcc spec
360file includes &lsquo;<samp>--dll-search-prefix=cyg</samp>&rsquo;, so in effect we actually search for
361&lsquo;<samp>cygxxx.dll</samp>&rsquo;.
362</p>
363<p>Other win32-based unix environments, such as mingw or pw32, may use other
364&lsquo;<samp>&lt;prefix&gt;</samp>&rsquo;es, although at present only cygwin makes use of this feature.  It
365was originally intended to help avoid name conflicts among dll&rsquo;s built for the
366various win32/un*x environments, so that (for example) two versions of a zlib dll
367could coexist on the same machine.
368</p>
369<p>The generic cygwin/mingw path layout uses a &lsquo;<samp>bin</samp>&rsquo; directory for
370applications and dll&rsquo;s and a &lsquo;<samp>lib</samp>&rsquo; directory for the import
371libraries (using cygwin nomenclature):
372</p>
373<div class="example">
374<pre class="example">bin/
375	cygxxx.dll
376lib/
377	libxxx.dll.a   (in case of dll's)
378	libxxx.a       (in case of static archive)
379</pre></div>
380
381<p>Linking directly to a dll without using the import library can be
382done two ways:
383</p>
384<p>1. Use the dll directly by adding the &lsquo;<samp>bin</samp>&rsquo; path to the link line
385</p><div class="example">
386<pre class="example">gcc -Wl,-verbose  -o a.exe -L../bin/ -lxxx
387</pre></div>
388
389<p>However, as the dll&rsquo;s often have version numbers appended to their names
390(&lsquo;<samp>cygncurses-5.dll</samp>&rsquo;) this will often fail, unless one specifies
391&lsquo;<samp>-L../bin -lncurses-5</samp>&rsquo; to include the version.  Import libs are generally
392not versioned, and do not have this difficulty.
393</p>
394<p>2. Create a symbolic link from the dll to a file in the &lsquo;<samp>lib</samp>&rsquo;
395directory according to the above mentioned search pattern.  This
396should be used to avoid unwanted changes in the tools needed for
397making the app/dll.
398</p>
399<div class="example">
400<pre class="example">ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
401</pre></div>
402
403<p>Then you can link without any make environment changes.
404</p>
405<div class="example">
406<pre class="example">gcc -Wl,-verbose  -o a.exe -L../lib/ -lxxx
407</pre></div>
408
409<p>This technique also avoids the version number problems, because the following is
410perfectly legal
411</p>
412<div class="example">
413<pre class="example">bin/
414	cygxxx-5.dll
415lib/
416	libxxx.dll.a -&gt; ../bin/cygxxx-5.dll
417</pre></div>
418
419<p>Linking directly to a dll without using an import lib will work
420even when auto-import features are exercised, and even when
421&lsquo;<samp>--enable-runtime-pseudo-relocs</samp>&rsquo; is used.
422</p>
423<p>Given the improvements in speed and memory usage, one might justifiably
424wonder why import libraries are used at all.  There are three reasons:
425</p>
426<p>1. Until recently, the link-directly-to-dll functionality did <em>not</em>
427work with auto-imported data.
428</p>
429<p>2. Sometimes it is necessary to include pure static objects within the
430import library (which otherwise contains only bfd&rsquo;s for indirection
431symbols that point to the exports of a dll).  Again, the import lib
432for the cygwin kernel makes use of this ability, and it is not
433possible to do this without an import lib.
434</p>
435<p>3. Symbol aliases can only be resolved using an import lib.  This is
436critical when linking against OS-supplied dll&rsquo;s (eg, the win32 API)
437in which symbols are usually exported as undecorated aliases of their
438stdcall-decorated assembly names.
439</p>
440<p>So, import libs are not going away.  But the ability to replace
441true import libs with a simple symbolic link to (or a copy of)
442a dll, in many cases, is a useful addition to the suite of tools
443binutils makes available to the win32 developer.  Given the
444massive improvements in memory requirements during linking, storage
445requirements, and linking speed, we expect that many developers
446will soon begin to use this feature whenever possible.
447</p>
448</dd>
449<dt><em>symbol aliasing</em></dt>
450<dd><dl compact="compact">
451<dt><em>adding additional names</em></dt>
452<dd><p>Sometimes, it is useful to export symbols with additional names.
453A symbol &lsquo;<samp>foo</samp>&rsquo; will be exported as &lsquo;<samp>foo</samp>&rsquo;, but it can also be
454exported as &lsquo;<samp>_foo</samp>&rsquo; by using special directives in the DEF file
455when creating the dll.  This will affect also the optional created
456import library.  Consider the following DEF file:
457</p>
458<div class="example">
459<pre class="example">LIBRARY &quot;xyz.dll&quot; BASE=0x61000000
460
461EXPORTS
462foo
463_foo = foo
464</pre></div>
465
466<p>The line &lsquo;<samp>_foo = foo</samp>&rsquo; maps the symbol &lsquo;<samp>foo</samp>&rsquo; to &lsquo;<samp>_foo</samp>&rsquo;.
467</p>
468<p>Another method for creating a symbol alias is to create it in the
469source code using the &quot;weak&quot; attribute:
470</p>
471<div class="example">
472<pre class="example">void foo () { /* Do something.  */; }
473void _foo () __attribute__ ((weak, alias (&quot;foo&quot;)));
474</pre></div>
475
476<p>See the gcc manual for more information about attributes and weak
477symbols.
478</p>
479</dd>
480<dt><em>renaming symbols</em></dt>
481<dd><p>Sometimes it is useful to rename exports.  For instance, the cygwin
482kernel does this regularly.  A symbol &lsquo;<samp>_foo</samp>&rsquo; can be exported as
483&lsquo;<samp>foo</samp>&rsquo; but not as &lsquo;<samp>_foo</samp>&rsquo; by using special directives in the
484DEF file. (This will also affect the import library, if it is
485created).  In the following example:
486</p>
487<div class="example">
488<pre class="example">LIBRARY &quot;xyz.dll&quot; BASE=0x61000000
489
490EXPORTS
491_foo = foo
492</pre></div>
493
494<p>The line &lsquo;<samp>_foo = foo</samp>&rsquo; maps the exported symbol &lsquo;<samp>foo</samp>&rsquo; to
495&lsquo;<samp>_foo</samp>&rsquo;.
496</p></dd>
497</dl>
498
499<p>Note: using a DEF file disables the default auto-export behavior,
500unless the &lsquo;<samp>--export-all-symbols</samp>&rsquo; command-line option is used.
501If, however, you are trying to rename symbols, then you should list
502<em>all</em> desired exports in the DEF file, including the symbols
503that are not being renamed, and do <em>not</em> use the
504&lsquo;<samp>--export-all-symbols</samp>&rsquo; option.  If you list only the
505renamed symbols in the DEF file, and use &lsquo;<samp>--export-all-symbols</samp>&rsquo;
506to handle the other symbols, then the both the new names <em>and</em>
507the original names for the renamed symbols will be exported.
508In effect, you&rsquo;d be aliasing those symbols, not renaming them,
509which is probably not what you wanted.
510</p>
511<a name="index-weak-externals"></a>
512</dd>
513<dt><em>weak externals</em></dt>
514<dd><p>The Windows object format, PE, specifies a form of weak symbols called
515weak externals.  When a weak symbol is linked and the symbol is not
516defined, the weak symbol becomes an alias for some other symbol.  There
517are three variants of weak externals:
518</p><ul>
519<li> Definition is searched for in objects and libraries, historically
520called lazy externals.
521</li><li> Definition is searched for only in other objects, not in libraries.
522This form is not presently implemented.
523</li><li> No search; the symbol is an alias.  This form is not presently
524implemented.
525</li></ul>
526<p>As a GNU extension, weak symbols that do not specify an alternate symbol
527are supported.  If the symbol is undefined when linking, the symbol
528uses a default value.
529</p>
530<a name="index-aligned-common-symbols"></a>
531</dd>
532<dt><em>aligned common symbols</em></dt>
533<dd><p>As a GNU extension to the PE file format, it is possible to specify the
534desired alignment for a common symbol.  This information is conveyed from
535the assembler or compiler to the linker by means of GNU-specific commands
536carried in the object file&rsquo;s &lsquo;<samp>.drectve</samp>&rsquo; section, which are recognized
537by <code>ld</code> and respected when laying out the common symbols.  Native
538tools will be able to process object files employing this GNU extension,
539but will fail to respect the alignment instructions, and may issue noisy
540warnings about unknown linker directives.
541</p>
542</dd>
543</dl>
544
545
546
547<hr>
548<div class="header">
549<p>
550Next: <a href="Xtensa.html#Xtensa" accesskey="n" rel="next">Xtensa</a>, Previous: <a href="TI-COFF.html#TI-COFF" accesskey="p" rel="previous">TI COFF</a>, Up: <a href="Machine-Dependent.html#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> &nbsp; [<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>
551</div>
552
553
554
555</body>
556</html>
557