Igor Sarkisov | cb47b6f | 2020-10-06 04:44:21 -0700 | [diff] [blame] | 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> |