cleemesser  committed 8c2b4dd

added rst versions of html doc on stdcall and dlltool

  • Participants
  • Parent commits ce32a29

Comments (0)

Files changed (2)

File docs/dlltool.rst

+.. image:: dlltool_files/docs_header.gif
+    :alt: Red Hat Docs
+Search Docs:
+`Red Hat Docs`_  >  `Manuals`_  >  `Red Hat Enterprise Linux Manuals`_  >
+gnu Binary Utilities: Using binutils, the GNU Binary Utilities
+Chapter 14. Create files needed to build and use DLLs
+``dlltool`` may be used to create the files needed to build and use dynamic
+link libraries (DLLs).
+> *Warning:* ``dlltool`` is not always built as part of the binary utilities,
+since it is only useful for those targets which support DLLs.
+::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 ?]
+``dlltool`` reads its inputs, which can come from the ``-d`` and ``-b``
+options as well as object files specified on the command line. It then
+processes these inputs and if the ``-e`` option has been specified it creates
+a exports file. If the ``-l`` option has been specified it creates a library
+file and if the ``-z`` option has been specified it creates a def file. Any
+or all of the ``-e``, ``-l`` and ``-z`` options can be present in one
+invocation of dlltool.
+When creating a DLL, along with the source for the DLL, it is necessary to
+have three other files. ``dlltool`` can help with the creation of these
+The first file is a ``.def`` file which specifies which functions are
+exported from the DLL, which functions the DLL imports, and so on. This is a
+text file and can be created by hand, or ``dlltool`` can be used to create it
+using the ``-z`` option. In this case ``dlltool`` will scan the object files
+specified on its command line looking for those functions which have been
+specially marked as being exported and put entries for them in the .def file
+it creates.
+In order 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. This can be done in C by using the asm() operator:
+::  asm (".section .drectve");
+      asm (".ascii \"-export:my_func\"");
+      int my_func (void) { ? }
+The second file needed for DLL creation is an exports file. This file is
+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. This is a binary file
+and it can be created by giving the ``-e`` option to ``dlltool`` when it is
+creating or reading in a .def file.
+The third file needed for DLL creation is the library file that programs will
+link with in order to access the functions in the DLL. This file can be
+created by giving the ``-l`` option to dlltool when it is creating or reading
+in a .def file.
+``dlltool`` builds the library file by hand, but it builds the exports file
+by creating temporary files containing assembler statements and then
+assembling these. The ``-S`` command line option can be used to specify the
+path to the assembler that dlltool will use, and the ``-f`` option can be
+used to pass specific flags to that assembler. The ``-n`` can be used to
+prevent dlltool from deleting these temporary assembler files when it is
+done, and if ``-n`` is specified twice then this will prevent dlltool from
+deleting the temporary object files it used to build the library.
+Here is 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
+::  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
+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.
+Treat all global and weak defined symbols found in the input object files as
+symbols to be exported. There is a small list of symbols which are not
+exported by default; see the ``-no-default-excludes`` option. You may add to
+the list of symbols to not export by using the ``-exclude-symbols`` option.
+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
+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. 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. This option only takes one argument, and if it occurs
+more than once on the command line, then later occurrences will override
+earlier occurrences. So if it is necessary to pass multiple options to the
+assembler they should be enclosed in double quotes.
+``-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 upon how it was created,
+but this option can be used to override that. This is normally only useful
+when creating DLLs for an ARM processor, when the contents of the DLL are
+actually encode using Thumb instructions.
+``-a``, ``-add-indirect``
+Specifies that when ``dlltool`` is creating the exports file it 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 it should
+prepend an underscore to the names of the exported functions. The option is
+ignored for symbols with an explicit internal name specification provided in
+a .def file.
+``-k``, ``-kill-at``
+Specifies that when ``dlltool`` is creating the exports file it should not
+append the string ``@ <number>`` The option is ignored for symbols with an
+explicit internal name specification provided in a .def file.
+``-A``, ``-add-stdcall-alias``
+Specifies that when ``dlltool`` is creating the exports file it 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 it
+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 it
+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 it produces as supporting interworking between ARM and
+Thumb code.
+``-n``, ``-nodelete``
+Makes ``dlltool`` preserve the temporary assembler files it used to create
+the exports file. If this option is repeated then dlltool will also preserve
+the temporary object files it 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 it is doing.
+``-h``, ``-help``
+Displays a list of command line options and then exits.
+``-V``, ``-version``
+Displays dlltool's version number and then exits.
+windres readelf
+.. _Red Hat Docs:
+.. _Manuals:
+.. _Red Hat Enterprise Linux Manuals:
+.. _Prev:
+    /gnu-binutils/windres.html
+.. _Next:
+    /gnu-binutils/readelf.html
+.. _Home:
+    /gnu-binutils/index.html

