1DLLTOOL(1)                   GNU Development Tools                  DLLTOOL(1)
2
3
4

NAME

6       dlltool - Create files needed to build and use DLLs.
7

SYNOPSIS

9       dlltool [-d|--input-def def-file-name]
10               [-b|--base-file base-file-name]
11               [-e|--output-exp exports-file-name]
12               [-z|--output-def def-file-name]
13               [-l|--output-lib library-file-name]
14               [-y|--output-delaylib library-file-name]
15               [--export-all-symbols] [--no-export-all-symbols]
16               [--exclude-symbols list]
17               [--no-default-excludes]
18               [-S|--as path-to-assembler] [-f|--as-flags options]
19               [-D|--dllname name] [-m|--machine machine]
20               [-a|--add-indirect]
21               [-U|--add-underscore] [--add-stdcall-underscore]
22               [-k|--kill-at] [-A|--add-stdcall-alias]
23               [-p|--ext-prefix-alias prefix]
24               [-x|--no-idata4] [-c|--no-idata5]
25               [--use-nul-prefixed-import-tables]
26               [-I|--identify library-file-name] [--identify-strict]
27               [-i|--interwork]
28               [-n|--nodelete] [-t|--temp-prefix prefix]
29               [-v|--verbose]
30               [-h|--help] [-V|--version]
31               [--no-leading-underscore] [--leading-underscore]
32               [object-file ...]
33

DESCRIPTION

