cannam@89: cannam@89: Frequently Asked Questions about ZLIB1.DLL cannam@89: cannam@89: cannam@89: This document describes the design, the rationale, and the usage cannam@89: of the official DLL build of zlib, named ZLIB1.DLL. If you have cannam@89: general questions about zlib, you should see the file "FAQ" found cannam@89: in the zlib distribution, or at the following location: cannam@89: http://www.gzip.org/zlib/zlib_faq.html cannam@89: cannam@89: cannam@89: 1. What is ZLIB1.DLL, and how can I get it? cannam@89: cannam@89: - ZLIB1.DLL is the official build of zlib as a DLL. cannam@89: (Please remark the character '1' in the name.) cannam@89: cannam@89: Pointers to a precompiled ZLIB1.DLL can be found in the zlib cannam@89: web site at: cannam@89: http://www.zlib.net/ cannam@89: cannam@89: Applications that link to ZLIB1.DLL can rely on the following cannam@89: specification: cannam@89: cannam@89: * The exported symbols are exclusively defined in the source cannam@89: files "zlib.h" and "zlib.def", found in an official zlib cannam@89: source distribution. cannam@89: * The symbols are exported by name, not by ordinal. cannam@89: * The exported names are undecorated. cannam@89: * The calling convention of functions is "C" (CDECL). cannam@89: * The ZLIB1.DLL binary is linked to MSVCRT.DLL. cannam@89: cannam@89: The archive in which ZLIB1.DLL is bundled contains compiled cannam@89: test programs that must run with a valid build of ZLIB1.DLL. cannam@89: It is recommended to download the prebuilt DLL from the zlib cannam@89: web site, instead of building it yourself, to avoid potential cannam@89: incompatibilities that could be introduced by your compiler cannam@89: and build settings. If you do build the DLL yourself, please cannam@89: make sure that it complies with all the above requirements, cannam@89: and it runs with the precompiled test programs, bundled with cannam@89: the original ZLIB1.DLL distribution. cannam@89: cannam@89: If, for any reason, you need to build an incompatible DLL, cannam@89: please use a different file name. cannam@89: cannam@89: cannam@89: 2. Why did you change the name of the DLL to ZLIB1.DLL? cannam@89: What happened to the old ZLIB.DLL? cannam@89: cannam@89: - The old ZLIB.DLL, built from zlib-1.1.4 or earlier, required cannam@89: compilation settings that were incompatible to those used by cannam@89: a static build. The DLL settings were supposed to be enabled cannam@89: by defining the macro ZLIB_DLL, before including "zlib.h". cannam@89: Incorrect handling of this macro was silently accepted at cannam@89: build time, resulting in two major problems: cannam@89: cannam@89: * ZLIB_DLL was missing from the old makefile. When building cannam@89: the DLL, not all people added it to the build options. In cannam@89: consequence, incompatible incarnations of ZLIB.DLL started cannam@89: to circulate around the net. cannam@89: cannam@89: * When switching from using the static library to using the cannam@89: DLL, applications had to define the ZLIB_DLL macro and cannam@89: to recompile all the sources that contained calls to zlib cannam@89: functions. Failure to do so resulted in creating binaries cannam@89: that were unable to run with the official ZLIB.DLL build. cannam@89: cannam@89: The only possible solution that we could foresee was to make cannam@89: a binary-incompatible change in the DLL interface, in order to cannam@89: remove the dependency on the ZLIB_DLL macro, and to release cannam@89: the new DLL under a different name. cannam@89: cannam@89: We chose the name ZLIB1.DLL, where '1' indicates the major cannam@89: zlib version number. We hope that we will not have to break cannam@89: the binary compatibility again, at least not as long as the cannam@89: zlib-1.x series will last. cannam@89: cannam@89: There is still a ZLIB_DLL macro, that can trigger a more cannam@89: efficient build and use of the DLL, but compatibility no cannam@89: longer dependents on it. cannam@89: cannam@89: cannam@89: 3. Can I build ZLIB.DLL from the new zlib sources, and replace cannam@89: an old ZLIB.DLL, that was built from zlib-1.1.4 or earlier? cannam@89: cannam@89: - In principle, you can do it by assigning calling convention cannam@89: keywords to the macros ZEXPORT and ZEXPORTVA. In practice, cannam@89: it depends on what you mean by "an old ZLIB.DLL", because the cannam@89: old DLL exists in several mutually-incompatible versions. cannam@89: You have to find out first what kind of calling convention is cannam@89: being used in your particular ZLIB.DLL build, and to use the cannam@89: same one in the new build. If you don't know what this is all cannam@89: about, you might be better off if you would just leave the old cannam@89: DLL intact. cannam@89: cannam@89: cannam@89: 4. Can I compile my application using the new zlib interface, and cannam@89: link it to an old ZLIB.DLL, that was built from zlib-1.1.4 or cannam@89: earlier? cannam@89: cannam@89: - The official answer is "no"; the real answer depends again on cannam@89: what kind of ZLIB.DLL you have. Even if you are lucky, this cannam@89: course of action is unreliable. cannam@89: cannam@89: If you rebuild your application and you intend to use a newer cannam@89: version of zlib (post- 1.1.4), it is strongly recommended to cannam@89: link it to the new ZLIB1.DLL. cannam@89: cannam@89: cannam@89: 5. Why are the zlib symbols exported by name, and not by ordinal? cannam@89: cannam@89: - Although exporting symbols by ordinal is a little faster, it cannam@89: is risky. Any single glitch in the maintenance or use of the cannam@89: DEF file that contains the ordinals can result in incompatible cannam@89: builds and frustrating crashes. Simply put, the benefits of cannam@89: exporting symbols by ordinal do not justify the risks. cannam@89: cannam@89: Technically, it should be possible to maintain ordinals in cannam@89: the DEF file, and still export the symbols by name. Ordinals cannam@89: exist in every DLL, and even if the dynamic linking performed cannam@89: at the DLL startup is searching for names, ordinals serve as cannam@89: hints, for a faster name lookup. However, if the DEF file cannam@89: contains ordinals, the Microsoft linker automatically builds cannam@89: an implib that will cause the executables linked to it to use cannam@89: those ordinals, and not the names. It is interesting to cannam@89: notice that the GNU linker for Win32 does not suffer from this cannam@89: problem. cannam@89: cannam@89: It is possible to avoid the DEF file if the exported symbols cannam@89: are accompanied by a "__declspec(dllexport)" attribute in the cannam@89: source files. You can do this in zlib by predefining the cannam@89: ZLIB_DLL macro. cannam@89: cannam@89: cannam@89: 6. I see that the ZLIB1.DLL functions use the "C" (CDECL) calling cannam@89: convention. Why not use the STDCALL convention? cannam@89: STDCALL is the standard convention in Win32, and I need it in cannam@89: my Visual Basic project! cannam@89: cannam@89: (For readability, we use CDECL to refer to the convention cannam@89: triggered by the "__cdecl" keyword, STDCALL to refer to cannam@89: the convention triggered by "__stdcall", and FASTCALL to cannam@89: refer to the convention triggered by "__fastcall".) cannam@89: cannam@89: - Most of the native Windows API functions (without varargs) use cannam@89: indeed the WINAPI convention (which translates to STDCALL in cannam@89: Win32), but the standard C functions use CDECL. If a user cannam@89: application is intrinsically tied to the Windows API (e.g. cannam@89: it calls native Windows API functions such as CreateFile()), cannam@89: sometimes it makes sense to decorate its own functions with cannam@89: WINAPI. But if ANSI C or POSIX portability is a goal (e.g. cannam@89: it calls standard C functions such as fopen()), it is not a cannam@89: sound decision to request the inclusion of , or to cannam@89: use non-ANSI constructs, for the sole purpose to make the user cannam@89: functions STDCALL-able. cannam@89: cannam@89: The functionality offered by zlib is not in the category of cannam@89: "Windows functionality", but is more like "C functionality". cannam@89: cannam@89: Technically, STDCALL is not bad; in fact, it is slightly cannam@89: faster than CDECL, and it works with variable-argument cannam@89: functions, just like CDECL. It is unfortunate that, in spite cannam@89: of using STDCALL in the Windows API, it is not the default cannam@89: convention used by the C compilers that run under Windows. cannam@89: The roots of the problem reside deep inside the unsafety of cannam@89: the K&R-style function prototypes, where the argument types cannam@89: are not specified; but that is another story for another day. cannam@89: cannam@89: The remaining fact is that CDECL is the default convention. cannam@89: Even if an explicit convention is hard-coded into the function cannam@89: prototypes inside C headers, problems may appear. The cannam@89: necessity to expose the convention in users' callbacks is one cannam@89: of these problems. cannam@89: cannam@89: The calling convention issues are also important when using cannam@89: zlib in other programming languages. Some of them, like Ada cannam@89: (GNAT) and Fortran (GNU G77), have C bindings implemented cannam@89: initially on Unix, and relying on the C calling convention. cannam@89: On the other hand, the pre- .NET versions of Microsoft Visual cannam@89: Basic require STDCALL, while Borland Delphi prefers, although cannam@89: it does not require, FASTCALL. cannam@89: cannam@89: In fairness to all possible uses of zlib outside the C cannam@89: programming language, we choose the default "C" convention. cannam@89: Anyone interested in different bindings or conventions is cannam@89: encouraged to maintain specialized projects. The "contrib/" cannam@89: directory from the zlib distribution already holds a couple cannam@89: of foreign bindings, such as Ada, C++, and Delphi. cannam@89: cannam@89: cannam@89: 7. I need a DLL for my Visual Basic project. What can I do? cannam@89: cannam@89: - Define the ZLIB_WINAPI macro before including "zlib.h", when cannam@89: building both the DLL and the user application (except that cannam@89: you don't need to define anything when using the DLL in Visual cannam@89: Basic). The ZLIB_WINAPI macro will switch on the WINAPI cannam@89: (STDCALL) convention. The name of this DLL must be different cannam@89: than the official ZLIB1.DLL. cannam@89: cannam@89: Gilles Vollant has contributed a build named ZLIBWAPI.DLL, cannam@89: with the ZLIB_WINAPI macro turned on, and with the minizip cannam@89: functionality built in. For more information, please read cannam@89: the notes inside "contrib/vstudio/readme.txt", found in the cannam@89: zlib distribution. cannam@89: cannam@89: cannam@89: 8. I need to use zlib in my Microsoft .NET project. What can I cannam@89: do? cannam@89: cannam@89: - Henrik Ravn has contributed a .NET wrapper around zlib. Look cannam@89: into contrib/dotzlib/, inside the zlib distribution. cannam@89: cannam@89: cannam@89: 9. If my application uses ZLIB1.DLL, should I link it to cannam@89: MSVCRT.DLL? Why? cannam@89: cannam@89: - It is not required, but it is recommended to link your cannam@89: application to MSVCRT.DLL, if it uses ZLIB1.DLL. cannam@89: cannam@89: The executables (.EXE, .DLL, etc.) that are involved in the cannam@89: same process and are using the C run-time library (i.e. they cannam@89: are calling standard C functions), must link to the same cannam@89: library. There are several libraries in the Win32 system: cannam@89: CRTDLL.DLL, MSVCRT.DLL, the static C libraries, etc. cannam@89: Since ZLIB1.DLL is linked to MSVCRT.DLL, the executables that cannam@89: depend on it should also be linked to MSVCRT.DLL. cannam@89: cannam@89: cannam@89: 10. Why are you saying that ZLIB1.DLL and my application should cannam@89: be linked to the same C run-time (CRT) library? I linked my cannam@89: application and my DLLs to different C libraries (e.g. my cannam@89: application to a static library, and my DLLs to MSVCRT.DLL), cannam@89: and everything works fine. cannam@89: cannam@89: - If a user library invokes only pure Win32 API (accessible via cannam@89: and the related headers), its DLL build will work cannam@89: in any context. But if this library invokes standard C API, cannam@89: things get more complicated. cannam@89: cannam@89: There is a single Win32 library in a Win32 system. Every cannam@89: function in this library resides in a single DLL module, that cannam@89: is safe to call from anywhere. On the other hand, there are cannam@89: multiple versions of the C library, and each of them has its cannam@89: own separate internal state. Standalone executables and user cannam@89: DLLs that call standard C functions must link to a C run-time cannam@89: (CRT) library, be it static or shared (DLL). Intermixing cannam@89: occurs when an executable (not necessarily standalone) and a cannam@89: DLL are linked to different CRTs, and both are running in the cannam@89: same process. cannam@89: cannam@89: Intermixing multiple CRTs is possible, as long as their cannam@89: internal states are kept intact. The Microsoft Knowledge Base cannam@89: articles KB94248 "HOWTO: Use the C Run-Time" and KB140584 cannam@89: "HOWTO: Link with the Correct C Run-Time (CRT) Library" cannam@89: mention the potential problems raised by intermixing. cannam@89: cannam@89: If intermixing works for you, it's because your application cannam@89: and DLLs are avoiding the corruption of each of the CRTs' cannam@89: internal states, maybe by careful design, or maybe by fortune. cannam@89: cannam@89: Also note that linking ZLIB1.DLL to non-Microsoft CRTs, such cannam@89: as those provided by Borland, raises similar problems. cannam@89: cannam@89: cannam@89: 11. Why are you linking ZLIB1.DLL to MSVCRT.DLL? cannam@89: cannam@89: - MSVCRT.DLL exists on every Windows 95 with a new service pack cannam@89: installed, or with Microsoft Internet Explorer 4 or later, and cannam@89: on all other Windows 4.x or later (Windows 98, Windows NT 4, cannam@89: or later). It is freely distributable; if not present in the cannam@89: system, it can be downloaded from Microsoft or from other cannam@89: software provider for free. cannam@89: cannam@89: The fact that MSVCRT.DLL does not exist on a virgin Windows 95 cannam@89: is not so problematic. Windows 95 is scarcely found nowadays, cannam@89: Microsoft ended its support a long time ago, and many recent cannam@89: applications from various vendors, including Microsoft, do not cannam@89: even run on it. Furthermore, no serious user should run cannam@89: Windows 95 without a proper update installed. cannam@89: cannam@89: cannam@89: 12. Why are you not linking ZLIB1.DLL to cannam@89: <> ? cannam@89: cannam@89: - We considered and abandoned the following alternatives: cannam@89: cannam@89: * Linking ZLIB1.DLL to a static C library (LIBC.LIB, or cannam@89: LIBCMT.LIB) is not a good option. People are using the DLL cannam@89: mainly to save disk space. If you are linking your program cannam@89: to a static C library, you may as well consider linking zlib cannam@89: in statically, too. cannam@89: cannam@89: * Linking ZLIB1.DLL to CRTDLL.DLL looks appealing, because cannam@89: CRTDLL.DLL is present on every Win32 installation. cannam@89: Unfortunately, it has a series of problems: it does not cannam@89: work properly with Microsoft's C++ libraries, it does not cannam@89: provide support for 64-bit file offsets, (and so on...), cannam@89: and Microsoft discontinued its support a long time ago. cannam@89: cannam@89: * Linking ZLIB1.DLL to MSVCR70.DLL or MSVCR71.DLL, supplied cannam@89: with the Microsoft .NET platform, and Visual C++ 7.0/7.1, cannam@89: raises problems related to the status of ZLIB1.DLL as a cannam@89: system component. According to the Microsoft Knowledge Base cannam@89: article KB326922 "INFO: Redistribution of the Shared C cannam@89: Runtime Component in Visual C++ .NET", MSVCR70.DLL and cannam@89: MSVCR71.DLL are not supposed to function as system DLLs, cannam@89: because they may clash with MSVCRT.DLL. Instead, the cannam@89: application's installer is supposed to put these DLLs cannam@89: (if needed) in the application's private directory. cannam@89: If ZLIB1.DLL depends on a non-system runtime, it cannot cannam@89: function as a redistributable system component. cannam@89: cannam@89: * Linking ZLIB1.DLL to non-Microsoft runtimes, such as cannam@89: Borland's, or Cygwin's, raises problems related to the cannam@89: reliable presence of these runtimes on Win32 systems. cannam@89: It's easier to let the DLL build of zlib up to the people cannam@89: who distribute these runtimes, and who may proceed as cannam@89: explained in the answer to Question 14. cannam@89: cannam@89: cannam@89: 13. If ZLIB1.DLL cannot be linked to MSVCR70.DLL or MSVCR71.DLL, cannam@89: how can I build/use ZLIB1.DLL in Microsoft Visual C++ 7.0 cannam@89: (Visual Studio .NET) or newer? cannam@89: cannam@89: - Due to the problems explained in the Microsoft Knowledge Base cannam@89: article KB326922 (see the previous answer), the C runtime that cannam@89: comes with the VC7 environment is no longer considered a cannam@89: system component. That is, it should not be assumed that this cannam@89: runtime exists, or may be installed in a system directory. cannam@89: Since ZLIB1.DLL is supposed to be a system component, it may cannam@89: not depend on a non-system component. cannam@89: cannam@89: In order to link ZLIB1.DLL and your application to MSVCRT.DLL cannam@89: in VC7, you need the library of Visual C++ 6.0 or older. If cannam@89: you don't have this library at hand, it's probably best not to cannam@89: use ZLIB1.DLL. cannam@89: cannam@89: We are hoping that, in the future, Microsoft will provide a cannam@89: way to build applications linked to a proper system runtime, cannam@89: from the Visual C++ environment. Until then, you have a cannam@89: couple of alternatives, such as linking zlib in statically. cannam@89: If your application requires dynamic linking, you may proceed cannam@89: as explained in the answer to Question 14. cannam@89: cannam@89: cannam@89: 14. I need to link my own DLL build to a CRT different than cannam@89: MSVCRT.DLL. What can I do? cannam@89: cannam@89: - Feel free to rebuild the DLL from the zlib sources, and link cannam@89: it the way you want. You should, however, clearly state that cannam@89: your build is unofficial. You should give it a different file cannam@89: name, and/or install it in a private directory that can be cannam@89: accessed by your application only, and is not visible to the cannam@89: others (i.e. it's neither in the PATH, nor in the SYSTEM or cannam@89: SYSTEM32 directories). Otherwise, your build may clash with cannam@89: applications that link to the official build. cannam@89: cannam@89: For example, in Cygwin, zlib is linked to the Cygwin runtime cannam@89: CYGWIN1.DLL, and it is distributed under the name CYGZ.DLL. cannam@89: cannam@89: cannam@89: 15. May I include additional pieces of code that I find useful, cannam@89: link them in ZLIB1.DLL, and export them? cannam@89: cannam@89: - No. A legitimate build of ZLIB1.DLL must not include code cannam@89: that does not originate from the official zlib source code. cannam@89: But you can make your own private DLL build, under a different cannam@89: file name, as suggested in the previous answer. cannam@89: cannam@89: For example, zlib is a part of the VCL library, distributed cannam@89: with Borland Delphi and C++ Builder. The DLL build of VCL cannam@89: is a redistributable file, named VCLxx.DLL. cannam@89: cannam@89: cannam@89: 16. May I remove some functionality out of ZLIB1.DLL, by enabling cannam@89: macros like NO_GZCOMPRESS or NO_GZIP at compile time? cannam@89: cannam@89: - No. A legitimate build of ZLIB1.DLL must provide the complete cannam@89: zlib functionality, as implemented in the official zlib source cannam@89: code. But you can make your own private DLL build, under a cannam@89: different file name, as suggested in the previous answer. cannam@89: cannam@89: cannam@89: 17. I made my own ZLIB1.DLL build. Can I test it for compliance? cannam@89: cannam@89: - We prefer that you download the official DLL from the zlib cannam@89: web site. If you need something peculiar from this DLL, you cannam@89: can send your suggestion to the zlib mailing list. cannam@89: cannam@89: However, in case you do rebuild the DLL yourself, you can run cannam@89: it with the test programs found in the DLL distribution. cannam@89: Running these test programs is not a guarantee of compliance, cannam@89: but a failure can imply a detected problem. cannam@89: cannam@89: ** cannam@89: cannam@89: This document is written and maintained by cannam@89: Cosmin Truta