Frequently Asked Questions about ZLIB1.DLLThis document describes the design, the rationale, and the usageof the official DLL build of zlib, named ZLIB1.DLL.  If you havegeneral questions about zlib, you should see the file "FAQ" foundin the zlib distribution, or at the following location:  http://www.gzip.org/zlib/zlib_faq.html 1. What is ZLIB1.DLL, and how can I get it?  - ZLIB1.DLL is the official build of zlib as a DLL.    (Please remark the character '1' in the name.)    Pointers to a precompiled ZLIB1.DLL can be found in the zlib    web site at:      http://www.zlib.org/    Applications that link to ZLIB1.DLL can rely on the following    specification:    * The exported symbols are exclusively defined in the source      files "zlib.h" and "zlib.def", found in an official zlib      source distribution.    * The symbols are exported by name, not by ordinal.    * The exported names are undecorated.    * The calling convention of functions is "C" (CDECL).    * The ZLIB1.DLL binary is linked to MSVCRT.DLL.    The archive in which ZLIB1.DLL is bundled contains compiled    test programs that must run with a valid build of ZLIB1.DLL.    It is recommended to download the prebuilt DLL from the zlib    web site, instead of building it yourself, to avoid potential    incompatibilities that could be introduced by your compiler    and build settings.  If you do build the DLL yourself, please    make sure that it complies with all the above requirements,    and it runs with the precompiled test programs, bundled with    the original ZLIB1.DLL distribution.    If, for any reason, you need to build an incompatible DLL,    please use a different file name. 2. Why did you change the name of the DLL to ZLIB1.DLL?    What happened to the old ZLIB.DLL?  - The old ZLIB.DLL, built from zlib-1.1.4 or earlier, required    compilation settings that were incompatible to those used by    a static build.  The DLL settings were supposed to be enabled    by defining the macro ZLIB_DLL, before including "zlib.h".    Incorrect handling of this macro was silently accepted at    build time, resulting in two major problems:    * ZLIB_DLL was missing from the old makefile.  When building      the DLL, not all people added it to the build options.  In      consequence, incompatible incarnations of ZLIB.DLL started      to circulate around the net.    * When switching from using the static library to using the      DLL, applications had to define the ZLIB_DLL macro and      to recompile all the sources that contained calls to zlib      functions.  Failure to do so resulted in creating binaries      that were unable to run with the official ZLIB.DLL build.    The only possible solution that we could foresee was to make    a binary-incompatible change in the DLL interface, in order to    remove the dependency on the ZLIB_DLL macro, and to release    the new DLL under a different name.    We chose the name ZLIB1.DLL, where '1' indicates the major    zlib version number.  We hope that we will not have to break    the binary compatibility again, at least not as long as the    zlib-1.x series will last.    There is still a ZLIB_DLL macro, that can trigger a more    efficient build and use of the DLL, but compatibility no    longer dependents on it. 3. Can I build ZLIB.DLL from the new zlib sources, and replace    an old ZLIB.DLL, that was built from zlib-1.1.4 or earlier?  - In principle, you can do it by assigning calling convention    keywords to the macros ZEXPORT and ZEXPORTVA.  In practice,    it depends on what you mean by "an old ZLIB.DLL", because the    old DLL exists in several mutually-incompatible versions.    You have to find out first what kind of calling convention is    being used in your particular ZLIB.DLL build, and to use the    same one in the new build.  If you don't know what this is all    about, you might be better off if you would just leave the old    DLL intact. 4. Can I compile my application using the new zlib interface, and    link it to an old ZLIB.DLL, that was built from zlib-1.1.4 or    earlier?  - The official answer is "no"; the real answer depends again on    what kind of ZLIB.DLL you have.  Even if you are lucky, this    course of action is unreliable.    If you rebuild your application and you intend to use a newer    version of zlib (post- 1.1.4), it is strongly recommended to    link it to the new ZLIB1.DLL. 5. Why are the zlib symbols exported by name, and not by ordinal?  - Although exporting symbols by ordinal is a little faster, it    is risky.  Any single glitch in the maintenance or use of the    DEF file that contains the ordinals can result in incompatible    builds and frustrating crashes.  Simply put, the benefits of    exporting symbols by ordinal do not justify the risks.    Technically, it should be possible to maintain ordinals in    the DEF file, and still export the symbols by name.  Ordinals    exist in every DLL, and even if the dynamic linking performed    at the DLL startup is searching for names, ordinals serve as    hints, for a faster name lookup.  However, if the DEF file    contains ordinals, the Microsoft linker automatically builds    an implib that will cause the executables linked to it to use    those ordinals, and not the names.  It is interesting to    notice that the GNU linker for Win32 does not suffer from this    problem.    It is possible to avoid the DEF file if the exported symbols    are accompanied by a "__declspec(dllexport)" attribute in the    source files.  You can do this in zlib by predefining the    ZLIB_DLL macro. 6. I see that the ZLIB1.DLL functions use the "C" (CDECL) calling    convention.  Why not use the STDCALL convention?    STDCALL is the standard convention in Win32, and I need it in    my Visual Basic project!    (For readability, we use CDECL to refer to the convention     triggered by the "__cdecl" keyword, STDCALL to refer to     the convention triggered by "__stdcall", and FASTCALL to     refer to the convention triggered by "__fastcall".)  - Most of the native Windows API functions (without varargs) use    indeed the WINAPI convention (which translates to STDCALL in    Win32), but the standard C functions use CDECL.  If a user    application is intrinsically tied to the Windows API (e.g.    it calls native Windows API functions such as CreateFile()),    sometimes it makes sense to decorate its own functions with    WINAPI.  But if ANSI C or POSIX portability is a goal (e.g.    it calls standard C functions such as fopen()), it is not a    sound decision to request the inclusion of <windows.h>, or to    use non-ANSI constructs, for the sole purpose to make the user    functions STDCALL-able.    The functionality offered by zlib is not in the category of    "Windows functionality", but is more like "C functionality".    Technically, STDCALL is not bad; in fact, it is slightly    faster than CDECL, and it works with variable-argument    functions, just like CDECL.  It is unfortunate that, in spite    of using STDCALL in the Windows API, it is not the default    convention used by the C compilers that run under Windows.    The roots of the problem reside deep inside the unsafety of    the K&R-style function prototypes, where the argument types    are not specified; but that is another story for another day.    The remaining fact is that CDECL is the default convention.    Even if an explicit convention is hard-coded into the function    prototypes inside C headers, problems may appear.  The    necessity to expose the convention in users' callbacks is one    of these problems.    The calling convention issues are also important when using    zlib in other programming languages.  Some of them, like Ada    (GNAT) and Fortran (GNU G77), have C bindings implemented    initially on Unix, and relying on the C calling convention.    On the other hand, the pre- .NET versions of Microsoft Visual    Basic require STDCALL, while Borland Delphi prefers, although    it does not require, FASTCALL.    In fairness to all possible uses of zlib outside the C    programming language, we choose the default "C" convention.    Anyone interested in different bindings or conventions is    encouraged to maintain specialized projects.  The "contrib/"    directory from the zlib distribution already holds a couple    of foreign bindings, such as Ada, C++, and Delphi. 7. I need a DLL for my Visual Basic project.  What can I do?  - Define the ZLIB_WINAPI macro before including "zlib.h", when    building both the DLL and the user application (except that    you don't need to define anything when using the DLL in Visual    Basic).  The ZLIB_WINAPI macro will switch on the WINAPI    (STDCALL) convention.  The name of this DLL must be different    than the official ZLIB1.DLL.    Gilles Vollant has contributed a build named ZLIBWAPI.DLL,