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