274 lines
18 KiB
HTML
274 lines
18 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.7">
|
||
|
|
<link title="Top" rel="start" href="index.html#Top">
|
||
|
|
<link rel="prev" href="windmc.html#windmc" title="windmc">
|
||
|
|
<link rel="next" href="Common-Options.html#Common-Options" title="Common Options">
|
||
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
||
|
|
<!--
|
||
|
|
Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
|
||
|
|
2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 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.2
|
||
|
|
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''.
|
||
|
|
|
||
|
|
man end-->
|
||
|
|
<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; }
|
||
|
|
--></style>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div class="node">
|
||
|
|
<p>
|
||
|
|
<a name="dlltool"></a>Next: <a rel="next" accesskey="n" href="Common-Options.html#Common-Options">Common Options</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="windmc.html#windmc">windmc</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
|
||
|
|
<hr><br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h2 class="chapter">14 dlltool</h2>
|
||
|
|
|
||
|
|
<p><a name="index-DLL-122"></a><a name="index-dlltool-123"></a>
|
||
|
|
<span class="command">dlltool</span> 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
|
||
|
|
<span class="file">.def</span> file or scanning the <span class="file">.a</span> and <span class="file">.o</span> files which
|
||
|
|
will be in the DLL. A <span class="file">.o</span> file can contain information in
|
||
|
|
special <span class="samp">.drectve</span> sections with export information.
|
||
|
|
|
||
|
|
<blockquote>
|
||
|
|
<em>Note:</em> <span class="command">dlltool</span> 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 [<span class="option">-d</span>|<span class="option">--input-def</span> <var>def-file-name</var>]
|
||
|
|
[<span class="option">-b</span>|<span class="option">--base-file</span> <var>base-file-name</var>]
|
||
|
|
[<span class="option">-e</span>|<span class="option">--output-exp</span> <var>exports-file-name</var>]
|
||
|
|
[<span class="option">-z</span>|<span class="option">--output-def</span> <var>def-file-name</var>]
|
||
|
|
[<span class="option">-l</span>|<span class="option">--output-lib</span> <var>library-file-name</var>]
|
||
|
|
[<span class="option">--export-all-symbols</span>] [<span class="option">--no-export-all-symbols</span>]
|
||
|
|
[<span class="option">--exclude-symbols</span> <var>list</var>]
|
||
|
|
[<span class="option">--no-default-excludes</span>]
|
||
|
|
[<span class="option">-S</span>|<span class="option">--as</span> <var>path-to-assembler</var>] [<span class="option">-f</span>|<span class="option">--as-flags</span> <var>options</var>]
|
||
|
|
[<span class="option">-D</span>|<span class="option">--dllname</span> <var>name</var>] [<span class="option">-m</span>|<span class="option">--machine</span> <var>machine</var>]
|
||
|
|
[<span class="option">-a</span>|<span class="option">--add-indirect</span>]
|
||
|
|
[<span class="option">-U</span>|<span class="option">--add-underscore</span>] [<span class="option">--add-stdcall-underscore</span>]
|
||
|
|
[<span class="option">-k</span>|<span class="option">--kill-at</span>] [<span class="option">-A</span>|<span class="option">--add-stdcall-alias</span>]
|
||
|
|
[<span class="option">-p</span>|<span class="option">--ext-prefix-alias</span> <var>prefix</var>]
|
||
|
|
[<span class="option">-x</span>|<span class="option">--no-idata4</span>] [<span class="option">-c</span>|<span class="option">--no-idata5</span>] [<span class="option">-i</span>|<span class="option">--interwork</span>]
|
||
|
|
[<span class="option">-n</span>|<span class="option">--nodelete</span>] [<span class="option">-t</span>|<span class="option">--temp-prefix</span> <var>prefix</var>]
|
||
|
|
[<span class="option">-v</span>|<span class="option">--verbose</span>]
|
||
|
|
[<span class="option">-h</span>|<span class="option">--help</span>] [<span class="option">-V</span>|<span class="option">--version</span>]
|
||
|
|
[object-file ...]
|
||
|
|
<!-- man end -->
|
||
|
|
</pre>
|
||
|
|
<!-- man begin DESCRIPTION dlltool -->
|
||
|
|
<p><span class="command">dlltool</span> reads its inputs, which can come from the <span class="option">-d</span> and
|
||
|
|
<span class="option">-b</span> options as well as object files specified on the command
|
||
|
|
line. It then processes these inputs and if the <span class="option">-e</span> option has
|
||
|
|
been specified it creates a exports file. If the <span class="option">-l</span> option
|
||
|
|
has been specified it creates a library file and if the <span class="option">-z</span> option
|
||
|
|
has been specified it creates a def file. Any or all of the <span class="option">-e</span>,
|
||
|
|
<span class="option">-l</span> and <span class="option">-z</span> 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. <span class="command">dlltool</span> can help with the creation of
|
||
|
|
these files.
|
||
|
|
|
||
|
|
<p>The first file is a <span class="file">.def</span> 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 <span class="command">dlltool</span> can be used
|
||
|
|
to create it using the <span class="option">-z</span> option. In this case <span class="command">dlltool</span>
|
||
|
|
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 <span class="file">.def</span> file it creates.
|
||
|
|
|
||
|
|
<p>In order to mark a function as being exported from a DLL, it needs to
|
||
|
|
have an <span class="option">-export:<name_of_function></span> entry in the <span class="samp">.drectve</span>
|
||
|
|
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 <span class="option">-e</span> option to
|
||
|
|
<span class="command">dlltool</span> when it is creating or reading in a <span class="file">.def</span> 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. This file
|
||
|
|
can be created by giving the <span class="option">-l</span> option to dlltool when it
|
||
|
|
is creating or reading in a <span class="file">.def</span> file.
|
||
|
|
|
||
|
|
<p><span class="command">dlltool</span> builds the library file by hand, but it builds the
|
||
|
|
exports file by creating temporary files containing assembler statements
|
||
|
|
and then assembling these. The <span class="option">-S</span> command line option can be
|
||
|
|
used to specify the path to the assembler that dlltool will use,
|
||
|
|
and the <span class="option">-f</span> option can be used to pass specific flags to that
|
||
|
|
assembler. The <span class="option">-n</span> can be used to prevent dlltool from deleting
|
||
|
|
these temporary assembler files when it is done, and if <span class="option">-n</span> 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 <span class="samp">dll.c</span> and
|
||
|
|
also creating a program (from an object file called <span class="samp">program.o</span>)
|
||
|
|
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>
|
||
|
|
<!-- man end -->
|
||
|
|
<!-- man begin OPTIONS dlltool -->
|
||
|
|
<p>The command line options have the following meanings:
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><span class="env">-d </span><var>filename</var><dt><span class="env">--input-def </span><var>filename</var><dd><a name="index-input-_002edef-file-124"></a>Specifies the name of a <span class="file">.def</span> file to be read in and processed.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-b </span><var>filename</var><dt><span class="env">--base-file </span><var>filename</var><dd><a name="index-base-files-125"></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><span class="env">-e </span><var>filename</var><dt><span class="env">--output-exp </span><var>filename</var><dd>Specifies the name of the export file to be created by dlltool.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-z </span><var>filename</var><dt><span class="env">--output-def </span><var>filename</var><dd>Specifies the name of the <span class="file">.def</span> file to be created by dlltool.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-l </span><var>filename</var><dt><span class="env">--output-lib </span><var>filename</var><dd>Specifies the name of the library file to be created by dlltool.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--export-all-symbols</span><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 <span class="option">--no-default-excludes</span>
|
||
|
|
option. You may add to the list of symbols to not export by using the
|
||
|
|
<span class="option">--exclude-symbols</span> option.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--no-export-all-symbols</span><dd>Only export symbols explicitly listed in an input <span class="file">.def</span> file or in
|
||
|
|
<span class="samp">.drectve</span> sections in the input object files. This is the default
|
||
|
|
behaviour. The <span class="samp">.drectve</span> sections are created by <span class="samp">dllexport</span>
|
||
|
|
attributes in the source code.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--exclude-symbols </span><var>list</var><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
|
||
|
|
<span class="option">--export-all-symbols</span> is used.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--no-default-excludes</span><dd>When <span class="option">--export-all-symbols</span> is used, it will by default avoid
|
||
|
|
exporting certain special symbols. The current list of symbols to avoid
|
||
|
|
exporting is <span class="samp">DllMain@12</span>, <span class="samp">DllEntryPoint@0</span>,
|
||
|
|
<span class="samp">impure_ptr</span>. You may use the <span class="option">--no-default-excludes</span> option
|
||
|
|
to go ahead and export these special symbols. This is only meaningful
|
||
|
|
when <span class="option">--export-all-symbols</span> is used.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-S </span><var>path</var><dt><span class="env">--as </span><var>path</var><dd>Specifies the path, including the filename, of the assembler to be used
|
||
|
|
to create the exports file.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-f </span><var>options</var><dt><span class="env">--as-flags </span><var>options</var><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 <span class="option">-S</span> 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><span class="env">-D </span><var>name</var><dt><span class="env">--dll-name </span><var>name</var><dd>Specifies the name to be stored in the <span class="file">.def</span> file as the name of
|
||
|
|
the DLL when the <span class="option">-e</span> option is used. If this option is not
|
||
|
|
present, then the filename given to the <span class="option">-e</span> option will be
|
||
|
|
used as the name of the DLL.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-m </span><var>machine</var><dt><span class="env">-machine </span><var>machine</var><dd>Specifies the type of machine for which the library file should be
|
||
|
|
built. <span class="command">dlltool</span> 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><span class="env">-a</span><dt><span class="env">--add-indirect</span><dd>Specifies that when <span class="command">dlltool</span> 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><span class="env">-U</span><dt><span class="env">--add-underscore</span><dd>Specifies that when <span class="command">dlltool</span> is creating the exports file it
|
||
|
|
should prepend an underscore to the names of <em>all</em> exported symbols.
|
||
|
|
|
||
|
|
<br><dt><span class="env">--add-stdcall-underscore</span><dd>Specifies that when <span class="command">dlltool</span> 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><span class="env">-k</span><dt><span class="env">--kill-at</span><dd>Specifies that when <span class="command">dlltool</span> is creating the exports file it
|
||
|
|
should not append the string <span class="samp">@ <number></span>. These numbers are
|
||
|
|
called ordinal numbers and they represent another way of accessing the
|
||
|
|
function in a DLL, other than by name.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-A</span><dt><span class="env">--add-stdcall-alias</span><dd>Specifies that when <span class="command">dlltool</span> is creating the exports file it
|
||
|
|
should add aliases for stdcall symbols without <span class="samp">@ <number></span>
|
||
|
|
in addition to the symbols with <span class="samp">@ <number></span>.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-p</span><dt><span class="env">--ext-prefix-alias </span><var>prefix</var><dd>Causes <span class="command">dlltool</span> 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><span class="env">-x</span><dt><span class="env">--no-idata4</span><dd>Specifies that when <span class="command">dlltool</span> 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><span class="env">-c</span><dt><span class="env">--no-idata5</span><dd>Specifies that when <span class="command">dlltool</span> 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><span class="env">-i</span><dt><span class="env">--interwork</span><dd>Specifies that <span class="command">dlltool</span> should mark the objects in the library
|
||
|
|
file and exports file that it produces as supporting interworking
|
||
|
|
between ARM and Thumb code.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-n</span><dt><span class="env">--nodelete</span><dd>Makes <span class="command">dlltool</span> 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><span class="env">-t </span><var>prefix</var><dt><span class="env">--temp-prefix </span><var>prefix</var><dd>Makes <span class="command">dlltool</span> 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><span class="env">-v</span><dt><span class="env">--verbose</span><dd>Make dlltool describe what it is doing.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-h</span><dt><span class="env">--help</span><dd>Displays a list of command line options and then exits.
|
||
|
|
|
||
|
|
<br><dt><span class="env">-V</span><dt><span class="env">--version</span><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 <span class="file">.def</span> file
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
</body></html>
|
||
|
|
|