binutils/dlltool.1

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