DLLTOOL(1)

📦 version 2.16.1, in debian bookworm, ubuntu jammy, ubuntu noble

💖 DLLTOOL(1) 💖

okay bestie, welcome to the manual page for dlltool, part of the GNU Development Tools situation ✨ (the manual name is literally DLLTOOL(1), iykyk). she's a binutils girlie and she makes files. so many files. let's get into it 🎀

✨ NAME ✨

dlltool — Create files needed to build and use DLLs.

that's it. that's the whole vibe. she builds the scaffolding so your DLL can exist 💅

🌸 SYNOPSIS 🌸

dlltool [-d⎪--input-def def-file-name]
        [-b⎪--base-file base-file-name]
        [-e⎪--output-exp exports-file-name]
        [-z⎪--output-def def-file-name]
        [-l⎪--output-lib library-file-name]
        [--export-all-symbols] [--no-export-all-symbols]
        [--exclude-symbols list]
        [--no-default-excludes]
        [-S⎪--as path-to-assembler] [-f⎪--as-flags options]
        [-D⎪--dllname name] [-m⎪--machine machine]
        [-a⎪--add-indirect] [-U⎪--add-underscore] [-k⎪--kill-at]
        [-A⎪--add-stdcall-alias]
        [-p⎪--ext-prefix-alias prefix]
        [-x⎪--no-idata4] [-c⎪--no-idata5] [-i⎪--interwork]
        [-n⎪--nodelete] [-t⎪--temp-prefix prefix]
        [-v⎪--verbose]
        [-h⎪--help] [-V⎪--version]
        [object-file ...]

look at her. so many options. she's thriving 👑

🦋 DESCRIPTION 🦋

okay so here's the tea 🍓. dlltool reads its inputs, and those inputs can come from the -d and -b options, plus object files you just drop on the command line. then she processes all of that, and:

  • if you gave her -e, she creates an exports file 📦
  • if you gave her -l, she creates a library file 📚
  • if you gave her -z, she creates a def file 📝

and literally any or all of -e, -l and -z can show up in one single invocation of dlltool. she's a multitasker, no cap 💅

💜 the three files situation 💜

so when you're creating a DLL, along with the source for the DLL itself, you need three other files. dlltool can help with creating all of them, and honestly? she wants to 🥺

file one: the .def file 🎀

this one specifies which functions are exported from the DLL, which functions the DLL imports, and so on. it's a text file, so you can create it by hand like a brave little soldier, or dlltool can create it for you using the -z option. in that case dlltool scans the object files you specified on her command line, looking for the functions that have been specially marked as being exported, and she puts entries for them into the .def file she creates. queen behavior ✨

so to mark a function as being exported from a DLL, it needs to have an -export:<name_of_function> entry in the .drectve section of the object file. and you can do that in C by using the asm() operator, like this:

asm (".section .drectve");
asm (".ascii \"-export:my_func\"");

int my_func (void) { ... }

see? iconic. it's giving "I annotate my own object files" 💅

file two: the exports file 🔥

this is the second file you need for DLL creation. it gets linked with the object files that make up the body of the DLL, and it handles the interface between the DLL and the outside world 🌍. it's a binary file (so, not something you hand-edit, bestie, don't even try), and you can create it by giving the -e option to dlltool when she's creating or reading in a .def file.

file three: the library file 📚

this is the file that programs will link with in order to access the functions in the DLL. you create it by giving the -l option to dlltool when she's creating or reading in a .def file. simple as 🫶

🌈 how she actually does it 🌈

here's the fun part: dlltool builds the library file by hand, but she builds the exports file by creating temporary files containing assembler statements and then assembling those. very DIY of her 💖

  • the -S command line option specifies the path to the assembler she'll use 🛠️
  • the -f option passes specific flags to that assembler 🚩
  • the -n option stops dlltool from deleting those temporary assembler files when she's done 🗑️❌
  • and if -n is specified twice, that also prevents dlltool from deleting the temporary object files she used to build the library 👀

⭐ example time ⭐

here's an example of creating a DLL from a source file dll.c, and also creating a program (from an object file called program.o) that uses that DLL:

gcc -c dll.c
dlltool -e exports.o -l dll.lib dll.o
gcc dll.o exports.o -o dll.dll
gcc program.o dll.lib -o program

chef's kiss. no notes. ate and left no crumbs 😭🔥

👑 OPTIONS 👑

