contrib/binutils/binutils/doc/dlltool.1

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