1<html lang="en"> 2<head> 3<title>dlltool - GNU Binary Utilities</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="GNU Binary Utilities"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="prev" href="windres.html#windres" title="windres"> 9<link rel="next" href="readelf.html#readelf" title="readelf"> 10<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 11<!-- 12Copyright (C) 1991-2013 Free Software Foundation, Inc. 13 14Permission is granted to copy, distribute and/or modify this document 15under the terms of the GNU Free Documentation License, Version 1.3 16or any later version published by the Free Software Foundation; 17with no Invariant Sections, with no Front-Cover Texts, and with no 18Back-Cover Texts. A copy of the license is included in the 19section entitled ``GNU Free Documentation License''. 20 21--> 22<meta http-equiv="Content-Style-Type" content="text/css"> 23<style type="text/css"><!-- 24 pre.display { font-family:inherit } 25 pre.format { font-family:inherit } 26 pre.smalldisplay { font-family:inherit; font-size:smaller } 27 pre.smallformat { font-family:inherit; font-size:smaller } 28 pre.smallexample { font-size:smaller } 29 pre.smalllisp { font-size:smaller } 30 span.sc { font-variant:small-caps } 31 span.roman { font-family:serif; font-weight:normal; } 32 span.sansserif { font-family:sans-serif; font-weight:normal; } 33--></style> 34<link rel="stylesheet" type="text/css" href="../cs.css"> 35</head> 36<body> 37<div class="node"> 38<a name="dlltool"></a> 39<p> 40Next: <a rel="next" accesskey="n" href="readelf.html#readelf">readelf</a>, 41Previous: <a rel="previous" accesskey="p" href="windres.html#windres">windres</a>, 42Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a> 43<hr> 44</div> 45 46<h2 class="chapter">14 dlltool</h2> 47 48<p><a name="index-DLL-143"></a><a name="index-dlltool-144"></a> 49<samp><span class="command">dlltool</span></samp> is used to create the files needed to create dynamic 50link libraries (DLLs) on systems which understand PE format image 51files such as Windows. A DLL contains an export table which contains 52information that the runtime loader needs to resolve references from a 53referencing program. 54 55 <p>The export table is generated by this program by reading in a 56<samp><span class="file">.def</span></samp> file or scanning the <samp><span class="file">.a</span></samp> and <samp><span class="file">.o</span></samp> files which 57will be in the DLL. A <samp><span class="file">.o</span></samp> file can contain information in 58special ‘<samp><span class="samp">.drectve</span></samp>’ sections with export information. 59 60 <blockquote> 61<em>Note:</em> <samp><span class="command">dlltool</span></samp> is not always built as part of the 62binary utilities, since it is only useful for those targets which 63support DLLs. 64</blockquote> 65 66<!-- man title dlltool Create files needed to build and use DLLs. --> 67<pre class="smallexample"> <!-- man begin SYNOPSIS dlltool --> 68 dlltool [<samp><span class="option">-d</span></samp>|<samp><span class="option">--input-def</span></samp> <var>def-file-name</var>] 69 [<samp><span class="option">-b</span></samp>|<samp><span class="option">--base-file</span></samp> <var>base-file-name</var>] 70 [<samp><span class="option">-e</span></samp>|<samp><span class="option">--output-exp</span></samp> <var>exports-file-name</var>] 71 [<samp><span class="option">-z</span></samp>|<samp><span class="option">--output-def</span></samp> <var>def-file-name</var>] 72 [<samp><span class="option">-l</span></samp>|<samp><span class="option">--output-lib</span></samp> <var>library-file-name</var>] 73 [<samp><span class="option">-y</span></samp>|<samp><span class="option">--output-delaylib</span></samp> <var>library-file-name</var>] 74 [<samp><span class="option">--export-all-symbols</span></samp>] [<samp><span class="option">--no-export-all-symbols</span></samp>] 75 [<samp><span class="option">--exclude-symbols</span></samp> <var>list</var>] 76 [<samp><span class="option">--no-default-excludes</span></samp>] 77 [<samp><span class="option">-S</span></samp>|<samp><span class="option">--as</span></samp> <var>path-to-assembler</var>] [<samp><span class="option">-f</span></samp>|<samp><span class="option">--as-flags</span></samp> <var>options</var>] 78 [<samp><span class="option">-D</span></samp>|<samp><span class="option">--dllname</span></samp> <var>name</var>] [<samp><span class="option">-m</span></samp>|<samp><span class="option">--machine</span></samp> <var>machine</var>] 79 [<samp><span class="option">-a</span></samp>|<samp><span class="option">--add-indirect</span></samp>] 80 [<samp><span class="option">-U</span></samp>|<samp><span class="option">--add-underscore</span></samp>] [<samp><span class="option">--add-stdcall-underscore</span></samp>] 81 [<samp><span class="option">-k</span></samp>|<samp><span class="option">--kill-at</span></samp>] [<samp><span class="option">-A</span></samp>|<samp><span class="option">--add-stdcall-alias</span></samp>] 82 [<samp><span class="option">-p</span></samp>|<samp><span class="option">--ext-prefix-alias</span></samp> <var>prefix</var>] 83 [<samp><span class="option">-x</span></samp>|<samp><span class="option">--no-idata4</span></samp>] [<samp><span class="option">-c</span></samp>|<samp><span class="option">--no-idata5</span></samp>] 84 [<samp><span class="option">--use-nul-prefixed-import-tables</span></samp>] 85 [<samp><span class="option">-I</span></samp>|<samp><span class="option">--identify</span></samp> <var>library-file-name</var>] [<samp><span class="option">--identify-strict</span></samp>] 86 [<samp><span class="option">-i</span></samp>|<samp><span class="option">--interwork</span></samp>] 87 [<samp><span class="option">-n</span></samp>|<samp><span class="option">--nodelete</span></samp>] [<samp><span class="option">-t</span></samp>|<samp><span class="option">--temp-prefix</span></samp> <var>prefix</var>] 88 [<samp><span class="option">-v</span></samp>|<samp><span class="option">--verbose</span></samp>] 89 [<samp><span class="option">-h</span></samp>|<samp><span class="option">--help</span></samp>] [<samp><span class="option">-V</span></samp>|<samp><span class="option">--version</span></samp>] 90 [<samp><span class="option">--no-leading-underscore</span></samp>] [<samp><span class="option">--leading-underscore</span></samp>] 91 [object-file ...] 92 <!-- man end --> 93</pre> 94 <!-- man begin DESCRIPTION dlltool --> 95 <p><samp><span class="command">dlltool</span></samp> reads its inputs, which can come from the <samp><span class="option">-d</span></samp> and 96<samp><span class="option">-b</span></samp> options as well as object files specified on the command 97line. It then processes these inputs and if the <samp><span class="option">-e</span></samp> option has 98been specified it creates a exports file. If the <samp><span class="option">-l</span></samp> option 99has been specified it creates a library file and if the <samp><span class="option">-z</span></samp> option 100has been specified it creates a def file. Any or all of the <samp><span class="option">-e</span></samp>, 101<samp><span class="option">-l</span></samp> and <samp><span class="option">-z</span></samp> options can be present in one invocation of 102dlltool. 103 104 <p>When creating a DLL, along with the source for the DLL, it is necessary 105to have three other files. <samp><span class="command">dlltool</span></samp> can help with the creation of 106these files. 107 108 <p>The first file is a <samp><span class="file">.def</span></samp> file which specifies which functions are 109exported from the DLL, which functions the DLL imports, and so on. This 110is a text file and can be created by hand, or <samp><span class="command">dlltool</span></samp> can be used 111to create it using the <samp><span class="option">-z</span></samp> option. In this case <samp><span class="command">dlltool</span></samp> 112will scan the object files specified on its command line looking for 113those functions which have been specially marked as being exported and 114put entries for them in the <samp><span class="file">.def</span></samp> file it creates. 115 116 <p>In order to mark a function as being exported from a DLL, it needs to 117have an <samp><span class="option">-export:<name_of_function></span></samp> entry in the ‘<samp><span class="samp">.drectve</span></samp>’ 118section of the object file. This can be done in C by using the 119asm() operator: 120 121<pre class="smallexample"> asm (".section .drectve"); 122 asm (".ascii \"-export:my_func\""); 123 124 int my_func (void) { ... } 125</pre> 126 <p>The second file needed for DLL creation is an exports file. This file 127is linked with the object files that make up the body of the DLL and it 128handles the interface between the DLL and the outside world. This is a 129binary file and it can be created by giving the <samp><span class="option">-e</span></samp> option to 130<samp><span class="command">dlltool</span></samp> when it is creating or reading in a <samp><span class="file">.def</span></samp> file. 131 132 <p>The third file needed for DLL creation is the library file that programs 133will link with in order to access the functions in the DLL (an `import 134library'). This file can be created by giving the <samp><span class="option">-l</span></samp> option to 135dlltool when it is creating or reading in a <samp><span class="file">.def</span></samp> file. 136 137 <p>If the <samp><span class="option">-y</span></samp> option is specified, dlltool generates a delay-import 138library that can be used instead of the normal import library to allow 139a program to link to the dll only as soon as an imported function is 140called for the first time. The resulting executable will need to be 141linked to the static delayimp library containing __delayLoadHelper2(), 142which in turn will import LoadLibraryA and GetProcAddress from kernel32. 143 144 <p><samp><span class="command">dlltool</span></samp> builds the library file by hand, but it builds the 145exports file by creating temporary files containing assembler statements 146and then assembling these. The <samp><span class="option">-S</span></samp> command line option can be 147used to specify the path to the assembler that dlltool will use, 148and the <samp><span class="option">-f</span></samp> option can be used to pass specific flags to that 149assembler. The <samp><span class="option">-n</span></samp> can be used to prevent dlltool from deleting 150these temporary assembler files when it is done, and if <samp><span class="option">-n</span></samp> is 151specified twice then this will prevent dlltool from deleting the 152temporary object files it used to build the library. 153 154 <p>Here is an example of creating a DLL from a source file ‘<samp><span class="samp">dll.c</span></samp>’ and 155also creating a program (from an object file called ‘<samp><span class="samp">program.o</span></samp>’) 156that uses that DLL: 157 158<pre class="smallexample"> gcc -c dll.c 159 dlltool -e exports.o -l dll.lib dll.o 160 gcc dll.o exports.o -o dll.dll 161 gcc program.o dll.lib -o program 162</pre> 163 <p><samp><span class="command">dlltool</span></samp> may also be used to query an existing import library 164to determine the name of the DLL to which it is associated. See the 165description of the <samp><span class="option">-I</span></samp> or <samp><span class="option">--identify</span></samp> option. 166 167<!-- man end --> 168<!-- man begin OPTIONS dlltool --> 169 <p>The command line options have the following meanings: 170 171 <dl> 172<dt><samp><span class="env">-d </span><var>filename</var></samp><dt><samp><span class="env">--input-def </span><var>filename</var></samp><dd><a name="index-input-_002edef-file-145"></a>Specifies the name of a <samp><span class="file">.def</span></samp> file to be read in and processed. 173 174 <br><dt><samp><span class="env">-b </span><var>filename</var></samp><dt><samp><span class="env">--base-file </span><var>filename</var></samp><dd><a name="index-base-files-146"></a>Specifies the name of a base file to be read in and processed. The 175contents of this file will be added to the relocation section in the 176exports file generated by dlltool. 177 178 <br><dt><samp><span class="env">-e </span><var>filename</var></samp><dt><samp><span class="env">--output-exp </span><var>filename</var></samp><dd>Specifies the name of the export file to be created by dlltool. 179 180 <br><dt><samp><span class="env">-z </span><var>filename</var></samp><dt><samp><span class="env">--output-def </span><var>filename</var></samp><dd>Specifies the name of the <samp><span class="file">.def</span></samp> file to be created by dlltool. 181 182 <br><dt><samp><span class="env">-l </span><var>filename</var></samp><dt><samp><span class="env">--output-lib </span><var>filename</var></samp><dd>Specifies the name of the library file to be created by dlltool. 183 184 <br><dt><samp><span class="env">-y </span><var>filename</var></samp><dt><samp><span class="env">--output-delaylib </span><var>filename</var></samp><dd>Specifies the name of the delay-import library file to be created by dlltool. 185 186 <br><dt><samp><span class="env">--export-all-symbols</span></samp><dd>Treat all global and weak defined symbols found in the input object 187files as symbols to be exported. There is a small list of symbols which 188are not exported by default; see the <samp><span class="option">--no-default-excludes</span></samp> 189option. You may add to the list of symbols to not export by using the 190<samp><span class="option">--exclude-symbols</span></samp> option. 191 192 <br><dt><samp><span class="env">--no-export-all-symbols</span></samp><dd>Only export symbols explicitly listed in an input <samp><span class="file">.def</span></samp> file or in 193‘<samp><span class="samp">.drectve</span></samp>’ sections in the input object files. This is the default 194behaviour. The ‘<samp><span class="samp">.drectve</span></samp>’ sections are created by ‘<samp><span class="samp">dllexport</span></samp>’ 195attributes in the source code. 196 197 <br><dt><samp><span class="env">--exclude-symbols </span><var>list</var></samp><dd>Do not export the symbols in <var>list</var>. This is a list of symbol names 198separated by comma or colon characters. The symbol names should not 199contain a leading underscore. This is only meaningful when 200<samp><span class="option">--export-all-symbols</span></samp> is used. 201 202 <br><dt><samp><span class="env">--no-default-excludes</span></samp><dd>When <samp><span class="option">--export-all-symbols</span></samp> is used, it will by default avoid 203exporting certain special symbols. The current list of symbols to avoid 204exporting is ‘<samp><span class="samp">DllMain@12</span></samp>’, ‘<samp><span class="samp">DllEntryPoint@0</span></samp>’, 205‘<samp><span class="samp">impure_ptr</span></samp>’. You may use the <samp><span class="option">--no-default-excludes</span></samp> option 206to go ahead and export these special symbols. This is only meaningful 207when <samp><span class="option">--export-all-symbols</span></samp> is used. 208 209 <br><dt><samp><span class="env">-S </span><var>path</var></samp><dt><samp><span class="env">--as </span><var>path</var></samp><dd>Specifies the path, including the filename, of the assembler to be used 210to create the exports file. 211 212 <br><dt><samp><span class="env">-f </span><var>options</var></samp><dt><samp><span class="env">--as-flags </span><var>options</var></samp><dd>Specifies any specific command line options to be passed to the 213assembler when building the exports file. This option will work even if 214the <samp><span class="option">-S</span></samp> option is not used. This option only takes one argument, 215and if it occurs more than once on the command line, then later 216occurrences will override earlier occurrences. So if it is necessary to 217pass multiple options to the assembler they should be enclosed in 218double quotes. 219 220 <br><dt><samp><span class="env">-D </span><var>name</var></samp><dt><samp><span class="env">--dll-name </span><var>name</var></samp><dd>Specifies the name to be stored in the <samp><span class="file">.def</span></samp> file as the name of 221the DLL when the <samp><span class="option">-e</span></samp> option is used. If this option is not 222present, then the filename given to the <samp><span class="option">-e</span></samp> option will be 223used as the name of the DLL. 224 225 <br><dt><samp><span class="env">-m </span><var>machine</var></samp><dt><samp><span class="env">-machine </span><var>machine</var></samp><dd>Specifies the type of machine for which the library file should be 226built. <samp><span class="command">dlltool</span></samp> has a built in default type, depending upon how 227it was created, but this option can be used to override that. This is 228normally only useful when creating DLLs for an ARM processor, when the 229contents of the DLL are actually encode using Thumb instructions. 230 231 <br><dt><samp><span class="env">-a</span></samp><dt><samp><span class="env">--add-indirect</span></samp><dd>Specifies that when <samp><span class="command">dlltool</span></samp> is creating the exports file it 232should add a section which allows the exported functions to be 233referenced without using the import library. Whatever the hell that 234means! 235 236 <br><dt><samp><span class="env">-U</span></samp><dt><samp><span class="env">--add-underscore</span></samp><dd>Specifies that when <samp><span class="command">dlltool</span></samp> is creating the exports file it 237should prepend an underscore to the names of <em>all</em> exported symbols. 238 239 <br><dt><samp><span class="env">--no-leading-underscore</span></samp><br><dt><samp><span class="env">--leading-underscore</span></samp><dd>Specifies whether standard symbol should be forced to be prefixed, or 240not. 241 242 <br><dt><samp><span class="env">--add-stdcall-underscore</span></samp><dd>Specifies that when <samp><span class="command">dlltool</span></samp> is creating the exports file it 243should prepend an underscore to the names of exported <em>stdcall</em> 244functions. Variable names and non-stdcall function names are not modified. 245This option is useful when creating GNU-compatible import libs for third 246party DLLs that were built with MS-Windows tools. 247 248 <br><dt><samp><span class="env">-k</span></samp><dt><samp><span class="env">--kill-at</span></samp><dd>Specifies that when <samp><span class="command">dlltool</span></samp> is creating the exports file it 249should not append the string ‘<samp><span class="samp">@ <number></span></samp>’. These numbers are 250called ordinal numbers and they represent another way of accessing the 251function in a DLL, other than by name. 252 253 <br><dt><samp><span class="env">-A</span></samp><dt><samp><span class="env">--add-stdcall-alias</span></samp><dd>Specifies that when <samp><span class="command">dlltool</span></samp> is creating the exports file it 254should add aliases for stdcall symbols without ‘<samp><span class="samp">@ <number></span></samp>’ 255in addition to the symbols with ‘<samp><span class="samp">@ <number></span></samp>’. 256 257 <br><dt><samp><span class="env">-p</span></samp><dt><samp><span class="env">--ext-prefix-alias </span><var>prefix</var></samp><dd>Causes <samp><span class="command">dlltool</span></samp> to create external aliases for all DLL 258imports with the specified prefix. The aliases are created for both 259external and import symbols with no leading underscore. 260 261 <br><dt><samp><span class="env">-x</span></samp><dt><samp><span class="env">--no-idata4</span></samp><dd>Specifies that when <samp><span class="command">dlltool</span></samp> is creating the exports and library 262files it should omit the <code>.idata4</code> section. This is for compatibility 263with certain operating systems. 264 265 <br><dt><samp><span class="env">--use-nul-prefixed-import-tables</span></samp><dd>Specifies that when <samp><span class="command">dlltool</span></samp> is creating the exports and library 266files it should prefix the <code>.idata4</code> and <code>.idata5</code> by zero an 267element. This emulates old gnu import library generation of 268<code>dlltool</code>. By default this option is turned off. 269 270 <br><dt><samp><span class="env">-c</span></samp><dt><samp><span class="env">--no-idata5</span></samp><dd>Specifies that when <samp><span class="command">dlltool</span></samp> is creating the exports and library 271files it should omit the <code>.idata5</code> section. This is for compatibility 272with certain operating systems. 273 274 <br><dt><samp><span class="env">-I </span><var>filename</var></samp><dt><samp><span class="env">--identify </span><var>filename</var></samp><dd>Specifies that <samp><span class="command">dlltool</span></samp> should inspect the import library 275indicated by <var>filename</var> and report, on <code>stdout</code>, the name(s) 276of the associated DLL(s). This can be performed in addition to any 277other operations indicated by the other options and arguments. 278<samp><span class="command">dlltool</span></samp> fails if the import library does not exist or is not 279actually an import library. See also <samp><span class="option">--identify-strict</span></samp>. 280 281 <br><dt><samp><span class="env">--identify-strict</span></samp><dd>Modifies the behavior of the <samp><span class="option">--identify</span></samp> option, such 282that an error is reported if <var>filename</var> is associated with 283more than one DLL. 284 285 <br><dt><samp><span class="env">-i</span></samp><dt><samp><span class="env">--interwork</span></samp><dd>Specifies that <samp><span class="command">dlltool</span></samp> should mark the objects in the library 286file and exports file that it produces as supporting interworking 287between ARM and Thumb code. 288 289 <br><dt><samp><span class="env">-n</span></samp><dt><samp><span class="env">--nodelete</span></samp><dd>Makes <samp><span class="command">dlltool</span></samp> preserve the temporary assembler files it used to 290create the exports file. If this option is repeated then dlltool will 291also preserve the temporary object files it uses to create the library 292file. 293 294 <br><dt><samp><span class="env">-t </span><var>prefix</var></samp><dt><samp><span class="env">--temp-prefix </span><var>prefix</var></samp><dd>Makes <samp><span class="command">dlltool</span></samp> use <var>prefix</var> when constructing the names of 295temporary assembler and object files. By default, the temp file prefix 296is generated from the pid. 297 298 <br><dt><samp><span class="env">-v</span></samp><dt><samp><span class="env">--verbose</span></samp><dd>Make dlltool describe what it is doing. 299 300 <br><dt><samp><span class="env">-h</span></samp><dt><samp><span class="env">--help</span></samp><dd>Displays a list of command line options and then exits. 301 302 <br><dt><samp><span class="env">-V</span></samp><dt><samp><span class="env">--version</span></samp><dd>Displays dlltool's version number and then exits. 303 304 </dl> 305 306<!-- man end --> 307<ul class="menu"> 308<li><a accesskey="1" href="def-file-format.html#def-file-format">def file format</a>: The format of the dlltool <samp><span class="file">.def</span></samp> file 309</ul> 310 311 </body></html> 312 313