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