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 @<number> suffixes should be omitted from the names
219           of stdcall functions that will be imported from the DLL.  This is
220           useful when creating an import library for a DLL which exports
221           stdcall functions but without the usual @<number> symbol name
222           suffix.
223
224           This does not change the naming of symbols provided by the import
225           library to programs linked against it, but only the entries in the
226           import table (ie the .idata section).
227
228       -A
229       --add-stdcall-alias
230           Specifies that when dlltool is creating the exports file it should
231           add aliases for stdcall symbols without @ <number> in addition to
232           the symbols with @ <number>.
233
234       -p
235       --ext-prefix-alias prefix
236           Causes dlltool to create external aliases for all DLL imports with
237           the specified prefix.  The aliases are created for both external
238           and import symbols with no leading underscore.
239
240       -x
241       --no-idata4
242           Specifies that when dlltool is creating the exports and library
243           files it should omit the ".idata4" section.  This is for
244           compatibility with certain operating systems.
245
246       --use-nul-prefixed-import-tables
247           Specifies that when dlltool is creating the exports and library
248           files it should prefix the ".idata4" and ".idata5" by zero an
249           element. This emulates old gnu import library generation of
250           "dlltool". By default this option is turned off.
251
252       -c
253       --no-idata5
254           Specifies that when dlltool is creating the exports and library
255           files it should omit the ".idata5" section.  This is for
256           compatibility with certain operating systems.
257
258       -I filename
259       --identify filename
260           Specifies that dlltool should inspect the import library indicated
261           by filename and report, on "stdout", the name(s) of the associated
262           DLL(s).  This can be performed in addition to any other operations
263           indicated by the other options and arguments.  dlltool fails if the
264           import library does not exist or is not actually an import library.
265           See also --identify-strict.
266
267       --identify-strict
268           Modifies the behavior of the --identify option, such that an error
269           is reported if filename is associated with more than one DLL.
270
271       -i
272       --interwork
273           Specifies that dlltool should mark the objects in the library file
274           and exports file that it produces as supporting interworking
275           between ARM and Thumb code.
276
277       -n
278       --nodelete
279           Makes dlltool preserve the temporary assembler files it used to
280           create the exports file.  If this option is repeated then dlltool
281           will also preserve the temporary object files it uses to create the
282           library file.
283
284       -t prefix
285       --temp-prefix prefix
286           Makes dlltool use prefix when constructing the names of temporary
287           assembler and object files.  By default, the temp file prefix is
288           generated from the pid.
289
290       -v
291       --verbose
292           Make dlltool describe what it is doing.
293
294       -h
295       --help
296           Displays a list of command line options and then exits.
297
298       -V
299       --version
300           Displays dlltool's version number and then exits.
301
302       @file
303           Read command-line options from file.  The options read are inserted
304           in place of the original @file option.  If file does not exist, or
305           cannot be read, then the option will be treated literally, and not
306           removed.
307
308           Options in file are separated by whitespace.  A whitespace
309           character may be included in an option by surrounding the entire
310           option in either single or double quotes.  Any character (including
311           a backslash) may be included by prefixing the character to be
312           included with a backslash.  The file may itself contain additional
313           @file options; any such options will be processed recursively.
314

SEE ALSO

316       The Info pages for binutils.
317
319       Copyright (c) 1991-2018 Free Software Foundation, Inc.
320
321       Permission is granted to copy, distribute and/or modify this document
322       under the terms of the GNU Free Documentation License, Version 1.3 or
323       any later version published by the Free Software Foundation; with no
324       Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
325       Texts.  A copy of the license is included in the section entitled "GNU
326       Free Documentation License".
327
328
329
330binutils-2.30.90                  2018-07-09                        DLLTOOL(1)
Impressum