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