|Frequently Asked Questions about ZLIB1.DLL
|This document describes the design, the rationale, and the usage
|of the official DLL build of zlib, named ZLIB1.DLL. If you have
|general questions about zlib, you should see the file "FAQ" found
|in the zlib distribution, or at the following location:
|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:
|Applications that link to ZLIB1.DLL can rely on the following
|* The exported symbols are exclusively defined in the source
|files "zlib.h" and "zlib.def", found in an official zlib
|* 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
|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
|- 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
|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
|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
|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,
|with the ZLIB_WINAPI macro turned on, and with the minizip
|functionality built in. For more information, please read
|the notes inside "contrib/vstudio/readme.txt", found in the
|8. I need to use zlib in my Microsoft .NET project. What can I
|- Henrik Ravn has contributed a .NET wrapper around zlib. Look
|into contrib/dotzlib/, inside the zlib distribution.
|9. If my application uses ZLIB1.DLL, should I link it to
|- It is not required, but it is recommended to link your
|application to MSVCRT.DLL, if it uses ZLIB1.DLL.
|The executables (.EXE, .DLL, etc.) that are involved in the
|same process and are using the C run-time library (i.e. they
|are calling standard C functions), must link to the same
|library. There are several libraries in the Win32 system:
|CRTDLL.DLL, MSVCRT.DLL, the static C libraries, etc.
|Since ZLIB1.DLL is linked to MSVCRT.DLL, the executables that
|depend on it should also be linked to MSVCRT.DLL.
|10. Why are you saying that ZLIB1.DLL and my application should
|be linked to the same C run-time (CRT) library? I linked my
|application and my DLLs to different C libraries (e.g. my
|application to a static library, and my DLLs to MSVCRT.DLL),
|and everything works fine.
|- If a user library invokes only pure Win32 API (accessible via
|<windows.h> and the related headers), its DLL build will work
|in any context. But if this library invokes standard C API,
|things get more complicated.
|There is a single Win32 library in a Win32 system. Every
|function in this library resides in a single DLL module, that
|is safe to call from anywhere. On the other hand, there are
|multiple versions of the C library, and each of them has its
|own separate internal state. Standalone executables and user
|DLLs that call standard C functions must link to a C run-time
|(CRT) library, be it static or shared (DLL). Intermixing
|occurs when an executable (not necessarily standalone) and a
|DLL are linked to different CRTs, and both are running in the
|Intermixing multiple CRTs is possible, as long as their
|internal states are kept intact. The Microsoft Knowledge Base
|articles KB94248 "HOWTO: Use the C Run-Time" and KB140584
|"HOWTO: Link with the Correct C Run-Time (CRT) Library"
|mention the potential problems raised by intermixing.
|If intermixing works for you, it's because your application
|and DLLs are avoiding the corruption of each of the CRTs'
|internal states, maybe by careful design, or maybe by fortune.
|Also note that linking ZLIB1.DLL to non-Microsoft CRTs, such
|as those provided by Borland, raises similar problems.
|11. Why are you linking ZLIB1.DLL to MSVCRT.DLL?
|- MSVCRT.DLL exists on every Windows 95 with a new service pack
|installed, or with Microsoft Internet Explorer 4 or later, and
|on all other Windows 4.x or later (Windows 98, Windows NT 4,
|or later). It is freely distributable; if not present in the
|system, it can be downloaded from Microsoft or from other
|software provider for free.
|The fact that MSVCRT.DLL does not exist on a virgin Windows 95
|is not so problematic. Windows 95 is scarcely found nowadays,
|Microsoft ended its support a long time ago, and many recent
|applications from various vendors, including Microsoft, do not
|even run on it. Furthermore, no serious user should run
|Windows 95 without a proper update installed.
|12. Why are you not linking ZLIB1.DLL to
|<<my favorite C run-time library>> ?
|- We considered and abandoned the following alternatives:
|* Linking ZLIB1.DLL to a static C library (LIBC.LIB, or
|LIBCMT.LIB) is not a good option. People are using the DLL
|mainly to save disk space. If you are linking your program
|to a static C library, you may as well consider linking zlib
|in statically, too.
|* Linking ZLIB1.DLL to CRTDLL.DLL looks appealing, because
|CRTDLL.DLL is present on every Win32 installation.
|Unfortunately, it has a series of problems: it does not
|work properly with Microsoft's C++ libraries, it does not
|provide support for 64-bit file offsets, (and so on...),
|and Microsoft discontinued its support a long time ago.
|* Linking ZLIB1.DLL to MSVCR70.DLL or MSVCR71.DLL, supplied
|with the Microsoft .NET platform, and Visual C++ 7.0/7.1,
|raises problems related to the status of ZLIB1.DLL as a
|system component. According to the Microsoft Knowledge Base
|article KB326922 "INFO: Redistribution of the Shared C
|Runtime Component in Visual C++ .NET", MSVCR70.DLL and
|MSVCR71.DLL are not supposed to function as system DLLs,
|because they may clash with MSVCRT.DLL. Instead, the
|application's installer is supposed to put these DLLs
|(if needed) in the application's private directory.
|If ZLIB1.DLL depends on a non-system runtime, it cannot
|function as a redistributable system component.
|* Linking ZLIB1.DLL to non-Microsoft runtimes, such as
|Borland's, or Cygwin's, raises problems related to the
|reliable presence of these runtimes on Win32 systems.
|It's easier to let the DLL build of zlib up to the people
|who distribute these runtimes, and who may proceed as
|explained in the answer to Question 14.
|13. If ZLIB1.DLL cannot be linked to MSVCR70.DLL or MSVCR71.DLL,
|how can I build/use ZLIB1.DLL in Microsoft Visual C++ 7.0
|(Visual Studio .NET) or newer?
|- Due to the problems explained in the Microsoft Knowledge Base
|article KB326922 (see the previous answer), the C runtime that
|comes with the VC7 environment is no longer considered a
|system component. That is, it should not be assumed that this
|runtime exists, or may be installed in a system directory.
|Since ZLIB1.DLL is supposed to be a system component, it may
|not depend on a non-system component.
|In order to link ZLIB1.DLL and your application to MSVCRT.DLL
|in VC7, you need the library of Visual C++ 6.0 or older. If
|you don't have this library at hand, it's probably best not to
|We are hoping that, in the future, Microsoft will provide a
|way to build applications linked to a proper system runtime,
|from the Visual C++ environment. Until then, you have a
|couple of alternatives, such as linking zlib in statically.
|If your application requires dynamic linking, you may proceed
|as explained in the answer to Question 14.
|14. I need to link my own DLL build to a CRT different than
|MSVCRT.DLL. What can I do?
|- Feel free to rebuild the DLL from the zlib sources, and link
|it the way you want. You should, however, clearly state that
|your build is unofficial. You should give it a different file
|name, and/or install it in a private directory that can be
|accessed by your application only, and is not visible to the
|others (i.e. it's neither in the PATH, nor in the SYSTEM or
|SYSTEM32 directories). Otherwise, your build may clash with
|applications that link to the official build.
|For example, in Cygwin, zlib is linked to the Cygwin runtime
|CYGWIN1.DLL, and it is distributed under the name CYGZ.DLL.
|15. May I include additional pieces of code that I find useful,
|link them in ZLIB1.DLL, and export them?
|- No. A legitimate build of ZLIB1.DLL must not include code
|that does not originate from the official zlib source code.
|But you can make your own private DLL build, under a different
|file name, as suggested in the previous answer.
|For example, zlib is a part of the VCL library, distributed
|with Borland Delphi and C++ Builder. The DLL build of VCL
|is a redistributable file, named VCLxx.DLL.
|16. May I remove some functionality out of ZLIB1.DLL, by enabling
|macros like NO_GZCOMPRESS or NO_GZIP at compile time?
|- No. A legitimate build of ZLIB1.DLL must provide the complete
|zlib functionality, as implemented in the official zlib source
|code. But you can make your own private DLL build, under a
|different file name, as suggested in the previous answer.
|17. I made my own ZLIB1.DLL build. Can I test it for compliance?
|- We prefer that you download the official DLL from the zlib
|web site. If you need something peculiar from this DLL, you
|can send your suggestion to the zlib mailing list.
|However, in case you do rebuild the DLL yourself, you can run
|it with the test programs found in the DLL distribution.
|Running these test programs is not a guarantee of compliance,
|but a failure can imply a detected problem.
|This document is written and maintained by
|Cosmin Truta <email@example.com>