the command line options have the following meanings:

  • -d filename, --input-def filename — Specifies the name of a .def file to be read in and processed. 📖
  • -b filename, --base-file filename — Specifies the name of a base file to be read in and processed. The contents of this file will be added to the relocation section in the exports file generated by dlltool. 🧩
  • -e filename, --output-exp filename — Specifies the name of the export file to be created by dlltool. 📤
  • -z filename, --output-def filename — Specifies the name of the .def file to be created by dlltool. 📝
  • -l filename, --output-lib filename — Specifies the name of the library file to be created by dlltool. 📚
  • --export-all-symbols — Treat all global and weak defined symbols found in the input object files as symbols to be exported. There's a small list of symbols that are not exported by default — see the --no-default-excludes option for that. And you can add to the list of symbols to NOT export by using the --exclude-symbols option. 💥
  • --no-export-all-symbols — Only export symbols explicitly listed in an input .def file, or in .drectve sections in the input object files. This is the default behaviour. The .drectve sections are created by dllexport attributes in the source code. 🎯
  • --exclude-symbols list — Do not export the symbols in list. This is a list of symbol names separated by comma or colon characters. The symbol names should not contain a leading underscore. This is only meaningful when --export-all-symbols is used. 🙅♀️
  • --no-default-excludes — When --export-all-symbols is used, it will by default avoid exporting certain special symbols. The current list of symbols to avoid exporting is DllMain@12, DllEntryPoint@0, impure_ptr. You may use the --no-default-excludes option to go ahead and export these special symbols anyway. This is only meaningful when --export-all-symbols is used. 👀
  • -S path, --as path — Specifies the path, including the filename, of the assembler to be used to create the exports file. 🛠️
  • -f options, --as-flags options — Specifies any specific command line options to be passed to the assembler when building the exports file. This option will work even if the -S option is not used. It only takes one argument, and if it occurs more than once on the command line, then later occurrences will override earlier occurrences. So if you need to pass multiple options to the assembler, enclose them in double quotes, bestie 🗣️
  • -D name, --dll-name name — Specifies the name to be stored in the .def file as the name of the DLL when the -e option is used. If this option is not present, then the filename given to the -e option will be used as the name of the DLL. 🏷️
  • -m machine, -machine machine — Specifies the type of machine for which the library file should be built. dlltool has a built in default type, depending on how she was created, but this option can override that. This is normally only useful when creating DLLs for an ARM processor, when the contents of the DLL are actually encoded using Thumb instructions. 🦾
  • -a, --add-indirect — Specifies that when dlltool is creating the exports file she should add a section which allows the exported functions to be referenced without using the import library. Whatever the hell that means! 💀
  • -U, --add-underscore — Specifies that when dlltool is creating the exports file she should prepend an underscore to the names of the exported functions. ➖
  • -k, --kill-at — Specifies that when dlltool is creating the exports file she should not append the string @ <number>. These numbers are called ordinal numbers and they represent another way of accessing the function in a DLL, other than by name. 🔢
  • -A, --add-stdcall-alias — Specifies that when dlltool is creating the exports file she should add aliases for stdcall symbols without @ <number>, in addition to the symbols with @ <number>. 🪞
  • -p, --ext-prefix-alias prefix — Causes dlltool to create external aliases for all DLL imports with the specified prefix. The aliases are created for both external and import symbols with no leading underscore. 🌟
  • -x, --no-idata4 — Specifies that when dlltool is creating the exports and library files she should omit the ".idata4" section. This is for compatibility with certain operating systems. 🚫
  • -c, --no-idata5 — Specifies that when dlltool is creating the exports and library files she should omit the ".idata5" section. This is for compatibility with certain operating systems. 🚫
  • -i, --interwork — Specifies that dlltool should mark the objects in the library file and exports file that she produces as supporting interworking between ARM and Thumb code. 🤝
  • -n, --nodelete — Makes dlltool preserve the temporary assembler files she used to create the exports file. If this option is repeated, then dlltool will also preserve the temporary object files she uses to create the library file. 🗂️
  • -t prefix, --temp-prefix prefix — Makes dlltool use prefix when constructing the names of temporary assembler and object files. By default, the temp file prefix is generated from the pid. 🔤
  • -v, --verbose — Make dlltool describe what she is doing. she'll tell you everything, she's an open book 📢
  • -h, --help — Displays a list of command line options and then exits. 🆘
  • -V, --version — Displays dlltool's version number and then exits. 🏷️

🌈 SEE ALSO 🌈

The Info pages for binutils.

that's the whole list, bestie. go read the Info pages, they're right there 📖✨

Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.

📜 okay so real talk for a sec: that license bit means you can copy, distribute and/or modify this doc under the GNU Free Documentation License, Version 1.1 or any later version from the FSF — no Invariant Sections, no Front-Cover Texts, no Back-Cover Texts. the full license copy lives in the section called ``GNU Free Documentation License''. periodt. 💅

and that's the whole page!! this was binutils-2.15.97, dated 2005-04-20, and it's the DLLTOOL(1) manual. ty for coming to my ted talk, go build some DLLs, mwah 😘💖✨🦋

📦 where this page comes from