contrib/binutils/binutils/doc/dlltool.1

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