316 lines
23 KiB
HTML
316 lines
23 KiB
HTML
<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>
|
|
|