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