1DLLTOOL(1) GNU Development Tools DLLTOOL(1)
2
6 dlltool - create files needed to build and use DLLs
7
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 [--deterministic-libraries] [--non-deterministic-libraries]
33 [object-file ...]
34
36 dlltool reads its inputs, which can come from the -d and -b options as
37 well as object files specified on the command line. It then processes
38 these inputs and if the -e option has been specified it creates a
39 exports file. If the -l option has been specified it creates a library
40 file and if the -z option has been specified it creates a def file.
41 Any or all of the -e, -l and -z options can be present in one
42 invocation of dlltool.
43 When creating a DLL, along with the source for the DLL, it is necessary
45 to have three other files. dlltool can help with the creation of these
46 files.
47 The first file is a .def file which specifies which functions are
49 exported from the DLL, which functions the DLL imports, and so on.
50 This is a text file and can be created by hand, or dlltool can be used
51 to create it using the -z option. In this case dlltool will scan the
52 object files specified on its command line looking for those functions
53 which have been specially marked as being exported and put entries for
54 them in the .def file it creates.
55 In order to mark a function as being exported from a DLL, it needs to
57 have an -export:<name_of_function> entry in the .drectve section of the
58 object file. This can be done in C by using the asm() operator:
59 asm (".section .drectve");
61 asm (".ascii \"-export:my_func\"");
62 int my_func (void) { ... }
64 The second file needed for DLL creation is an exports file. This file
66 is linked with the object files that make up the body of the DLL and it
67 handles the interface between the DLL and the outside world. This is a
68 binary file and it can be created by giving the -e option to dlltool
69 when it is creating or reading in a .def file.
70 The third file needed for DLL creation is the library file that
72 programs will link with in order to access the functions in the DLL (an
73 `import library'). This file can be created by giving the -l option to
74 dlltool when it is creating or reading in a .def file.
75 If the -y option is specified, dlltool generates a delay-import library
77 that can be used instead of the normal import library to allow a
78 program to link to the dll only as soon as an imported function is
79 called for the first time. The resulting executable will need to be
80 linked to the static delayimp library containing __delayLoadHelper2(),
81 which in turn will import LoadLibraryA and GetProcAddress from
82 kernel32.
83 dlltool builds the library file by hand, but it builds the exports file
85 by creating temporary files containing assembler statements and then
86 assembling these. The -S command-line option can be used to specify
87 the path to the assembler that dlltool will use, and the -f option can
88 be used to pass specific flags to that assembler. The -n can be used
89 to prevent dlltool from deleting these temporary assembler files when
90 it is done, and if -n is specified twice then this will prevent dlltool
91 from deleting the temporary object files it used to build the library.
92 Here is an example of creating a DLL from a source file dll.c and also
94 creating a program (from an object file called program.o) that uses
95 that DLL:
96 gcc -c dll.c
98 dlltool -e exports.o -l dll.lib dll.o
99 gcc dll.o exports.o -o dll.dll
100 gcc program.o dll.lib -o program
101 dlltool may also be used to query an existing import library to
103 determine the name of the DLL to which it is associated. See the
104 description of the -I or --identify option.
105
107 The command-line options have the following meanings:
108 -d filename
110 --input-def filename
111 Specifies the name of a .def file to be read in and processed.
112 -b filename
114 --base-file filename
115 Specifies the name of a base file to be read in and processed. The
116 contents of this file will be added to the relocation section in
117 the exports file generated by dlltool.
118 -e filename
120 --output-exp filename
121 Specifies the name of the export file to be created by dlltool.
122 -z filename
124 --output-def filename
125 Specifies the name of the .def file to be created by dlltool.
126 -l filename
128 --output-lib filename
129 Specifies the name of the library file to be created by dlltool.
130 -y filename
132 --output-delaylib filename
133 Specifies the name of the delay-import library file to be created
134 by dlltool.
135 --deterministic-libraries
137 --non-deterministic-libraries
138 When creating output libraries in response to either the
139 --output-lib or --output-delaylib options either use the value of
140 zero for any timestamps, user ids and group ids created
141 (--deterministic-libraries) or the actual timestamps, user ids and
142 group ids (--non-deterministic-libraries).
143 --export-all-symbols
145 Treat all global and weak defined symbols found in the input object
146 files as symbols to be exported. There is a small list of symbols
147 which are not exported by default; see the --no-default-excludes
148 option. You may add to the list of symbols to not export by using
149 the --exclude-symbols option.
150 --no-export-all-symbols
152 Only export symbols explicitly listed in an input .def file or in
153 .drectve sections in the input object files. This is the default
154 behaviour. The .drectve sections are created by dllexport
155 attributes in the source code.
156 --exclude-symbols list
158 Do not export the symbols in list. This is a list of symbol names
159 separated by comma or colon characters. The symbol names should
160 not contain a leading underscore. This is only meaningful when
161 --export-all-symbols is used.
162 --no-default-excludes
164 When --export-all-symbols is used, it will by default avoid
165 exporting certain special symbols. The current list of symbols to
166 avoid exporting is DllMain@12, DllEntryPoint@0, impure_ptr. You
167 may use the --no-default-excludes option to go ahead and export
168 these special symbols. This is only meaningful when
169 --export-all-symbols is used.
170 -S path
172 --as path
173 Specifies the path, including the filename, of the assembler to be
174 used to create the exports file.
175 -f options
177 --as-flags options
178 Specifies any specific command-line options to be passed to the
179 assembler when building the exports file. This option will work
180 even if the -S option is not used. This option only takes one
181 argument, and if it occurs more than once on the command line, then
182 later occurrences will override earlier occurrences. So if it is
183 necessary to pass multiple options to the assembler they should be
184 enclosed in double quotes.
185 -D name
187 --dll-name name
188 Specifies the name to be stored in the .def file as the name of the
189 DLL when the -e option is used. If this option is not present,
190 then the filename given to the -e option will be used as the name
191 of the DLL.
192 -m machine
194 -machine machine
195 Specifies the type of machine for which the library file should be
196 built. dlltool has a built in default type, depending upon how it
197 was created, but this option can be used to override that. This is
198 normally only useful when creating DLLs for an ARM processor, when
199 the contents of the DLL are actually encode using Thumb
200 instructions.
201 -a
203 --add-indirect
204 Specifies that when dlltool is creating the exports file it should
205 add a section which allows the exported functions to be referenced
206 without using the import library. Whatever the hell that means!
207 -U
209 --add-underscore
210 Specifies that when dlltool is creating the exports file it should
211 prepend an underscore to the names of all exported symbols.
212 --no-leading-underscore
214 --leading-underscore
215 Specifies whether standard symbol should be forced to be prefixed,
216 or not.
217 --add-stdcall-underscore
219 Specifies that when dlltool is creating the exports file it should
220 prepend an underscore to the names of exported stdcall functions.
221 Variable names and non-stdcall function names are not modified.
222 This option is useful when creating GNU-compatible import libs for
223 third party DLLs that were built with MS-Windows tools.
224 -k
226 --kill-at
227 Specifies that @<number> suffixes should be omitted from the names
228 of stdcall functions that will be imported from the DLL. This is
229 useful when creating an import library for a DLL which exports
230 stdcall functions but without the usual @<number> symbol name
231 suffix.
232 This does not change the naming of symbols provided by the import
234 library to programs linked against it, but only the entries in the
235 import table (ie the .idata section).
236 -A
238 --add-stdcall-alias
239 Specifies that when dlltool is creating the exports file it should
240 add aliases for stdcall symbols without @ <number> in addition to
241 the symbols with @ <number>.
242 -p
244 --ext-prefix-alias prefix
245 Causes dlltool to create external aliases for all DLL imports with
246 the specified prefix. The aliases are created for both external
247 and import symbols with no leading underscore.
248 -x
250 --no-idata4
251 Specifies that when dlltool is creating the exports and library
252 files it should omit the ".idata4" section. This is for
253 compatibility with certain operating systems.
254 --use-nul-prefixed-import-tables
256 Specifies that when dlltool is creating the exports and library
257 files it should prefix the ".idata4" and ".idata5" by zero an
258 element. This emulates old gnu import library generation of
259 "dlltool". By default this option is turned off.
260 -c
262 --no-idata5
263 Specifies that when dlltool is creating the exports and library
264 files it should omit the ".idata5" section. This is for
265 compatibility with certain operating systems.
266 -I filename
268 --identify filename
269 Specifies that dlltool should inspect the import library indicated
270 by filename and report, on "stdout", the name(s) of the associated
271 DLL(s). This can be performed in addition to any other operations
272 indicated by the other options and arguments. dlltool fails if the
273 import library does not exist or is not actually an import library.
274 See also --identify-strict.
275 --identify-strict
277 Modifies the behavior of the --identify option, such that an error
278 is reported if filename is associated with more than one DLL.
279 -i
281 --interwork
282 Specifies that dlltool should mark the objects in the library file
283 and exports file that it produces as supporting interworking
284 between ARM and Thumb code.
285 -n
287 --nodelete
288 Makes dlltool preserve the temporary assembler files it used to
289 create the exports file. If this option is repeated then dlltool
290 will also preserve the temporary object files it uses to create the
291 library file.
292 -t prefix
294 --temp-prefix prefix
295 Makes dlltool use prefix when constructing the names of temporary
296 assembler and object files. By default, the temp file prefix is
297 generated from the pid.
298 -v
300 --verbose
301 Make dlltool describe what it is doing.
302 -h
304 --help
305 Displays a list of command-line options and then exits.
306 -V
308 --version
309 Displays dlltool's version number and then exits.
310 @file
312 Read command-line options from file. The options read are inserted
313 in place of the original @file option. If file does not exist, or
314 cannot be read, then the option will be treated literally, and not
315 removed.
316 Options in file are separated by whitespace. A whitespace
318 character may be included in an option by surrounding the entire
319 option in either single or double quotes. Any character (including
320 a backslash) may be included by prefixing the character to be
321 included with a backslash. The file may itself contain additional
322 @file options; any such options will be processed recursively.
323
325 The Info pages for binutils.
326
328 Copyright (c) 1991-2023 Free Software Foundation, Inc.
329 Permission is granted to copy, distribute and/or modify this document
331 under the terms of the GNU Free Documentation License, Version 1.3 or
332 any later version published by the Free Software Foundation; with no
333 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
334 Texts. A copy of the license is included in the section entitled "GNU
335 Free Documentation License".
336binutils-2.40.00 2023-07-30 DLLTOOL(1)