binutils: dlltool
1
1 14 dlltool
1 **********
1
1 'dlltool' is used to create the files needed to create dynamic link
1 libraries (DLLs) on systems which understand PE format image files such
1 as Windows. A DLL contains an export table which contains information
1 that the runtime loader needs to resolve references from a referencing
1 program.
1
1 The export table is generated by this program by reading in a '.def'
1 file or scanning the '.a' and '.o' files which will be in the DLL. A
1 '.o' file can contain information in special '.drectve' sections with
1 export information.
1
1 _Note:_ 'dlltool' is not always built as part of the binary
1 utilities, since it is only useful for those targets which support
1 DLLs.
1
1 dlltool [-d|--input-def DEF-FILE-NAME]
1 [-b|--base-file BASE-FILE-NAME]
1 [-e|--output-exp EXPORTS-FILE-NAME]
1 [-z|--output-def DEF-FILE-NAME]
1 [-l|--output-lib LIBRARY-FILE-NAME]
1 [-y|--output-delaylib LIBRARY-FILE-NAME]
1 [--export-all-symbols] [--no-export-all-symbols]
1 [--exclude-symbols LIST]
1 [--no-default-excludes]
1 [-S|--as PATH-TO-ASSEMBLER] [-f|--as-flags OPTIONS]
1 [-D|--dllname NAME] [-m|--machine MACHINE]
1 [-a|--add-indirect]
1 [-U|--add-underscore] [--add-stdcall-underscore]
1 [-k|--kill-at] [-A|--add-stdcall-alias]
1 [-p|--ext-prefix-alias PREFIX]
1 [-x|--no-idata4] [-c|--no-idata5]
1 [--use-nul-prefixed-import-tables]
1 [-I|--identify LIBRARY-FILE-NAME] [--identify-strict]
1 [-i|--interwork]
1 [-n|--nodelete] [-t|--temp-prefix PREFIX]
1 [-v|--verbose]
1 [-h|--help] [-V|--version]
1 [--no-leading-underscore] [--leading-underscore]
1 [object-file ...]
1
1 'dlltool' reads its inputs, which can come from the '-d' and '-b'
1 options as well as object files specified on the command line. It then
1 processes these inputs and if the '-e' option has been specified it
1 creates a exports file. If the '-l' option has been specified it
1 creates a library file and if the '-z' option has been specified it
1 creates a def file. Any or all of the '-e', '-l' and '-z' options can
1 be present in one invocation of dlltool.
1
1 When creating a DLL, along with the source for the DLL, it is
1 necessary to have three other files. 'dlltool' can help with the
1 creation of these files.
1
1 The first file is a '.def' file which specifies which functions are
1 exported from the DLL, which functions the DLL imports, and so on. This
1 is a text file and can be created by hand, or 'dlltool' can be used to
1 create it using the '-z' option. In this case 'dlltool' will scan the
1 object files specified on its command line looking for those functions
1 which have been specially marked as being exported and put entries for
1 them in the '.def' file it creates.
1
1 In order to mark a function as being exported from a DLL, it needs to
1 have an '-export:<name_of_function>' entry in the '.drectve' section of
1 the object file. This can be done in C by using the asm() operator:
1
1 asm (".section .drectve");
1 asm (".ascii \"-export:my_func\"");
1
1 int my_func (void) { ... }
1
1 The second file needed for DLL creation is an exports file. This
1 file is linked with the object files that make up the body of the DLL
1 and it handles the interface between the DLL and the outside world.
1 This is a binary file and it can be created by giving the '-e' option to
1 'dlltool' when it is creating or reading in a '.def' file.
1
1 The third file needed for DLL creation is the library file that
1 programs will link with in order to access the functions in the DLL (an
1 'import library'). This file can be created by giving the '-l' option
1 to dlltool when it is creating or reading in a '.def' file.
1
1 If the '-y' option is specified, dlltool generates a delay-import
1 library that can be used instead of the normal import library to allow a
1 program to link to the dll only as soon as an imported function is
1 called for the first time. The resulting executable will need to be
1 linked to the static delayimp library containing __delayLoadHelper2(),
1 which in turn will import LoadLibraryA and GetProcAddress from kernel32.
1
1 'dlltool' builds the library file by hand, but it builds the exports
1 file by creating temporary files containing assembler statements and
1 then assembling these. The '-S' command line option can be used to
1 specify the path to the assembler that dlltool will use, and the '-f'
1 option can be used to pass specific flags to that assembler. The '-n'
1 can be used to prevent dlltool from deleting these temporary assembler
1 files when it is done, and if '-n' is specified twice then this will
1 prevent dlltool from deleting the temporary object files it used to
1 build the library.
1
1 Here is an example of creating a DLL from a source file 'dll.c' and
1 also creating a program (from an object file called 'program.o') that
1 uses that DLL:
1
1 gcc -c dll.c
1 dlltool -e exports.o -l dll.lib dll.o
1 gcc dll.o exports.o -o dll.dll
1 gcc program.o dll.lib -o program
1
1 'dlltool' may also be used to query an existing import library to
1 determine the name of the DLL to which it is associated. See the
1 description of the '-I' or '--identify' option.
1
1 The command line options have the following meanings:
1
1 '-d FILENAME'
1 '--input-def FILENAME'
1 Specifies the name of a '.def' file to be read in and processed.
1
1 '-b FILENAME'
1 '--base-file FILENAME'
1 Specifies the name of a base file to be read in and processed. The
1 contents of this file will be added to the relocation section in
1 the exports file generated by dlltool.
1
1 '-e FILENAME'
1 '--output-exp FILENAME'
1 Specifies the name of the export file to be created by dlltool.
1
1 '-z FILENAME'
1 '--output-def FILENAME'
1 Specifies the name of the '.def' file to be created by dlltool.
1
1 '-l FILENAME'
1 '--output-lib FILENAME'
1 Specifies the name of the library file to be created by dlltool.
1
1 '-y FILENAME'
1 '--output-delaylib FILENAME'
1 Specifies the name of the delay-import library file to be created
1 by dlltool.
1
1 '--export-all-symbols'
1 Treat all global and weak defined symbols found in the input object
1 files as symbols to be exported. There is a small list of symbols
1 which are not exported by default; see the '--no-default-excludes'
1 option. You may add to the list of symbols to not export by using
1 the '--exclude-symbols' option.
1
1 '--no-export-all-symbols'
1 Only export symbols explicitly listed in an input '.def' file or in
1 '.drectve' sections in the input object files. This is the default
1 behaviour. The '.drectve' sections are created by 'dllexport'
1 attributes in the source code.
1
1 '--exclude-symbols LIST'
1 Do not export the symbols in LIST. This is a list of symbol names
1 separated by comma or colon characters. The symbol names should
1 not contain a leading underscore. This is only meaningful when
1 '--export-all-symbols' is used.
1
1 '--no-default-excludes'
1 When '--export-all-symbols' is used, it will by default avoid
1 exporting certain special symbols. The current list of symbols to
1 avoid exporting is 'DllMain@12', 'DllEntryPoint@0', 'impure_ptr'.
1 You may use the '--no-default-excludes' option to go ahead and
1 export these special symbols. This is only meaningful when
1 '--export-all-symbols' is used.
1
1 '-S PATH'
1 '--as PATH'
1 Specifies the path, including the filename, of the assembler to be
1 used to create the exports file.
1
1 '-f OPTIONS'
1 '--as-flags OPTIONS'
1 Specifies any specific command line options to be passed to the
1 assembler when building the exports file. This option will work
1 even if the '-S' option is not used. This option only takes one
1 argument, and if it occurs more than once on the command line, then
1 later occurrences will override earlier occurrences. So if it is
1 necessary to pass multiple options to the assembler they should be
1 enclosed in double quotes.
1
1 '-D NAME'
1 '--dll-name NAME'
1 Specifies the name to be stored in the '.def' file as the name of
1 the DLL when the '-e' option is used. If this option is not
1 present, then the filename given to the '-e' option will be used as
1 the name of the DLL.
1
1 '-m MACHINE'
1 '-machine MACHINE'
1 Specifies the type of machine for which the library file should be
1 built. 'dlltool' has a built in default type, depending upon how
1 it was created, but this option can be used to override that. This
1 is normally only useful when creating DLLs for an ARM processor,
1 when the contents of the DLL are actually encode using Thumb
1 instructions.
1
1 '-a'
1 '--add-indirect'
1 Specifies that when 'dlltool' is creating the exports file it
1 should add a section which allows the exported functions to be
1 referenced without using the import library. Whatever the hell
1 that means!
1
1 '-U'
1 '--add-underscore'
1 Specifies that when 'dlltool' is creating the exports file it
1 should prepend an underscore to the names of _all_ exported
1 symbols.
1
1 '--no-leading-underscore'
1 '--leading-underscore'
1 Specifies whether standard symbol should be forced to be prefixed,
1 or not.
1
1 '--add-stdcall-underscore'
1 Specifies that when 'dlltool' is creating the exports file it
1 should prepend an underscore to the names of exported _stdcall_
1 functions. Variable names and non-stdcall function names are not
1 modified. This option is useful when creating GNU-compatible
1 import libs for third party DLLs that were built with MS-Windows
1 tools.
1
1 '-k'
1 '--kill-at'
1 Specifies that '@<number>' suffixes should be omitted from the
1 names of stdcall functions that will be imported from the DLL. This
1 is useful when creating an import library for a DLL which exports
1 stdcall functions but without the usual '@<number>' symbol name
1 suffix.
1
1 This does not change the naming of symbols provided by the import
1 library to programs linked against it, but only the entries in the
1 import table (ie the .idata section).
1
1 '-A'
1 '--add-stdcall-alias'
1 Specifies that when 'dlltool' is creating the exports file it
1 should add aliases for stdcall symbols without '@ <number>' in
1 addition to the symbols with '@ <number>'.
1
1 '-p'
1 '--ext-prefix-alias PREFIX'
1 Causes 'dlltool' to create external aliases for all DLL imports
1 with the specified prefix. The aliases are created for both
1 external and import symbols with no leading underscore.
1
1 '-x'
1 '--no-idata4'
1 Specifies that when 'dlltool' is creating the exports and library
1 files it should omit the '.idata4' section. This is for
1 compatibility with certain operating systems.
1
1 '--use-nul-prefixed-import-tables'
1 Specifies that when 'dlltool' is creating the exports and library
1 files it should prefix the '.idata4' and '.idata5' by zero an
1 element. This emulates old gnu import library generation of
1 'dlltool'. By default this option is turned off.
1
1 '-c'
1 '--no-idata5'
1 Specifies that when 'dlltool' is creating the exports and library
1 files it should omit the '.idata5' section. This is for
1 compatibility with certain operating systems.
1
1 '-I FILENAME'
1 '--identify FILENAME'
1 Specifies that 'dlltool' should inspect the import library
1 indicated by FILENAME and report, on 'stdout', the name(s) of the
1 associated DLL(s). This can be performed in addition to any other
1 operations indicated by the other options and arguments. 'dlltool'
1 fails if the import library does not exist or is not actually an
1 import library. See also '--identify-strict'.
1
1 '--identify-strict'
1 Modifies the behavior of the '--identify' option, such that an
1 error is reported if FILENAME is associated with more than one DLL.
1
1 '-i'
1 '--interwork'
1 Specifies that 'dlltool' should mark the objects in the library
1 file and exports file that it produces as supporting interworking
1 between ARM and Thumb code.
1
1 '-n'
1 '--nodelete'
1 Makes 'dlltool' preserve the temporary assembler files it used to
1 create the exports file. If this option is repeated then dlltool
1 will also preserve the temporary object files it uses to create the
1 library file.
1
1 '-t PREFIX'
1 '--temp-prefix PREFIX'
1 Makes 'dlltool' use PREFIX when constructing the names of temporary
1 assembler and object files. By default, the temp file prefix is
1 generated from the pid.
1
1 '-v'
1 '--verbose'
1 Make dlltool describe what it is doing.
1
1 '-h'
1 '--help'
1 Displays a list of command line options and then exits.
1
1 '-V'
1 '--version'
1 Displays dlltool's version number and then exits.
1
Menu