1*440a403fSchristos 2*440a403fSchristos Frequently Asked Questions about ZLIB1.DLL 3*440a403fSchristos 4*440a403fSchristos 5*440a403fSchristosThis document describes the design, the rationale, and the usage 6*440a403fSchristosof the official DLL build of zlib, named ZLIB1.DLL. If you have 7*440a403fSchristosgeneral questions about zlib, you should see the file "FAQ" found 8*440a403fSchristosin the zlib distribution, or at the following location: 9*440a403fSchristos http://www.gzip.org/zlib/zlib_faq.html 10*440a403fSchristos 11*440a403fSchristos 12*440a403fSchristos 1. What is ZLIB1.DLL, and how can I get it? 13*440a403fSchristos 14*440a403fSchristos - ZLIB1.DLL is the official build of zlib as a DLL. 15*440a403fSchristos (Please remark the character '1' in the name.) 16*440a403fSchristos 17*440a403fSchristos Pointers to a precompiled ZLIB1.DLL can be found in the zlib 18*440a403fSchristos web site at: 19*440a403fSchristos http://www.zlib.net/ 20*440a403fSchristos 21*440a403fSchristos Applications that link to ZLIB1.DLL can rely on the following 22*440a403fSchristos specification: 23*440a403fSchristos 24*440a403fSchristos * The exported symbols are exclusively defined in the source 25*440a403fSchristos files "zlib.h" and "zlib.def", found in an official zlib 26*440a403fSchristos source distribution. 27*440a403fSchristos * The symbols are exported by name, not by ordinal. 28*440a403fSchristos * The exported names are undecorated. 29*440a403fSchristos * The calling convention of functions is "C" (CDECL). 30*440a403fSchristos * The ZLIB1.DLL binary is linked to MSVCRT.DLL. 31*440a403fSchristos 32*440a403fSchristos The archive in which ZLIB1.DLL is bundled contains compiled 33*440a403fSchristos test programs that must run with a valid build of ZLIB1.DLL. 34*440a403fSchristos It is recommended to download the prebuilt DLL from the zlib 35*440a403fSchristos web site, instead of building it yourself, to avoid potential 36*440a403fSchristos incompatibilities that could be introduced by your compiler 37*440a403fSchristos and build settings. If you do build the DLL yourself, please 38*440a403fSchristos make sure that it complies with all the above requirements, 39*440a403fSchristos and it runs with the precompiled test programs, bundled with 40*440a403fSchristos the original ZLIB1.DLL distribution. 41*440a403fSchristos 42*440a403fSchristos If, for any reason, you need to build an incompatible DLL, 43*440a403fSchristos please use a different file name. 44*440a403fSchristos 45*440a403fSchristos 46*440a403fSchristos 2. Why did you change the name of the DLL to ZLIB1.DLL? 47*440a403fSchristos What happened to the old ZLIB.DLL? 48*440a403fSchristos 49*440a403fSchristos - The old ZLIB.DLL, built from zlib-1.1.4 or earlier, required 50*440a403fSchristos compilation settings that were incompatible to those used by 51*440a403fSchristos a static build. The DLL settings were supposed to be enabled 52*440a403fSchristos by defining the macro ZLIB_DLL, before including "zlib.h". 53*440a403fSchristos Incorrect handling of this macro was silently accepted at 54*440a403fSchristos build time, resulting in two major problems: 55*440a403fSchristos 56*440a403fSchristos * ZLIB_DLL was missing from the old makefile. When building 57*440a403fSchristos the DLL, not all people added it to the build options. In 58*440a403fSchristos consequence, incompatible incarnations of ZLIB.DLL started 59*440a403fSchristos to circulate around the net. 60*440a403fSchristos 61*440a403fSchristos * When switching from using the static library to using the 62*440a403fSchristos DLL, applications had to define the ZLIB_DLL macro and 63*440a403fSchristos to recompile all the sources that contained calls to zlib 64*440a403fSchristos functions. Failure to do so resulted in creating binaries 65*440a403fSchristos that were unable to run with the official ZLIB.DLL build. 66*440a403fSchristos 67*440a403fSchristos The only possible solution that we could foresee was to make 68*440a403fSchristos a binary-incompatible change in the DLL interface, in order to 69*440a403fSchristos remove the dependency on the ZLIB_DLL macro, and to release 70*440a403fSchristos the new DLL under a different name. 71*440a403fSchristos 72*440a403fSchristos We chose the name ZLIB1.DLL, where '1' indicates the major 73*440a403fSchristos zlib version number. We hope that we will not have to break 74*440a403fSchristos the binary compatibility again, at least not as long as the 75*440a403fSchristos zlib-1.x series will last. 76*440a403fSchristos 77*440a403fSchristos There is still a ZLIB_DLL macro, that can trigger a more 78*440a403fSchristos efficient build and use of the DLL, but compatibility no 79*440a403fSchristos longer dependents on it. 80*440a403fSchristos 81*440a403fSchristos 82*440a403fSchristos 3. Can I build ZLIB.DLL from the new zlib sources, and replace 83*440a403fSchristos an old ZLIB.DLL, that was built from zlib-1.1.4 or earlier? 84*440a403fSchristos 85*440a403fSchristos - In principle, you can do it by assigning calling convention 86*440a403fSchristos keywords to the macros ZEXPORT and ZEXPORTVA. In practice, 87*440a403fSchristos it depends on what you mean by "an old ZLIB.DLL", because the 88*440a403fSchristos old DLL exists in several mutually-incompatible versions. 89*440a403fSchristos You have to find out first what kind of calling convention is 90*440a403fSchristos being used in your particular ZLIB.DLL build, and to use the 91*440a403fSchristos same one in the new build. If you don't know what this is all 92*440a403fSchristos about, you might be better off if you would just leave the old 93*440a403fSchristos DLL intact. 94*440a403fSchristos 95*440a403fSchristos 96*440a403fSchristos 4. Can I compile my application using the new zlib interface, and 97*440a403fSchristos link it to an old ZLIB.DLL, that was built from zlib-1.1.4 or 98*440a403fSchristos earlier? 99*440a403fSchristos 100*440a403fSchristos - The official answer is "no"; the real answer depends again on 101*440a403fSchristos what kind of ZLIB.DLL you have. Even if you are lucky, this 102*440a403fSchristos course of action is unreliable. 103*440a403fSchristos 104*440a403fSchristos If you rebuild your application and you intend to use a newer 105*440a403fSchristos version of zlib (post- 1.1.4), it is strongly recommended to 106*440a403fSchristos link it to the new ZLIB1.DLL. 107*440a403fSchristos 108*440a403fSchristos 109*440a403fSchristos 5. Why are the zlib symbols exported by name, and not by ordinal? 110*440a403fSchristos 111*440a403fSchristos - Although exporting symbols by ordinal is a little faster, it 112*440a403fSchristos is risky. Any single glitch in the maintenance or use of the 113*440a403fSchristos DEF file that contains the ordinals can result in incompatible 114*440a403fSchristos builds and frustrating crashes. Simply put, the benefits of 115*440a403fSchristos exporting symbols by ordinal do not justify the risks. 116*440a403fSchristos 117*440a403fSchristos Technically, it should be possible to maintain ordinals in 118*440a403fSchristos the DEF file, and still export the symbols by name. Ordinals 119*440a403fSchristos exist in every DLL, and even if the dynamic linking performed 120*440a403fSchristos at the DLL startup is searching for names, ordinals serve as 121*440a403fSchristos hints, for a faster name lookup. However, if the DEF file 122*440a403fSchristos contains ordinals, the Microsoft linker automatically builds 123*440a403fSchristos an implib that will cause the executables linked to it to use 124*440a403fSchristos those ordinals, and not the names. It is interesting to 125*440a403fSchristos notice that the GNU linker for Win32 does not suffer from this 126*440a403fSchristos problem. 127*440a403fSchristos 128*440a403fSchristos It is possible to avoid the DEF file if the exported symbols 129*440a403fSchristos are accompanied by a "__declspec(dllexport)" attribute in the 130*440a403fSchristos source files. You can do this in zlib by predefining the 131*440a403fSchristos ZLIB_DLL macro. 132*440a403fSchristos 133*440a403fSchristos 134*440a403fSchristos 6. I see that the ZLIB1.DLL functions use the "C" (CDECL) calling 135*440a403fSchristos convention. Why not use the STDCALL convention? 136*440a403fSchristos STDCALL is the standard convention in Win32, and I need it in 137*440a403fSchristos my Visual Basic project! 138*440a403fSchristos 139*440a403fSchristos (For readability, we use CDECL to refer to the convention 140*440a403fSchristos triggered by the "__cdecl" keyword, STDCALL to refer to 141*440a403fSchristos the convention triggered by "__stdcall", and FASTCALL to 142*440a403fSchristos refer to the convention triggered by "__fastcall".) 143*440a403fSchristos 144*440a403fSchristos - Most of the native Windows API functions (without varargs) use 145*440a403fSchristos indeed the WINAPI convention (which translates to STDCALL in 146*440a403fSchristos Win32), but the standard C functions use CDECL. If a user 147*440a403fSchristos application is intrinsically tied to the Windows API (e.g. 148*440a403fSchristos it calls native Windows API functions such as CreateFile()), 149*440a403fSchristos sometimes it makes sense to decorate its own functions with 150*440a403fSchristos WINAPI. But if ANSI C or POSIX portability is a goal (e.g. 151*440a403fSchristos it calls standard C functions such as fopen()), it is not a 152*440a403fSchristos sound decision to request the inclusion of <windows.h>, or to 153*440a403fSchristos use non-ANSI constructs, for the sole purpose to make the user 154*440a403fSchristos functions STDCALL-able. 155*440a403fSchristos 156*440a403fSchristos The functionality offered by zlib is not in the category of 157*440a403fSchristos "Windows functionality", but is more like "C functionality". 158*440a403fSchristos 159*440a403fSchristos Technically, STDCALL is not bad; in fact, it is slightly 160*440a403fSchristos faster than CDECL, and it works with variable-argument 161*440a403fSchristos functions, just like CDECL. It is unfortunate that, in spite 162*440a403fSchristos of using STDCALL in the Windows API, it is not the default 163*440a403fSchristos convention used by the C compilers that run under Windows. 164*440a403fSchristos The roots of the problem reside deep inside the unsafety of 165*440a403fSchristos the K&R-style function prototypes, where the argument types 166*440a403fSchristos are not specified; but that is another story for another day. 167*440a403fSchristos 168*440a403fSchristos The remaining fact is that CDECL is the default convention. 169*440a403fSchristos Even if an explicit convention is hard-coded into the function 170*440a403fSchristos prototypes inside C headers, problems may appear. The 171*440a403fSchristos necessity to expose the convention in users' callbacks is one 172*440a403fSchristos of these problems. 173*440a403fSchristos 174*440a403fSchristos The calling convention issues are also important when using 175*440a403fSchristos zlib in other programming languages. Some of them, like Ada 176*440a403fSchristos (GNAT) and Fortran (GNU G77), have C bindings implemented 177*440a403fSchristos initially on Unix, and relying on the C calling convention. 178*440a403fSchristos On the other hand, the pre- .NET versions of Microsoft Visual 179*440a403fSchristos Basic require STDCALL, while Borland Delphi prefers, although 180*440a403fSchristos it does not require, FASTCALL. 181*440a403fSchristos 182*440a403fSchristos In fairness to all possible uses of zlib outside the C 183*440a403fSchristos programming language, we choose the default "C" convention. 184*440a403fSchristos Anyone interested in different bindings or conventions is 185*440a403fSchristos encouraged to maintain specialized projects. The "contrib/" 186*440a403fSchristos directory from the zlib distribution already holds a couple 187*440a403fSchristos of foreign bindings, such as Ada, C++, and Delphi. 188*440a403fSchristos 189*440a403fSchristos 190*440a403fSchristos 7. I need a DLL for my Visual Basic project. What can I do? 191*440a403fSchristos 192*440a403fSchristos - Define the ZLIB_WINAPI macro before including "zlib.h", when 193*440a403fSchristos building both the DLL and the user application (except that 194*440a403fSchristos you don't need to define anything when using the DLL in Visual 195*440a403fSchristos Basic). The ZLIB_WINAPI macro will switch on the WINAPI 196*440a403fSchristos (STDCALL) convention. The name of this DLL must be different 197*440a403fSchristos than the official ZLIB1.DLL. 198*440a403fSchristos 199*440a403fSchristos Gilles Vollant has contributed a build named ZLIBWAPI.DLL, 200*440a403fSchristos with the ZLIB_WINAPI macro turned on, and with the minizip 201*440a403fSchristos functionality built in. For more information, please read 202*440a403fSchristos the notes inside "contrib/vstudio/readme.txt", found in the 203*440a403fSchristos zlib distribution. 204*440a403fSchristos 205*440a403fSchristos 206*440a403fSchristos 8. I need to use zlib in my Microsoft .NET project. What can I 207*440a403fSchristos do? 208*440a403fSchristos 209*440a403fSchristos - Henrik Ravn has contributed a .NET wrapper around zlib. Look 210*440a403fSchristos into contrib/dotzlib/, inside the zlib distribution. 211*440a403fSchristos 212*440a403fSchristos 213*440a403fSchristos 9. If my application uses ZLIB1.DLL, should I link it to 214*440a403fSchristos MSVCRT.DLL? Why? 215*440a403fSchristos 216*440a403fSchristos - It is not required, but it is recommended to link your 217*440a403fSchristos application to MSVCRT.DLL, if it uses ZLIB1.DLL. 218*440a403fSchristos 219*440a403fSchristos The executables (.EXE, .DLL, etc.) that are involved in the 220*440a403fSchristos same process and are using the C run-time library (i.e. they 221*440a403fSchristos are calling standard C functions), must link to the same 222*440a403fSchristos library. There are several libraries in the Win32 system: 223*440a403fSchristos CRTDLL.DLL, MSVCRT.DLL, the static C libraries, etc. 224*440a403fSchristos Since ZLIB1.DLL is linked to MSVCRT.DLL, the executables that 225*440a403fSchristos depend on it should also be linked to MSVCRT.DLL. 226*440a403fSchristos 227*440a403fSchristos 228*440a403fSchristos10. Why are you saying that ZLIB1.DLL and my application should 229*440a403fSchristos be linked to the same C run-time (CRT) library? I linked my 230*440a403fSchristos application and my DLLs to different C libraries (e.g. my 231*440a403fSchristos application to a static library, and my DLLs to MSVCRT.DLL), 232*440a403fSchristos and everything works fine. 233*440a403fSchristos 234*440a403fSchristos - If a user library invokes only pure Win32 API (accessible via 235*440a403fSchristos <windows.h> and the related headers), its DLL build will work 236*440a403fSchristos in any context. But if this library invokes standard C API, 237*440a403fSchristos things get more complicated. 238*440a403fSchristos 239*440a403fSchristos There is a single Win32 library in a Win32 system. Every 240*440a403fSchristos function in this library resides in a single DLL module, that 241*440a403fSchristos is safe to call from anywhere. On the other hand, there are 242*440a403fSchristos multiple versions of the C library, and each of them has its 243*440a403fSchristos own separate internal state. Standalone executables and user 244*440a403fSchristos DLLs that call standard C functions must link to a C run-time 245*440a403fSchristos (CRT) library, be it static or shared (DLL). Intermixing 246*440a403fSchristos occurs when an executable (not necessarily standalone) and a 247*440a403fSchristos DLL are linked to different CRTs, and both are running in the 248*440a403fSchristos same process. 249*440a403fSchristos 250*440a403fSchristos Intermixing multiple CRTs is possible, as long as their 251*440a403fSchristos internal states are kept intact. The Microsoft Knowledge Base 252*440a403fSchristos articles KB94248 "HOWTO: Use the C Run-Time" and KB140584 253*440a403fSchristos "HOWTO: Link with the Correct C Run-Time (CRT) Library" 254*440a403fSchristos mention the potential problems raised by intermixing. 255*440a403fSchristos 256*440a403fSchristos If intermixing works for you, it's because your application 257*440a403fSchristos and DLLs are avoiding the corruption of each of the CRTs' 258*440a403fSchristos internal states, maybe by careful design, or maybe by fortune. 259*440a403fSchristos 260*440a403fSchristos Also note that linking ZLIB1.DLL to non-Microsoft CRTs, such 261*440a403fSchristos as those provided by Borland, raises similar problems. 262*440a403fSchristos 263*440a403fSchristos 264*440a403fSchristos11. Why are you linking ZLIB1.DLL to MSVCRT.DLL? 265*440a403fSchristos 266*440a403fSchristos - MSVCRT.DLL exists on every Windows 95 with a new service pack 267*440a403fSchristos installed, or with Microsoft Internet Explorer 4 or later, and 268*440a403fSchristos on all other Windows 4.x or later (Windows 98, Windows NT 4, 269*440a403fSchristos or later). It is freely distributable; if not present in the 270*440a403fSchristos system, it can be downloaded from Microsoft or from other 271*440a403fSchristos software provider for free. 272*440a403fSchristos 273*440a403fSchristos The fact that MSVCRT.DLL does not exist on a virgin Windows 95 274*440a403fSchristos is not so problematic. Windows 95 is scarcely found nowadays, 275*440a403fSchristos Microsoft ended its support a long time ago, and many recent 276*440a403fSchristos applications from various vendors, including Microsoft, do not 277*440a403fSchristos even run on it. Furthermore, no serious user should run 278*440a403fSchristos Windows 95 without a proper update installed. 279*440a403fSchristos 280*440a403fSchristos 281*440a403fSchristos12. Why are you not linking ZLIB1.DLL to 282*440a403fSchristos <<my favorite C run-time library>> ? 283*440a403fSchristos 284*440a403fSchristos - We considered and abandoned the following alternatives: 285*440a403fSchristos 286*440a403fSchristos * Linking ZLIB1.DLL to a static C library (LIBC.LIB, or 287*440a403fSchristos LIBCMT.LIB) is not a good option. People are using the DLL 288*440a403fSchristos mainly to save disk space. If you are linking your program 289*440a403fSchristos to a static C library, you may as well consider linking zlib 290*440a403fSchristos in statically, too. 291*440a403fSchristos 292*440a403fSchristos * Linking ZLIB1.DLL to CRTDLL.DLL looks appealing, because 293*440a403fSchristos CRTDLL.DLL is present on every Win32 installation. 294*440a403fSchristos Unfortunately, it has a series of problems: it does not 295*440a403fSchristos work properly with Microsoft's C++ libraries, it does not 296*440a403fSchristos provide support for 64-bit file offsets, (and so on...), 297*440a403fSchristos and Microsoft discontinued its support a long time ago. 298*440a403fSchristos 299*440a403fSchristos * Linking ZLIB1.DLL to MSVCR70.DLL or MSVCR71.DLL, supplied 300*440a403fSchristos with the Microsoft .NET platform, and Visual C++ 7.0/7.1, 301*440a403fSchristos raises problems related to the status of ZLIB1.DLL as a 302*440a403fSchristos system component. According to the Microsoft Knowledge Base 303*440a403fSchristos article KB326922 "INFO: Redistribution of the Shared C 304*440a403fSchristos Runtime Component in Visual C++ .NET", MSVCR70.DLL and 305*440a403fSchristos MSVCR71.DLL are not supposed to function as system DLLs, 306*440a403fSchristos because they may clash with MSVCRT.DLL. Instead, the 307*440a403fSchristos application's installer is supposed to put these DLLs 308*440a403fSchristos (if needed) in the application's private directory. 309*440a403fSchristos If ZLIB1.DLL depends on a non-system runtime, it cannot 310*440a403fSchristos function as a redistributable system component. 311*440a403fSchristos 312*440a403fSchristos * Linking ZLIB1.DLL to non-Microsoft runtimes, such as 313*440a403fSchristos Borland's, or Cygwin's, raises problems related to the 314*440a403fSchristos reliable presence of these runtimes on Win32 systems. 315*440a403fSchristos It's easier to let the DLL build of zlib up to the people 316*440a403fSchristos who distribute these runtimes, and who may proceed as 317*440a403fSchristos explained in the answer to Question 14. 318*440a403fSchristos 319*440a403fSchristos 320*440a403fSchristos13. If ZLIB1.DLL cannot be linked to MSVCR70.DLL or MSVCR71.DLL, 321*440a403fSchristos how can I build/use ZLIB1.DLL in Microsoft Visual C++ 7.0 322*440a403fSchristos (Visual Studio .NET) or newer? 323*440a403fSchristos 324*440a403fSchristos - Due to the problems explained in the Microsoft Knowledge Base 325*440a403fSchristos article KB326922 (see the previous answer), the C runtime that 326*440a403fSchristos comes with the VC7 environment is no longer considered a 327*440a403fSchristos system component. That is, it should not be assumed that this 328*440a403fSchristos runtime exists, or may be installed in a system directory. 329*440a403fSchristos Since ZLIB1.DLL is supposed to be a system component, it may 330*440a403fSchristos not depend on a non-system component. 331*440a403fSchristos 332*440a403fSchristos In order to link ZLIB1.DLL and your application to MSVCRT.DLL 333*440a403fSchristos in VC7, you need the library of Visual C++ 6.0 or older. If 334*440a403fSchristos you don't have this library at hand, it's probably best not to 335*440a403fSchristos use ZLIB1.DLL. 336*440a403fSchristos 337*440a403fSchristos We are hoping that, in the future, Microsoft will provide a 338*440a403fSchristos way to build applications linked to a proper system runtime, 339*440a403fSchristos from the Visual C++ environment. Until then, you have a 340*440a403fSchristos couple of alternatives, such as linking zlib in statically. 341*440a403fSchristos If your application requires dynamic linking, you may proceed 342*440a403fSchristos as explained in the answer to Question 14. 343*440a403fSchristos 344*440a403fSchristos 345*440a403fSchristos14. I need to link my own DLL build to a CRT different than 346*440a403fSchristos MSVCRT.DLL. What can I do? 347*440a403fSchristos 348*440a403fSchristos - Feel free to rebuild the DLL from the zlib sources, and link 349*440a403fSchristos it the way you want. You should, however, clearly state that 350*440a403fSchristos your build is unofficial. You should give it a different file 351*440a403fSchristos name, and/or install it in a private directory that can be 352*440a403fSchristos accessed by your application only, and is not visible to the 353*440a403fSchristos others (i.e. it's neither in the PATH, nor in the SYSTEM or 354*440a403fSchristos SYSTEM32 directories). Otherwise, your build may clash with 355*440a403fSchristos applications that link to the official build. 356*440a403fSchristos 357*440a403fSchristos For example, in Cygwin, zlib is linked to the Cygwin runtime 358*440a403fSchristos CYGWIN1.DLL, and it is distributed under the name CYGZ.DLL. 359*440a403fSchristos 360*440a403fSchristos 361*440a403fSchristos15. May I include additional pieces of code that I find useful, 362*440a403fSchristos link them in ZLIB1.DLL, and export them? 363*440a403fSchristos 364*440a403fSchristos - No. A legitimate build of ZLIB1.DLL must not include code 365*440a403fSchristos that does not originate from the official zlib source code. 366*440a403fSchristos But you can make your own private DLL build, under a different 367*440a403fSchristos file name, as suggested in the previous answer. 368*440a403fSchristos 369*440a403fSchristos For example, zlib is a part of the VCL library, distributed 370*440a403fSchristos with Borland Delphi and C++ Builder. The DLL build of VCL 371*440a403fSchristos is a redistributable file, named VCLxx.DLL. 372*440a403fSchristos 373*440a403fSchristos 374*440a403fSchristos16. May I remove some functionality out of ZLIB1.DLL, by enabling 375*440a403fSchristos macros like NO_GZCOMPRESS or NO_GZIP at compile time? 376*440a403fSchristos 377*440a403fSchristos - No. A legitimate build of ZLIB1.DLL must provide the complete 378*440a403fSchristos zlib functionality, as implemented in the official zlib source 379*440a403fSchristos code. But you can make your own private DLL build, under a 380*440a403fSchristos different file name, as suggested in the previous answer. 381*440a403fSchristos 382*440a403fSchristos 383*440a403fSchristos17. I made my own ZLIB1.DLL build. Can I test it for compliance? 384*440a403fSchristos 385*440a403fSchristos - We prefer that you download the official DLL from the zlib 386*440a403fSchristos web site. If you need something peculiar from this DLL, you 387*440a403fSchristos can send your suggestion to the zlib mailing list. 388*440a403fSchristos 389*440a403fSchristos However, in case you do rebuild the DLL yourself, you can run 390*440a403fSchristos it with the test programs found in the DLL distribution. 391*440a403fSchristos Running these test programs is not a guarantee of compliance, 392*440a403fSchristos but a failure can imply a detected problem. 393*440a403fSchristos 394*440a403fSchristos** 395*440a403fSchristos 396*440a403fSchristosThis document is written and maintained by 397*440a403fSchristosCosmin Truta <cosmint@cs.ubbcluj.ro> 398