35       dlltool reads its inputs, which can come from the -d and -b options as
36       well as object files specified on the command line.  It then processes
37       these inputs and if the -e option has been specified it creates a
38       exports file.  If the -l option has been specified it creates a library
39       file and if the -z option has been specified it creates a def file.
40       Any or all of the -e, -l and -z options can be present in one
41       invocation of dlltool.
42
43       When creating a DLL, along with the source for the DLL, it is necessary
44       to have three other files.  dlltool can help with the creation of these
45       files.
46
47       The first file is a .def file which specifies which functions are
48       exported from the DLL, which functions the DLL imports, and so on.
49       This is a text file and can be created by hand, or dlltool can be used
50       to create it using the -z option.  In this case dlltool will scan the
51       object files specified on its command line looking for those functions
52       which have been specially marked as being exported and put entries for
53       them in the .def file it creates.
54
55       In order to mark a function as being exported from a DLL, it needs to
56       have an -export:<name_of_function> entry in the .drectve section of the
57       object file.  This can be done in C by using the asm() operator:
58
59                 asm (".section .drectve");
60                 asm (".ascii \"-export:my_func\"");
61
62                 int my_func (void) { ... }
63
64       The second file needed for DLL creation is an exports file.  This file
65       is linked with the object files that make up the body of the DLL and it
66       handles the interface between the DLL and the outside world.  This is a
67       binary file and it can be created by giving the -e option to dlltool
68       when it is creating or reading in a .def file.
69
70       The third file needed for DLL creation is the library file that
71       programs will link with in order to access the functions in the DLL (an
72       `import library').  This file can be created by giving the -l option to
73       dlltool when it is creating or reading in a .def file.
74
75       If the -y option is specified, dlltool generates a delay-import library
76       that can be used instead of the normal import library to allow a
77       program to link to the dll only as soon as an imported function is
78       called for the first time. The resulting executable will need to be
79       linked to the static delayimp library containing __delayLoadHelper2(),
80       which in turn will import LoadLibraryA and GetProcAddress from
81       kernel32.
82
83       dlltool builds the library file by hand, but it builds the exports file
84       by creating temporary files containing assembler statements and then
85       assembling these.  The -S command line option can be used to specify
86       the path to the assembler that dlltool will use, and the -f option can
87       be used to pass specific flags to that assembler.  The -n can be used
88       to prevent dlltool from deleting these temporary assembler files when
89       it is done, and if -n is specified twice then this will prevent dlltool
90       from deleting the temporary object files it used to build the library.
91
92       Here is an example of creating a DLL from a source file dll.c and also
93       creating a program (from an object file called program.o) that uses
94       that DLL:
95
96                 gcc -c dll.c
97                 dlltool -e exports.o -l dll.lib dll.o
98                 gcc dll.o exports.o -o dll.dll
99                 gcc program.o dll.lib -o program
100
101       dlltool may also be used to query an existing import library to
102       determine the name of the DLL to which it is associated.  See the
103       description of the -I or --identify option.
104

OPTIONS

106       The command line options have the following meanings:
107
108       -d filename
109       --input-def filename
110           Specifies the name of a .def file to be read in and processed.
111
112       -b filename
113       --base-file filename
114           Specifies the name of a base file to be read in and processed.  The
115           contents of this file will be added to the relocation section in
116           the exports file generated by dlltool.
117
118       -e filename
119       --output-exp filename
120           Specifies the name of the export file to be created by dlltool.
121
122       -z filename
123       --output-def filename
124           Specifies the name of the .def file to be created by dlltool.
125
126       -l filename
127       --output-lib filename
128           Specifies the name of the library file to be created by dlltool.
129
130       -y filename
131       --output-delaylib filename
132           Specifies the name of the delay-import library file to be created
133           by dlltool.
134
135       --export-all-symbols
136           Treat all global and weak defined symbols found in the input object
137           files as symbols to be exported.  There is a small list of symbols
138           which are not exported by default; see the --no-default-excludes
139           option.  You may add to the list of symbols to not export by using
140           the --exclude-symbols option.
141
142       --no-export-all-symbols
143           Only export symbols explicitly listed in an input .def file or in
144           .drectve sections in the input object files.  This is the default
145           behaviour.  The .drectve sections are created by dllexport
146           attributes in the source code.
147
148       --exclude-symbols list
149           Do not export the symbols in list.  This is a list of symbol names
150           separated by comma or colon characters.  The symbol names should
151           not contain a leading underscore.  This is only meaningful when
152           --export-all-symbols is used.
153
154       --no-default-excludes
155           When --export-all-symbols is used, it will by default avoid
156           exporting certain special symbols.  The current list of symbols to
157           avoid exporting is DllMain@12, DllEntryPoint@0, impure_ptr.  You
158           may use the --no-default-excludes option to go ahead and export
159           these special symbols.  This is only meaningful when
160           --export-all-symbols is used.
161
162       -S path
163       --as path
164           Specifies the path, including the filename, of the assembler to be
165           used to create the exports file.
166
167       -f options
168       --as-flags options
169           Specifies any specific command line options to be passed to the
170           assembler when building the exports file.  This option will work
171           even if the -S option is not used.  This option only takes one
172           argument, and if it occurs more than once on the command line, then
173           later occurrences will override earlier occurrences.  So if it is
174           necessary to pass multiple options to the assembler they should be
175           enclosed in double quotes.
176
177       -D name
178       --dll-name name
179           Specifies the name to be stored in the .def file as the name of the
180           DLL when the -e option is used.  If this option is not present,
181           then the filename given to the -e option will be used as the name
182           of the DLL.
183
184       -m machine
185       -machine machine
186           Specifies the type of machine for which the library file should be
187           built.  dlltool has a built in default type, depending upon how it
188           was created, but this option can be used to override that.  This is
189           normally only useful when creating DLLs for an ARM processor, when
190           the contents of the DLL are actually encode using Thumb
191           instructions.
192
193       -a
194       --add-indirect
195           Specifies that when dlltool is creating the exports file it should
196           add a section which allows the exported functions to be referenced
197           without using the import library.  Whatever the hell that means!
198
199       -U
200       --add-underscore
201           Specifies that when dlltool is creating the exports file it should
202           prepend an underscore to the names of all exported symbols.
203
204       --no-leading-underscore
205       --leading-underscore
206           Specifies whether standard symbol should be forced to be prefixed,
207           or not.
208
209       --add-stdcall-underscore
210           Specifies that when dlltool is creating the exports file it should
211           prepend an underscore to the names of exported stdcall functions.
212           Variable names and non-stdcall function names are not modified.
213           This option is useful when creating GNU-compatible import libs for
214           third party DLLs that were built with MS-Windows tools.
215
216       -k
217       --kill-at
218           Specifies that when dlltool is creating the exports file it should
219           not append the string @ <number>.  These numbers are called ordinal
220           numbers and they represent another way of accessing the function in
221           a DLL, other than by name.
222
223       -A
224       --add-stdcall-alias
225           Specifies that when dlltool is creating the exports file it should
226           add aliases for stdcall symbols without @ <number> in addition to
227           the symbols with @ <number>.
228
229       -p
230       --ext-prefix-alias prefix
231           Causes dlltool to create external aliases for all DLL imports with
232           the specified prefix.  The aliases are created for both external
233           and import symbols with no leading underscore.
234
235       -x
236       --no-idata4
237           Specifies that when dlltool is creating the exports and library
238           files it should omit the ".idata4" section.  This is for
239           compatibility with certain operating systems.
240
241       --use-nul-prefixed-import-tables
242           Specifies that when dlltool is creating the exports and library
243           files it should prefix the ".idata4" and ".idata5" by zero an
244           element. This emulates old gnu import library generation of
245           "dlltool". By default this option is turned off.
246
247       -c
248       --no-idata5
249           Specifies that when dlltool is creating the exports and library
250           files it should omit the ".idata5" section.  This is for
251           compatibility with certain operating systems.
252
253       -I filename
254       --identify filename
255           Specifies that dlltool should inspect the import library indicated
256           by filename and report, on "stdout", the name(s) of the associated
257           DLL(s).  This can be performed in addition to any other operations
258           indicated by the other options and arguments.  dlltool fails if the
259           import library does not exist or is not actually an import library.
260           See also --identify-strict.
261
262       --identify-strict
263           Modifies the behavior of the --identify option, such that an error
264           is reported if filename is associated with more than one DLL.
265
266       -i
267       --interwork
268           Specifies that dlltool should mark the objects in the library file
269           and exports file that it produces as supporting interworking
270           between ARM and Thumb code.
271
272       -n
273       --nodelete
274           Makes dlltool preserve the temporary assembler files it used to
275           create the exports file.  If this option is repeated then dlltool
276           will also preserve the temporary object files it uses to create the
277           library file.
278
279       -t prefix
280       --temp-prefix prefix
281           Makes dlltool use prefix when constructing the names of temporary
282           assembler and object files.  By default, the temp file prefix is
283           generated from the pid.
284
285       -v
286       --verbose
287           Make dlltool describe what it is doing.
288
289       -h
290       --help
291           Displays a list of command line options and then exits.
292
293       -V
294       --version
295           Displays dlltool's version number and then exits.
296
297       @file
298           Read command-line options from file.  The options read are inserted
299           in place of the original @file option.  If file does not exist, or
300           cannot be read, then the option will be treated literally, and not
301           removed.
302
303           Options in file are separated by whitespace.  A whitespace
304           character may be included in an option by surrounding the entire
305           option in either single or double quotes.  Any character (including
306           a backslash) may be included by prefixing the character to be
307           included with a backslash.  The file may itself contain additional
308           @file options; any such options will be processed recursively.
309

SEE ALSO

311       The Info pages for binutils.
312
314       Copyright (c) 1991-2013 Free Software Foundation, Inc.
315
316       Permission is granted to copy, distribute and/or modify this document
317       under the terms of the GNU Free Documentation License, Version 1.3 or
318       any later version published by the Free Software Foundation; with no
319       Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
320       Texts.  A copy of the license is included in the section entitled "GNU
321       Free Documentation License".
322
323
324
325binutils-2.24                     2019-02-02                        DLLTOOL(1)
Impressum