File docs/stdcall_and_mingw.rst

+Stdcall and DLL tools of MSVC and MinGW
+The **__stdcall** calling convention has been there for a very long time.
+When the older calling conventions like **__pascal** fell into oblivion,
+**__stdcall** became the standard calling conventions of Win32 API functions.
+Unlike **__cdecl** (the *native* calling convention of C/C++), it is
+supported in C/C++, Visual Basic, Java, and other languages alike, which
+makes it the first choice when building a DLL for cross-language use.
+The internal representations of both **__cdecl** and **__stdcall** functions
+have *decorations*. In MSVC (Microsoft Visual C++) and MinGW (Minimalistic
+GNU for Windows) GCC, **__cdecl** function will be prefixed an underscore,
+and **__stdcall** functions will have the beginning underscore as well as be
+appended by the at-sign (``@``) followed by the number of bytes in the
+argument list. So, ``double __cdecl sin(double)`` will be decorated as
+``_sin``, and ``double __stdcall sin(double)`` will be decorated as
+But things are not that simple. The decorations could change when they appear
+in DLLs or when they are produced by different compilers. The following table
+lists the names as are produced by MSVC, MinGW, Digital Mars C/C++ Compiler
+(DMC), Borland C++ Compiler/C++ Builder (BCC):
+Calling Convention Internal* MSVC DLL (w/ DEF) MSVC DLL (dllexport) DMC DLL
+**``__stdcall``** ``_*Function*@*n*`` *``Function``* ``_*Function*@*n*``
+``_*Function*@*n*`` ``*Function*@*n*`` *``Function``*
+**``__cdecl``** ``_*Function*`` *``Function``* *``Function``* *``Function``*
+*``Function``* ``_*Function*``
+* For all but BCC, which has the same naming convention for symbols in code
+and exported name in DLL.
+What a mess (especially when you notice that, for MSVC, whether a name is
+exported by a DEF file or by the ``__declspec(dllexport)`` attribute affects
+its naming decoration)! And although the ending decoration clearly shows how
+many bytes the called function pops up from stack beforereturning, it is not
+necessarily the most frequently used form. E.g., the Win32 API functions in
+the system DLLs have no decoration at all, as in the case ones uses a DEF
+file when exporting functions with MSVC. Many DLLs intended for multi-
+language usage also follow this practice and use no decoration with
+**__stdcall** functions (although the Java Native Interface, on Win32
+platforms, will accept functions either undecorated or decorated in the
+Microsoft way, the latter being the preferred form). The remaining part of
+this article is thus devoted to the creation and use of such DLLs with MSVC
+and MinGW, as well as the introduction and comparison of related tools (there
+are good articles at ``_ explaining the
+complexities of DLLs with Borland C++ Builder, so I need not bother to say
+anything more about it).
+Tools working with DEF files
+First, I will talk about the DEF file format and the relevant tools used with
+MSVC and MinGW. Many intricacies lie here.
+DEF file format
+We care about only two sections of the DEF file: the LIBRARY section and the
+EXPORTS section. The LIBRARY section specifies the internal name of the DLL;
+and the EXPORTS section specifies the function or data items to export. A
+short example follows:
+> ::LIBRARY    testdll.dll
+>     EXPORTS
+>         cdeclFunction                       @1
+>         _stdcallFunction@8                  @2
+>         aliasName = cdeclFunction           @3
+This DEF file defines three exports for a testdll.dll: the first one is a
+**__cdecl** function, the second one a **__stdcall** function, and the third
+one an alias of the first function. The three functions are also assigned
+*ordinals*. A function can be called by its name or its ordinal.
+**CL** can accept a DEF file on the command line, and it simply passes the
+file name to **LINK**. E.g.,
+> ::cl /LD testdll.obj testdll.def
+will become
+> ::link /out:testdll.dll /dll /implib:testdll.lib /def:testdll.def
+**LINK** is our most important tool when treating DLL and DEF files with
+MSVC. The command line mentioned in **CL** already shows the options commonly
+used when creating a DLL with a DEF file. The main point is: if we do not use
+a DEF file when creating a DLL, the exported name of a **__stdcall** function
+will be ``_*Function*@*n*``; but if we use a DEF file, the exported name
+could be either *``Function``* or ``_*Function*@*n*``; if both names appear,
+only the undecorated form is used. But it is possible to get both forms of
+exports (similar to the ``--add-stdcall-alias`` option of GNU **ld** and
+**dllwrap**), when we have the following line in the EXPORTS section (notice
+that the order cannot be reversed):
+> ::TestFunction = _TestFunction@4
+Another thing to notice when we use the above line: **LINK** will export both
+``TestFunction`` (or any alias name) and ``_TestFunction@4`` from the DLL,
+but *only* ``_TestFunction@4`` (the internal name) will be output to the
+import library: in no case will a program linked with the import library call
+the function by ``TestFunction``!
+If we have the DLL from somebody else (no source available), and we have the
+DEF file, the easiest way to create an import library is to use the **LIB**
+tool. The following syntax is often enough (check `MSDN`_ for more details):
+> ::lib /def:*DEF_file*
+*Nota bene*: 1) it seems **LIB** does not accept aliased forms (it will
+simply ignore the part after the equal-sign); 2) it assumes all functions in
+the DEF file **__cdecl**. The second point lies in the fact that the import
+library it produces will map each symbol in the DLL to an internal name with
+an underscore prefixed, i.e., the linker using the import library will try to
+resolve an undefined symbol ``_Function`` to the symbol ``Function`` in the
+DLL. It takes no special care of the **__stdcall** calling convention. With
+some techniques we could use **LIB** to produce import libraries for
+**__stdcall** functions, but the caller could only call them by ordinal, not
+by name. The details are left as an exercise :-).
+Here we use **gcc** to call **ld**. The reason why we do not use **ld**
+directly is that using **gcc** is generally more convenient. The ``-shared``
+option is specially designed to produce DLLs. We could also use the ``-Wl``
+option to pass special link options.
+GNU **ld** has many options regarding DLLs, but we shall only focus on four
+(help information follows):
+> ::--add-stdcall-alias                Export symbols with and without @nn
+>     --kill-at                          Remove @nn from exported symbols
+>     --out-implib <file>                Generate import library
+>     --output-def <file>                Generate a .DEF file for the built
+Either **gcc** or **ld** can accept a DEF file directly on the command line.
+When we have the following line in the EXPORTS section,
+> ::TestFunction = TestFunction@4
+both symbols will be exported to the DLL. This behaviour is different from
+**dllwrap**, which we shall talk of immediately.
+GNU **dllwrap** could produce a DLL by a DEF file. We generally use
+**dllwrap** in the following syntax,
+> ::dllwrap --def *DEF_file* -o *DLL_file* *OBJ_files* [--output-lib
+and **dllwrap** will transparently call **gcc**, **ld**, and **dlltool** to
+fulfil its task. If **dllwrap** is asked to produce an import library
+(``--output-lib``), it will let **dlltool** do it. Unlike **LINK** or **ld**,
+when **dllwrap** encounters a line in the EXPORTS section like
+> ::TestFunction = TestFunction@4
+it will export ``TestFunction`` but not ``TestFunction@4``, and only
+``TestFunction`` is output to the import library (somehow similar to
+GNU **dlltool** may be used to create the files needed to build and use
+dynamic link libraries (DLLs). The following options are of interest to us
+> ::-l --output-lib <outname> Generate an interface library.
+>     -D --dllname <name>       Name of input dll to put into interface lib.
+>     -d --input-def <deffile>  Name of .def file to be read in.
+>     -U --add-underscore       Add underscores to symbols in interface
+>     -k --kill-at              Kill @<n> from exported names.
+**dlltool** works like **LIB**, but it has its special feature: the ``-U``
+option makes the items in the DEF file map to symbols prefixed with an
+underscore in the DLL, and the ``-k`` option makes the items in the DEF file
+map to symbols stripped of ``@*n*`` in the DLL.
+This is a stand-alone open-source tool to produce a DEF file from a given
+DLL. It is not distributed with MSVC or MinGW, and you may choose to download
+`here`_ if you do not find it elsewhere.
+The __stdcall DLL and the import library
+Having learnt so much about the tools, now we are ready to do what we wanted.
+We still need **sed** (search on the Internet if you do not already have this
+useful tool), and a knowledge of regular expression is required to understand
+thoroughly how it works.
+Microsoft Visual C++
+The simplest way to produce a DLL is to use the ``/LD`` command-line option
+of **CL**:
+> ::cl /LD *OBJ_files*
+The resulting DLL will have exported names like ``_MyFunction@8``, as is
+shown in the `MSVC DLL (no DEF)' column above. To create symbols with no
+decoration, we must use a DEF file. The following is an automatic way to
+create a DEF file from the DLL if **__declspec(dllexport)** is used to
+indicate which functions to export:
+> ::link /out:*DLL_file* /dll *OBJ_files
+>     *pexports *DLL_file* | sed "s/^_\([[:alnum:]_]\+\)@[[:digit:]]\+/\1/" >
+Once you have the object files and the DEF file, creating the DLL and the
+import library can be done in one step:
+> ::link /out:*DLL_file* /dll /def:*DEF_file* /implib:*LIB_file* *OBJ_files*
+And you are free to use the DLL and the import library now as you wish.
+If we do not need to control which functions to export except by
+**__declspec(dllexport)**, we can type:
+> ::gcc -shared -o *DLL_file* *OBJ_files* -Wl,--output-def,*DEF_file
+>     *gcc -shared -o *DLL_file* *OBJ_files* -Wl,--kill-at
+>     dlltool -d *DEF_file* --dllname *DLL_file* --output-lib *LIB_file*
+If we want to use a DEF file to control which functions to export, we can
+start by (assuming **__declspec(dllexport)** is used to indicate which
+functions to export)
+> ::gcc -shared -o *DLL_file* *OBJ_files* -Wl,--kill-at,--output-
+to produce a DEF file with exports like "``*Function* = *Function*@*n*
+@*Ordinal*``". After editing it to our will, the following commands will
+finish the job:
+> ::dllwrap --def *DEF_file* -o *DLL_file* *OBJ_files
+>     *sed "s/[[:alnum:]_]\+ *= *//" *DEF_file* > *New_DEF_file
+>     *dlltool -d *New_DEF_file* --dllname *DLL_file* --output-lib *LIB_file*
+And the import library is now at your hand to use.
+I am not sure whether I have stated clearly, but I have listed all my
+findings when I struggled to find out how to use the DLL tools properly and
+how to deal with **__stdcall** functions in DLLs. Hope you find it useful.
+**ACKNOWLEDGEMENT: **The MinGW mailing list provided much useful information;
+Luke Dunstan provided important suggestions and corrections.
+2002-8-20, written by Wu Yongwei
+2003-3-6, last revised by Wu Yongwei
+`Return to Main`_
+.. _
+.. _MSDN:
+.. _here:
+.. _Return to Main: