2001-04-05 Steven J. Hill <sjhill@cotw.com>
[deliverable/binutils-gdb.git] / binutils / dlltool.1
1 .rn '' }`
2 ''' $RCSfile$$Revision$$Date$
3 '''
4 ''' $Log$
5 ''' Revision 1.1 2001/03/25 20:32:25 nickc
6 ''' Automate generate on man pages
7 '''
8 '''
9 .de Sh
10 .br
11 .if t .Sp
12 .ne 5
13 .PP
14 \fB\\$1\fR
15 .PP
16 ..
17 .de Sp
18 .if t .sp .5v
19 .if n .sp
20 ..
21 .de Ip
22 .br
23 .ie \\n(.$>=3 .ne \\$3
24 .el .ne 3
25 .IP "\\$1" \\$2
26 ..
27 .de Vb
28 .ft CW
29 .nf
30 .ne \\$1
31 ..
32 .de Ve
33 .ft R
34
35 .fi
36 ..
37 '''
38 '''
39 ''' Set up \*(-- to give an unbreakable dash;
40 ''' string Tr holds user defined translation string.
41 ''' Bell System Logo is used as a dummy character.
42 '''
43 .tr \(*W-|\(bv\*(Tr
44 .ie n \{\
45 .ds -- \(*W-
46 .ds PI pi
47 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
48 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
49 .ds L" ""
50 .ds R" ""
51 ''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
52 ''' \*(L" and \*(R", except that they are used on ".xx" lines,
53 ''' such as .IP and .SH, which do another additional levels of
54 ''' double-quote interpretation
55 .ds M" """
56 .ds S" """
57 .ds N" """""
58 .ds T" """""
59 .ds L' '
60 .ds R' '
61 .ds M' '
62 .ds S' '
63 .ds N' '
64 .ds T' '
65 'br\}
66 .el\{\
67 .ds -- \(em\|
68 .tr \*(Tr
69 .ds L" ``
70 .ds R" ''
71 .ds M" ``
72 .ds S" ''
73 .ds N" ``
74 .ds T" ''
75 .ds L' `
76 .ds R' '
77 .ds M' `
78 .ds S' '
79 .ds N' `
80 .ds T' '
81 .ds PI \(*p
82 'br\}
83 .\" If the F register is turned on, we'll generate
84 .\" index entries out stderr for the following things:
85 .\" TH Title
86 .\" SH Header
87 .\" Sh Subsection
88 .\" Ip Item
89 .\" X<> Xref (embedded
90 .\" Of course, you have to process the output yourself
91 .\" in some meaninful fashion.
92 .if \nF \{
93 .de IX
94 .tm Index:\\$1\t\\n%\t"\\$2"
95 ..
96 .nr % 0
97 .rr F
98 .\}
99 .TH DLLTOOL.1 1 "binutils-2.11.90" "23/Mar/101" "GNU"
100 .UC
101 .if n .hy 0
102 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
103 .de CQ \" put $1 in typewriter font
104 .ft CW
105 'if n "\c
106 'if t \\&\\$1\c
107 'if n \\&\\$1\c
108 'if n \&"
109 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
110 '.ft R
111 ..
112 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
113 . \" AM - accent mark definitions
114 .bd B 3
115 . \" fudge factors for nroff and troff
116 .if n \{\
117 . ds #H 0
118 . ds #V .8m
119 . ds #F .3m
120 . ds #[ \f1
121 . ds #] \fP
122 .\}
123 .if t \{\
124 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
125 . ds #V .6m
126 . ds #F 0
127 . ds #[ \&
128 . ds #] \&
129 .\}
130 . \" simple accents for nroff and troff
131 .if n \{\
132 . ds ' \&
133 . ds ` \&
134 . ds ^ \&
135 . ds , \&
136 . ds ~ ~
137 . ds ? ?
138 . ds ! !
139 . ds /
140 . ds q
141 .\}
142 .if t \{\
143 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
144 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
145 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
146 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
147 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
148 . ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
149 . ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
150 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
151 . ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
152 .\}
153 . \" troff and (daisy-wheel) nroff accents
154 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
155 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
156 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
157 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
158 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
159 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
160 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
161 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
162 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
163 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
164 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
165 .ds ae a\h'-(\w'a'u*4/10)'e
166 .ds Ae A\h'-(\w'A'u*4/10)'E
167 .ds oe o\h'-(\w'o'u*4/10)'e
168 .ds Oe O\h'-(\w'O'u*4/10)'E
169 . \" corrections for vroff
170 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
171 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
172 . \" for low resolution devices (crt and lpr)
173 .if \n(.H>23 .if \n(.V>19 \
174 \{\
175 . ds : e
176 . ds 8 ss
177 . ds v \h'-1'\o'\(aa\(ga'
178 . ds _ \h'-1'^
179 . ds . \h'-1'.
180 . ds 3 3
181 . ds o a
182 . ds d- d\h'-1'\(ga
183 . ds D- D\h'-1'\(hy
184 . ds th \o'bp'
185 . ds Th \o'LP'
186 . ds ae ae
187 . ds Ae AE
188 . ds oe oe
189 . ds Oe OE
190 .\}
191 .rm #[ #] #H #V #F C
192 .SH "NAME"
193 dlltool \- Create files needed to build and use DLLs.
194 .SH "SYNOPSIS"
195 dlltool [\-d|--input-def \fIdef-file-name\fR]
196 [\-b|--base-file \fIbase-file-name\fR]
197 [\-e|--output-exp \fIexports-file-name\fR]
198 [\-z|--output-def \fIdef-file-name\fR]
199 [\-l|--output-lib \fIlibrary-file-name\fR]
200 [--export-all-symbols] [--no-export-all-symbols]
201 [--exclude-symbols \fIlist\fR]
202 [--no-default-excludes]
203 [\-S|--as \fIpath-to-assembler\fR] [\-f|--as-flags \fIoptions\fR]
204 [\-D|--dllname \fIname\fR] [\-m|--machine \fImachine\fR]
205 [\-a|--add-indirect] [\-U|--add-underscore] [\-k|--kill-at]
206 [\-A|--add-stdcall-alias]
207 [\-x|--no-idata4] [\-c|--no-idata5] [\-i|--interwork]
208 [\-n|--nodelete] [\-v|--verbose] [\-h|--help] [\-V|--version]
209 [object-file ...]
210 .SH "DESCRIPTION"
211 \f(CWdlltool\fR reads its inputs, which can come from the \fB\-d\fR and
212 \fB\-b\fR options as well as object files specified on the command
213 line. It then processes these inputs and if the \fB\-e\fR option has
214 been specified it creates a exports file. If the \fB\-l\fR option
215 has been specified it creates a library file and if the \fB\-z\fR option
216 has been specified it creates a def file. Any or all of the \-e, \-l
217 and \-z options can be present in one invocation of dlltool.
218 .PP
219 When creating a DLL, along with the source for the DLL, it is necessary
220 to have three other files. \f(CWdlltool\fR can help with the creation of
221 these files.
222 .PP
223 The first file is a \fB.def\fR file which specifies which functions are
224 exported from the DLL, which functions the DLL imports, and so on. This
225 is a text file and can be created by hand, or \f(CWdlltool\fR can be used
226 to create it using the \fB\-z\fR option. In this case \f(CWdlltool\fR
227 will scan the object files specified on its command line looking for
228 those functions which have been specially marked as being exported and
229 put entries for them in the .def file it creates.
230 .PP
231 In order to mark a function as being exported from a DLL, it needs to
232 have an \fB\-export:<name_of_function>\fR entry in the \fB.drectve\fR
233 section of the object file. This can be done in C by using the
234 \fIasm()\fR operator:
235 .PP
236 .Vb 5
237 \&
238 \& asm (".section .drectve");
239 \& asm (".ascii \e"-export:my_func\e"");
240 \&
241 \& int my_func (void) { ... }
242 .Ve
243 The second file needed for DLL creation is an exports file. This file
244 is linked with the object files that make up the body of the DLL and it
245 handles the interface between the DLL and the outside world. This is a
246 binary file and it can be created by giving the \fB\-e\fR option to
247 \f(CWdlltool\fR when it is creating or reading in a .def file.
248 .PP
249 The third file needed for DLL creation is the library file that programs
250 will link with in order to access the functions in the DLL. This file
251 can be created by giving the \fB\-l\fR option to dlltool when it
252 is creating or reading in a .def file.
253 .PP
254 \f(CWdlltool\fR builds the library file by hand, but it builds the
255 exports file by creating temporary files containing assembler statements
256 and then assembling these. The \fB\-S\fR command line option can be
257 used to specify the path to the assembler that dlltool will use,
258 and the \fB\-f\fR option can be used to pass specific flags to that
259 assembler. The \fB\-n\fR can be used to prevent dlltool from deleting
260 these temporary assembler files when it is done, and if \fB\-n\fR is
261 specified twice then this will prevent dlltool from deleting the
262 temporary object files it used to build the library.
263 .PP
264 Here is an example of creating a DLL from a source file \fBdll.c\fR and
265 also creating a program (from an object file called \fBprogram.o\fR)
266 that uses that DLL:
267 .PP
268 .Vb 5
269 \&
270 \& gcc -c dll.c
271 \& dlltool -e exports.o -l dll.lib dll.o
272 \& gcc dll.o exports.o -o dll.dll
273 \& gcc program.o dll.lib -o program
274 .Ve
275 .SH "OPTIONS"
276 The command line options have the following meanings:
277 .Ip "\f(CW-d \fIfilename\fR\fR" 4
278 .Ip "\f(CW--input-def \fIfilename\fR\fR" 4
279 Specifies the name of a .def file to be read in and processed.
280 .Ip "\f(CW-b \fIfilename\fR\fR" 4
281 .Ip "\f(CW--base-file \fIfilename\fR\fR" 4
282 Specifies the name of a base file to be read in and processed. The
283 contents of this file will be added to the relocation section in the
284 exports file generated by dlltool.
285 .Ip "\f(CW-e \fIfilename\fR\fR" 4
286 .Ip "\f(CW--output-exp \fIfilename\fR\fR" 4
287 Specifies the name of the export file to be created by dlltool.
288 .Ip "\f(CW-z \fIfilename\fR\fR" 4
289 .Ip "\f(CW--output-def \fIfilename\fR\fR" 4
290 Specifies the name of the .def file to be created by dlltool.
291 .Ip "\f(CW-l \fIfilename\fR\fR" 4
292 .Ip "\f(CW--output-lib \fIfilename\fR\fR" 4
293 Specifies the name of the library file to be created by dlltool.
294 .Ip "\f(CW--export-all-symbols\fR" 4
295 Treat all global and weak defined symbols found in the input object
296 files as symbols to be exported. There is a small list of symbols which
297 are not exported by default; see the \f(CW--no-default-excludes\fR
298 option. You may add to the list of symbols to not export by using the
299 \f(CW--exclude-symbols\fR option.
300 .Ip "\f(CW--no-export-all-symbols\fR" 4
301 Only export symbols explicitly listed in an input .def file or in
302 \&\fB.drectve\fR sections in the input object files. This is the default
303 behaviour. The \fB.drectve\fR sections are created by \fBdllexport\fR
304 attributes in the source code.
305 .Ip "\f(CW--exclude-symbols \fIlist\fR\fR" 4
306 Do not export the symbols in \fIlist\fR. This is a list of symbol names
307 separated by comma or colon characters. The symbol names should not
308 contain a leading underscore. This is only meaningful when
309 \f(CW--export-all-symbols\fR is used.
310 .Ip "\f(CW--no-default-excludes\fR" 4
311 When \f(CW--export-all-symbols\fR is used, it will by default avoid
312 exporting certain special symbols. The current list of symbols to avoid
313 exporting is \fBDllMain@12\fR, \fBDllEntryPoint@0\fR,
314 \fBimpure_ptr\fR. You may use the \f(CW--no-default-excludes\fR option
315 to go ahead and export these special symbols. This is only meaningful
316 when \f(CW--export-all-symbols\fR is used.
317 .Ip "\f(CW-S \fIpath\fR\fR" 4
318 .Ip "\f(CW--as \fIpath\fR\fR" 4
319 Specifies the path, including the filename, of the assembler to be used
320 to create the exports file.
321 .Ip "\f(CW-f \fIswitches\fR\fR" 4
322 .Ip "\f(CW--as-flags \fIswitches\fR\fR" 4
323 Specifies any specific command line switches to be passed to the
324 assembler when building the exports file. This option will work even if
325 the \fB\-S\fR option is not used. This option only takes one argument,
326 and if it occurs more than once on the command line, then later
327 occurrences will override earlier occurrences. So if it is necessary to
328 pass multiple switches to the assembler they should be enclosed in
329 double quotes.
330 .Ip "\f(CW-D \fIname\fR\fR" 4
331 .Ip "\f(CW--dll-name \fIname\fR\fR" 4
332 Specifies the name to be stored in the .def file as the name of the \s-1DLL\s0
333 when the \fB\-e\fR option is used. If this option is not present, then
334 the filename given to the \fB\-e\fR option will be used as the name of
335 the \s-1DLL\s0.
336 .Ip "\f(CW-m \fImachine\fR\fR" 4
337 .Ip "\f(CW-machine \fImachine\fR\fR" 4
338 Specifies the type of machine for which the library file should be
339 built. \f(CWdlltool\fR has a built in default type, depending upon how
340 it was created, but this option can be used to override that. This is
341 normally only useful when creating DLLs for an \s-1ARM\s0 processor, when the
342 contents of the \s-1DLL\s0 are actually encode using \s-1THUMB\s0 instructions.
343 .Ip "\f(CW-a\fR" 4
344 .Ip "\f(CW--add-indirect\fR" 4
345 Specifies that when \f(CWdlltool\fR is creating the exports file it
346 should add a section which allows the exported functions to be
347 referenced without using the import library. Whatever the hell that
348 means!
349 .Ip "\f(CW-U\fR" 4
350 .Ip "\f(CW--add-underscore\fR" 4
351 Specifies that when \f(CWdlltool\fR is creating the exports file it
352 should prepend an underscore to the names of the exported functions.
353 .Ip "\f(CW-k\fR" 4
354 .Ip "\f(CW--kill-at\fR" 4
355 Specifies that when \f(CWdlltool\fR is creating the exports file it
356 should not append the string \fB@ <number>\fR. These numbers are
357 called ordinal numbers and they represent another way of accessing the
358 function in a \s-1DLL\s0, other than by name.
359 .Ip "\f(CW-A\fR" 4
360 .Ip "\f(CW--add-stdcall-alias\fR" 4
361 Specifies that when \f(CWdlltool\fR is creating the exports file it
362 should add aliases for stdcall symbols without \fB@ <number>\fR
363 in addition to the symbols with \fB@ <number>\fR.
364 .Ip "\f(CW-x\fR" 4
365 .Ip "\f(CW--no-idata4\fR" 4
366 Specifies that when \f(CWdlltool\fR is creating the exports and library
367 files it should omit the .idata4 section. This is for compatibility
368 with certain operating systems.
369 .Ip "\f(CW-c\fR" 4
370 .Ip "\f(CW--no-idata5\fR" 4
371 Specifies that when \f(CWdlltool\fR is creating the exports and library
372 files it should omit the .idata5 section. This is for compatibility
373 with certain operating systems.
374 .Ip "\f(CW-i\fR" 4
375 .Ip "\f(CW--interwork\fR" 4
376 Specifies that \f(CWdlltool\fR should mark the objects in the library
377 file and exports file that it produces as supporting interworking
378 between \s-1ARM\s0 and \s-1THUMB\s0 code.
379 .Ip "\f(CW-n\fR" 4
380 .Ip "\f(CW--nodelete\fR" 4
381 Makes \f(CWdlltool\fR preserve the temporary assembler files it used to
382 create the exports file. If this option is repeated then dlltool will
383 also preserve the temporary object files it uses to create the library
384 file.
385 .Ip "\f(CW-v\fR" 4
386 .Ip "\f(CW--verbose\fR" 4
387 Make dlltool describe what it is doing.
388 .Ip "\f(CW-h\fR" 4
389 .Ip "\f(CW--help\fR" 4
390 Displays a list of command line options and then exits.
391 .Ip "\f(CW-V\fR" 4
392 .Ip "\f(CW--version\fR" 4
393 Displays dlltool's version number and then exits.
394 .SH "SEE ALSO"
395 the Info entries for \fIbinutils\fR.
396 .SH "COPYRIGHT"
397 Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc.
398 .PP
399 Permission is granted to copy, distribute and/or modify this document
400 under the terms of the GNU Free Documentation License, Version 1.1
401 or any later version published by the Free Software Foundation;
402 with no Invariant Sections, with no Front-Cover Texts, and with no
403 Back-Cover Texts. A copy of the license is included in the
404 section entitled \*(L"GNU Free Documentation License\*(R".
405
406 .rn }` ''
407 .IX Title "DLLTOOL.1 1"
408 .IX Name "dlltool - Create files needed to build and use DLLs."
409
410 .IX Header "NAME"
411
412 .IX Header "SYNOPSIS"
413
414 .IX Header "DESCRIPTION"
415
416 .IX Header "OPTIONS"
417
418 .IX Item "\f(CW-d \fIfilename\fR\fR"
419
420 .IX Item "\f(CW--input-def \fIfilename\fR\fR"
421
422 .IX Item "\f(CW-b \fIfilename\fR\fR"
423
424 .IX Item "\f(CW--base-file \fIfilename\fR\fR"
425
426 .IX Item "\f(CW-e \fIfilename\fR\fR"
427
428 .IX Item "\f(CW--output-exp \fIfilename\fR\fR"
429
430 .IX Item "\f(CW-z \fIfilename\fR\fR"
431
432 .IX Item "\f(CW--output-def \fIfilename\fR\fR"
433
434 .IX Item "\f(CW-l \fIfilename\fR\fR"
435
436 .IX Item "\f(CW--output-lib \fIfilename\fR\fR"
437
438 .IX Item "\f(CW--export-all-symbols\fR"
439
440 .IX Item "\f(CW--no-export-all-symbols\fR"
441
442 .IX Item "\f(CW--exclude-symbols \fIlist\fR\fR"
443
444 .IX Item "\f(CW--no-default-excludes\fR"
445
446 .IX Item "\f(CW-S \fIpath\fR\fR"
447
448 .IX Item "\f(CW--as \fIpath\fR\fR"
449
450 .IX Item "\f(CW-f \fIswitches\fR\fR"
451
452 .IX Item "\f(CW--as-flags \fIswitches\fR\fR"
453
454 .IX Item "\f(CW-D \fIname\fR\fR"
455
456 .IX Item "\f(CW--dll-name \fIname\fR\fR"
457
458 .IX Item "\f(CW-m \fImachine\fR\fR"
459
460 .IX Item "\f(CW-machine \fImachine\fR\fR"
461
462 .IX Item "\f(CW-a\fR"
463
464 .IX Item "\f(CW--add-indirect\fR"
465
466 .IX Item "\f(CW-U\fR"
467
468 .IX Item "\f(CW--add-underscore\fR"
469
470 .IX Item "\f(CW-k\fR"
471
472 .IX Item "\f(CW--kill-at\fR"
473
474 .IX Item "\f(CW-A\fR"
475
476 .IX Item "\f(CW--add-stdcall-alias\fR"
477
478 .IX Item "\f(CW-x\fR"
479
480 .IX Item "\f(CW--no-idata4\fR"
481
482 .IX Item "\f(CW-c\fR"
483
484 .IX Item "\f(CW--no-idata5\fR"
485
486 .IX Item "\f(CW-i\fR"
487
488 .IX Item "\f(CW--interwork\fR"
489
490 .IX Item "\f(CW-n\fR"
491
492 .IX Item "\f(CW--nodelete\fR"
493
494 .IX Item "\f(CW-v\fR"
495
496 .IX Item "\f(CW--verbose\fR"
497
498 .IX Item "\f(CW-h\fR"
499
500 .IX Item "\f(CW--help\fR"
501
502 .IX Item "\f(CW-V\fR"
503
504 .IX Item "\f(CW--version\fR"
505
506 .IX Header "SEE ALSO"
507
508 .IX Header "COPYRIGHT"
509
This page took 0.042237 seconds and 4 git commands to generate.