| <html lang="en"> |
| <head> |
| <title>dlltool - GNU Binary Utilities</title> |
| <meta http-equiv="Content-Type" content="text/html"> |
| <meta name="description" content="GNU Binary Utilities"> |
| <meta name="generator" content="makeinfo 4.13"> |
| <link title="Top" rel="start" href="index.html#Top"> |
| <link rel="prev" href="windres.html#windres" title="windres"> |
| <link rel="next" href="readelf.html#readelf" title="readelf"> |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> |
| <!-- |
| Copyright (C) 1991-2019 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 |
| or any later version published by the Free Software Foundation; |
| with no Invariant Sections, with no Front-Cover Texts, and with no |
| Back-Cover Texts. A copy of the license is included in the |
| section entitled ``GNU Free Documentation License''. |
| |
| --> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <style type="text/css"><!-- |
| pre.display { font-family:inherit } |
| pre.format { font-family:inherit } |
| pre.smalldisplay { font-family:inherit; font-size:smaller } |
| pre.smallformat { font-family:inherit; font-size:smaller } |
| pre.smallexample { font-size:smaller } |
| pre.smalllisp { font-size:smaller } |
| span.sc { font-variant:small-caps } |
| span.roman { font-family:serif; font-weight:normal; } |
| span.sansserif { font-family:sans-serif; font-weight:normal; } |
| --></style> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="dlltool"></a> |
| <p> |
| Next: <a rel="next" accesskey="n" href="readelf.html#readelf">readelf</a>, |
| Previous: <a rel="previous" accesskey="p" href="windres.html#windres">windres</a>, |
| Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a> |
| <hr> |
| </div> |
| |
| <h2 class="chapter">13 dlltool</h2> |
| |
| <p><a name="index-DLL-148"></a><a name="index-dlltool-149"></a> |
| <samp><span class="command">dlltool</span></samp> is used to create the files needed to create dynamic |
| link libraries (DLLs) on systems which understand PE format image |
| files such as Windows. A DLL contains an export table which contains |
| information that the runtime loader needs to resolve references from a |
| referencing program. |
| |
| <p>The export table is generated by this program by reading in a |
| <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 |
| will be in the DLL. A <samp><span class="file">.o</span></samp> file can contain information in |
| special ‘<samp><span class="samp">.drectve</span></samp>’ sections with export information. |
| |
| <blockquote> |
| <em>Note:</em> <samp><span class="command">dlltool</span></samp> is not always built as part of the |
| binary utilities, since it is only useful for those targets which |
| support DLLs. |
| </blockquote> |
| |
| <!-- man title dlltool create files needed to build and use DLLs --> |
| <pre class="smallexample"> <!-- man begin SYNOPSIS dlltool --> |
| dlltool [<samp><span class="option">-d</span></samp>|<samp><span class="option">--input-def</span></samp> <var>def-file-name</var>] |
| [<samp><span class="option">-b</span></samp>|<samp><span class="option">--base-file</span></samp> <var>base-file-name</var>] |
| [<samp><span class="option">-e</span></samp>|<samp><span class="option">--output-exp</span></samp> <var>exports-file-name</var>] |
| [<samp><span class="option">-z</span></samp>|<samp><span class="option">--output-def</span></samp> <var>def-file-name</var>] |
| [<samp><span class="option">-l</span></samp>|<samp><span class="option">--output-lib</span></samp> <var>library-file-name</var>] |
| [<samp><span class="option">-y</span></samp>|<samp><span class="option">--output-delaylib</span></samp> <var>library-file-name</var>] |
| [<samp><span class="option">--export-all-symbols</span></samp>] [<samp><span class="option">--no-export-all-symbols</span></samp>] |
| [<samp><span class="option">--exclude-symbols</span></samp> <var>list</var>] |
| [<samp><span class="option">--no-default-excludes</span></samp>] |
| [<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>] |
| [<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>] |
| [<samp><span class="option">-a</span></samp>|<samp><span class="option">--add-indirect</span></samp>] |
| [<samp><span class="option">-U</span></samp>|<samp><span class="option">--add-underscore</span></samp>] [<samp><span class="option">--add-stdcall-underscore</span></samp>] |
| [<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>] |
| [<samp><span class="option">-p</span></samp>|<samp><span class="option">--ext-prefix-alias</span></samp> <var>prefix</var>] |
| [<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>] |
| [<samp><span class="option">--use-nul-prefixed-import-tables</span></samp>] |
| [<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>] |
| [<samp><span class="option">-i</span></samp>|<samp><span class="option">--interwork</span></samp>] |
| [<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>] |
| [<samp><span class="option">-v</span></samp>|<samp><span class="option">--verbose</span></samp>] |
| [<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>] |
| [<samp><span class="option">--no-leading-underscore</span></samp>] [<samp><span class="option">--leading-underscore</span></samp>] |
| [object-file ...] |
| <!-- man end --> |
| </pre> |
| <!-- man begin DESCRIPTION dlltool --> |
| <p><samp><span class="command">dlltool</span></samp> reads its inputs, which can come from the <samp><span class="option">-d</span></samp> and |
| <samp><span class="option">-b</span></samp> options as well as object files specified on the command |
| line. It then processes these inputs and if the <samp><span class="option">-e</span></samp> option has |
| been specified it creates a exports file. If the <samp><span class="option">-l</span></samp> option |
| has been specified it creates a library file and if the <samp><span class="option">-z</span></samp> option |
| has been specified it creates a def file. Any or all of the <samp><span class="option">-e</span></samp>, |
| <samp><span class="option">-l</span></samp> and <samp><span class="option">-z</span></samp> options can be present in one invocation of |
| dlltool. |
| |
| <p>When creating a DLL, along with the source for the DLL, it is necessary |
| to have three other files. <samp><span class="command">dlltool</span></samp> can help with the creation of |
| these files. |
| |
| <p>The first file is a <samp><span class="file">.def</span></samp> file which specifies which functions are |
| exported from the DLL, which functions the DLL imports, and so on. This |
| is a text file and can be created by hand, or <samp><span class="command">dlltool</span></samp> can be used |
| to create it using the <samp><span class="option">-z</span></samp> option. In this case <samp><span class="command">dlltool</span></samp> |
| will scan the object files specified on its command line looking for |
| those functions which have been specially marked as being exported and |
| put entries for them in the <samp><span class="file">.def</span></samp> file it creates. |
| |
| <p>In order to mark a function as being exported from a DLL, it needs to |
| have an <samp><span class="option">-export:<name_of_function></span></samp> entry in the ‘<samp><span class="samp">.drectve</span></samp>’ |
| section of the object file. This can be done in C by using the |
| asm() operator: |
| |
| <pre class="smallexample"> asm (".section .drectve"); |
| asm (".ascii \"-export:my_func\""); |
| |
| int my_func (void) { ... } |
| </pre> |
| <p>The second file needed for DLL creation is an exports file. This file |
| is linked with the object files that make up the body of the DLL and it |
| handles the interface between the DLL and the outside world. This is a |
| binary file and it can be created by giving the <samp><span class="option">-e</span></samp> option to |
| <samp><span class="command">dlltool</span></samp> when it is creating or reading in a <samp><span class="file">.def</span></samp> file. |
| |
| <p>The third file needed for DLL creation is the library file that programs |
| will link with in order to access the functions in the DLL (an `import |
| library'). This file can be created by giving the <samp><span class="option">-l</span></samp> option to |
| dlltool when it is creating or reading in a <samp><span class="file">.def</span></samp> file. |
| |
| <p>If the <samp><span class="option">-y</span></samp> option is specified, dlltool generates a delay-import |
| library that can be used instead of the normal import library to allow |
| a program to link to the dll only as soon as an imported function is |
| called for the first time. The resulting executable will need to be |
| linked to the static delayimp library containing __delayLoadHelper2(), |
| which in turn will import LoadLibraryA and GetProcAddress from kernel32. |
| |
| <p><samp><span class="command">dlltool</span></samp> builds the library file by hand, but it builds the |
| exports file by creating temporary files containing assembler statements |
| and then assembling these. The <samp><span class="option">-S</span></samp> command-line option can be |
| used to specify the path to the assembler that dlltool will use, |
| and the <samp><span class="option">-f</span></samp> option can be used to pass specific flags to that |
| assembler. The <samp><span class="option">-n</span></samp> can be used to prevent dlltool from deleting |
| these temporary assembler files when it is done, and if <samp><span class="option">-n</span></samp> is |
| specified twice then this will prevent dlltool from deleting the |
| temporary object files it used to build the library. |
| |
| <p>Here is an example of creating a DLL from a source file ‘<samp><span class="samp">dll.c</span></samp>’ and |
| also creating a program (from an object file called ‘<samp><span class="samp">program.o</span></samp>’) |
| that uses that DLL: |
| |
| <pre class="smallexample"> gcc -c dll.c |
| dlltool -e exports.o -l dll.lib dll.o |
| gcc dll.o exports.o -o dll.dll |
| gcc program.o dll.lib -o program |
| </pre> |
| <p><samp><span class="command">dlltool</span></samp> may also be used to query an existing import library |
| to determine the name of the DLL to which it is associated. See the |
| description of the <samp><span class="option">-I</span></samp> or <samp><span class="option">--identify</span></samp> option. |
| |
| <!-- man end --> |
| <!-- man begin OPTIONS dlltool --> |
| <p>The command-line options have the following meanings: |
| |
| <dl> |
| <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-150"></a>Specifies the name of a <samp><span class="file">.def</span></samp> file to be read in and processed. |
| |
| <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-151"></a>Specifies the name of a base file to be read in and processed. The |
| contents of this file will be added to the relocation section in the |
| exports file generated by dlltool. |
| |
| <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. |
| |
| <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. |
| |
| <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. |
| |
| <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. |
| |
| <br><dt><samp><span class="env">--export-all-symbols</span></samp><dd>Treat all global and weak defined symbols found in the input object |
| files as symbols to be exported. There is a small list of symbols which |
| are not exported by default; see the <samp><span class="option">--no-default-excludes</span></samp> |
| option. You may add to the list of symbols to not export by using the |
| <samp><span class="option">--exclude-symbols</span></samp> option. |
| |
| <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 |
| ‘<samp><span class="samp">.drectve</span></samp>’ sections in the input object files. This is the default |
| behaviour. The ‘<samp><span class="samp">.drectve</span></samp>’ sections are created by ‘<samp><span class="samp">dllexport</span></samp>’ |
| attributes in the source code. |
| |
| <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 |
| separated by comma or colon characters. The symbol names should not |
| contain a leading underscore. This is only meaningful when |
| <samp><span class="option">--export-all-symbols</span></samp> is used. |
| |
| <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 |
| exporting certain special symbols. The current list of symbols to avoid |
| exporting is ‘<samp><span class="samp">DllMain@12</span></samp>’, ‘<samp><span class="samp">DllEntryPoint@0</span></samp>’, |
| ‘<samp><span class="samp">impure_ptr</span></samp>’. You may use the <samp><span class="option">--no-default-excludes</span></samp> option |
| to go ahead and export these special symbols. This is only meaningful |
| when <samp><span class="option">--export-all-symbols</span></samp> is used. |
| |
| <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 |
| to create the exports file. |
| |
| <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 |
| assembler when building the exports file. This option will work even if |
| the <samp><span class="option">-S</span></samp> option is not used. This option only takes one argument, |
| and if it occurs more than once on the command line, then later |
| occurrences will override earlier occurrences. So if it is necessary to |
| pass multiple options to the assembler they should be enclosed in |
| double quotes. |
| |
| <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 |
| the DLL when the <samp><span class="option">-e</span></samp> option is used. If this option is not |
| present, then the filename given to the <samp><span class="option">-e</span></samp> option will be |
| used as the name of the DLL. |
| |
| <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 |
| built. <samp><span class="command">dlltool</span></samp> has a built in default type, depending upon how |
| it was created, but this option can be used to override that. This is |
| normally only useful when creating DLLs for an ARM processor, when the |
| contents of the DLL are actually encode using Thumb instructions. |
| |
| <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 |
| should add a section which allows the exported functions to be |
| referenced without using the import library. Whatever the hell that |
| means! |
| |
| <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 |
| should prepend an underscore to the names of <em>all</em> exported symbols. |
| |
| <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 |
| not. |
| |
| <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 |
| should prepend an underscore to the names of exported <em>stdcall</em> |
| functions. Variable names and non-stdcall function names are not modified. |
| This option is useful when creating GNU-compatible import libs for third |
| party DLLs that were built with MS-Windows tools. |
| |
| <br><dt><samp><span class="env">-k</span></samp><dt><samp><span class="env">--kill-at</span></samp><dd>Specifies that ‘<samp><span class="samp">@<number></span></samp>’ suffixes should be omitted from the names |
| of stdcall functions that will be imported from the DLL. This is |
| useful when creating an import library for a DLL which exports stdcall |
| functions but without the usual ‘<samp><span class="samp">@<number></span></samp>’ symbol name suffix. |
| |
| <p>This does not change the naming of symbols provided by the import library |
| to programs linked against it, but only the entries in the import table |
| (ie the .idata section). |
| |
| <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 |
| should add aliases for stdcall symbols without ‘<samp><span class="samp">@ <number></span></samp>’ |
| in addition to the symbols with ‘<samp><span class="samp">@ <number></span></samp>’. |
| |
| <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 |
| imports with the specified prefix. The aliases are created for both |
| external and import symbols with no leading underscore. |
| |
| <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 |
| files it should omit the <code>.idata4</code> section. This is for compatibility |
| with certain operating systems. |
| |
| <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 |
| files it should prefix the <code>.idata4</code> and <code>.idata5</code> by zero an |
| element. This emulates old gnu import library generation of |
| <code>dlltool</code>. By default this option is turned off. |
| |
| <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 |
| files it should omit the <code>.idata5</code> section. This is for compatibility |
| with certain operating systems. |
| |
| <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 |
| indicated by <var>filename</var> and report, on <code>stdout</code>, the name(s) |
| of the associated DLL(s). This can be performed in addition to any |
| other operations indicated by the other options and arguments. |
| <samp><span class="command">dlltool</span></samp> fails if the import library does not exist or is not |
| actually an import library. See also <samp><span class="option">--identify-strict</span></samp>. |
| |
| <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 |
| that an error is reported if <var>filename</var> is associated with |
| more than one DLL. |
| |
| <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 |
| file and exports file that it produces as supporting interworking |
| between ARM and Thumb code. |
| |
| <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 |
| create the exports file. If this option is repeated then dlltool will |
| also preserve the temporary object files it uses to create the library |
| file. |
| |
| <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 |
| temporary assembler and object files. By default, the temp file prefix |
| is generated from the pid. |
| |
| <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. |
| |
| <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. |
| |
| <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. |
| |
| </dl> |
| |
| <!-- man end --> |
| <ul class="menu"> |
| <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 |
| </ul> |
| |
| </body></html> |
| |
