2 Frequently Asked Questions about ZLIB1.DLL
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
12 1. What is ZLIB1.DLL, and how can I get it?
14 - ZLIB1.DLL is the official build of zlib as a DLL.
15 (Please remark the symbol '1' in the name.)
17 Pointers to a precompiled ZLIB1.DLL can be found in the zlib
21 Applications that link to ZLIB1.DLL can rely on the following
24 * The exported symbols are exclusively defined in the source
25 files "zlib.h" and "zlib.def", found in an official zlib
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.
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 and available at the zlib
43 If, for any reason, you need to build an incompatible DLL,
44 please use a different name.
47 2. Why did you change the name of the DLL to ZLIB1.DLL?
48 What happened to the old ZLIB.DLL?
50 - The old ZLIB.DLL, built from zlib-1.1.x and earlier, required
51 compilation settings that were incompatible to those used by a
52 static build. The DLL settings were supposed to be enabled by
53 defining the macro ZLIB_DLL, before including "zlib.h".
54 Incorrect handling of this macro was silently accepted at
55 build time, resulting in two major problems:
57 * ZLIB_DLL was missing from the old makefile. When building
58 the DLL, not all people added it to the build options. In
59 consequence, incompatible incarnations of ZLIB.DLL started
60 to circulate around the net.
62 * When switching from using the static library to using the
63 DLL, applications had to define the ZLIB_DLL macro and
64 to recompile all the sources that contained calls to zlib
65 functions. Failure to do so resulted in creating binaries
66 that were unable to run with the official ZLIB.DLL build.
68 The only possible solution that we could foresee was to make a
69 binary-incompatible change in the DLL interfacing, in order to
70 remove the dependency on the ZLIB_DLL macro, and to release
71 the new DLL under a different name.
73 We chose the name ZLIB1.DLL, where '1' indicates the major
74 zlib version number. We hope that we will not have to break
75 the binary compatibility again, at least not as long as the
76 zlib-1.x series will last.
78 There is still a ZLIB_DLL macro, that can trigger a more
79 efficient build and use of the DLL, but compatibility no
80 longer dependents on it.
83 3. Can I build ZLIB.DLL from the new zlib sources, and replace
84 an old ZLIB.DLL, that was built from zlib-1.1.4 or earlier?
86 - In principle, you can do it by assigning calling convention
87 keywords to the macros ZEXPORT and ZEXPORTVA. In practice,
88 it depends on what you mean by "an old ZLIB.DLL", because
89 the old DLL exists in several mutually-incompatible versions.
91 If you have a compiled application that works with a certain
92 ZLIB.DLL without any known security issues, there is hardly
93 a need to rebuild the DLL from new sources only to link it to
94 the old app binary. But if you really want to do it, you have
95 to find out first what kind of calling convention uses your
96 particular ZLIB.DLL build, and to use the same one in the new
97 build. If you don't know what this is all about, you might be
98 better off if you would just forget it.
101 4. Can I compile my application using the new zlib interface, and
102 link it to an old ZLIB.DLL, that was built from zlib-1.1.4 or
105 - The official answer is "no"; the real answer depends again on
106 what kind of ZLIB.DLL you have. Even if you are lucky, this
107 course of action is unreliable.
109 If you rebuild your application and you intend to use a newer
110 version of zlib (post- 1.1.4), it is strongly recommended to
111 link it to the new ZLIB1.DLL.
114 5. Why are the zlib symbols exported by name, and not by ordinal?
116 - Although exporting symbols by ordinal is a little faster, it
117 is risky. Any single glitch in the maintenance or use of the
118 DEF file that contains the ordinals can result in incompatible
119 builds and frustrating crashes. Simply put, the benefits of
120 exporting symbols by ordinal do not justify the risks.
122 Technically, it should be possible to maintain ordinals in
123 the DEF file, and still export the symbols by name. Ordinals
124 exist in every DLL, and even if the dynamic linking performed
125 at the DLL startup is searching for names, ordinals serve as
126 hints, for a faster name lookup. However, if the DEF file
127 contains ordinals, the Microsoft linker automatically builds
128 an implib that will cause the executables linked to it to use
129 those ordinals, and not the names. It is interesting to
130 notice that the GNU linker for Win32 does not suffer from this
133 It is possible to avoid the DEF file if the exported symbols
134 are accompanied by a "__declspec(dllexport)" attribute in the
135 source files. You can do this in zlib by predefining the
139 6. I see that the ZLIB1.DLL functions use the "C" (CDECL) calling
140 convention. Why not use the STDCALL convention?
141 STDCALL is the standard convention in Win32, and I need it in
142 my Visual Basic project!
144 (For readability, we use CDECL to refer to the convention
145 triggered by the "__cdecl" keyword, STDCALL to refer to
146 the convention triggered by "__stdcall", and FASTCALL to
147 refer to the convention triggered by "__fastcall".)
149 - Most of the native Windows API functions (without varargs) use
150 indeed the WINAPI convention (which translates to STDCALL in
151 Win32), but the standard C functions use CDECL. If a user
152 application is intrinsically tied to the Windows API (e.g.
153 it calls native Windows API functions such as CreateFile()),
154 sometimes it makes sense to decorate its own functions with
155 WINAPI. But if ANSI C or POSIX portability is a goal (e.g.
156 it calls standard C functions such as fopen()), it is not a
157 sound decision to request the inclusion of <windows.h>, or to
158 use non-ANSI constructs, for the sole purpose to make the user
159 functions STDCALL-able.
161 The functionality offered by zlib is not in the category of
162 "Windows functionality", but is more like "C functionality".
164 Technically, STDCALL is not bad; in fact, it is slightly
165 faster than CDECL, and it works with variable-argument
166 functions, just like CDECL. It is unfortunate that, in spite
167 of using STDCALL in the Windows API, it is not the default
168 convention used by the C compilers that run under Windows.
169 The roots of the problem reside deep inside the unsafety of
170 the K&R-style function prototypes, where the argument types
171 are not specified; but that is another story for another day.
173 The fact that remains is that CDECL is the default convention.
174 Even if an explicit convention (such as STDCALL or FASTCALL)
175 is hard-coded into the function prototypes inside C headers,
176 problems may appear. One problem, for example, deals with the
177 necessity to expose the convention in users' callbacks.
179 The calling convention issues are also important when using
180 zlib in other programming languages. Some of them, like Ada
181 (GNAT) and Fortran (GNU G77), have C bindings implemented
182 initially on Unix, and relying on the C calling convention.
183 On the other hand, the pre- .NET versions of Microsoft Visual
184 Basic require STDCALL, while Borland Delphi prefers (although
185 it does not require) FASTCALL.
187 In fairness to all possible uses of zlib outside the C
188 programming language, we choose the default "C" convention.
189 Anyone interested in different bindings or conventions is
190 encouraged to maintain specialized projects. The "contrib/"
191 directory from the zlib distribution already holds a couple
192 of foreign bindings, such as Ada, C++, and Delphi.
195 7. I need a DLL for my Visual Basic project. What can I do?
197 - Define the ZLIB_WINAPI macro before including "zlib.h", when
198 building both the DLL and the user application (except that
199 you don't need to define anything when using the DLL in Visual
200 Basic). The ZLIB_WINAPI macro will switch on the WINAPI
201 (STDCALL) convention. The name of this DLL must be different
202 than the official ZLIB1.DLL.
204 Gilles Vollant has contributed a build named ZLIBWAPI.DLL,
205 with the ZLIB_WINAPI macro turned on, and with the minizip
206 functionality built in. For more information, please read
207 the notes inside "contrib/vstudio/readme.txt", found in the
211 8. If my application uses ZLIB1.DLL, should I link it to
214 - It is not required, but it is recommended to link your
215 application to MSVCRT.DLL, if it uses ZLIB1.DLL.
217 The executables (.EXE, .DLL, etc.) that are involved in the
218 same process and are using the C run-time library (i.e. they
219 are calling standard C functions), must link to the same
220 library. There are several libraries in the Win32 system:
221 CRTDLL.DLL, MSVCRT.DLL, the static C libraries, etc.
222 Since ZLIB1.DLL is linked to MSVCRT.DLL, the executables that
223 depend on it should also be linked to MSVCRT.DLL.
226 9. Why are you saying that ZLIB1.DLL and my application must be
227 linked to the same C run-time (CRT) library? I linked my
228 application and my DLLs to different C libraries (e.g. my
229 application to a static library, and my DLLs to MSVCRT.DLL),
230 and everything works fine.
232 - If a user library invokes only pure Win32 API (accessible via
233 <windows.h> and the related headers), its DLL build will work
234 in any context. But if this library invokes standard C API,
235 things get more complicated.
237 There is a single Win32 library in a Win32 system. Every
238 function in this library resides in a single DLL module, that
239 is safe to call from anywhere. On the other hand, there are
240 multiple versions of the C library, and each of them has its
241 own separate internal state. Standalone executables and user
242 DLLs that call standard C functions must link to a C run-time
243 (CRT) library, be it static or shared (DLL). Intermixing
244 occurs when an executable (not necessarily standalone) and a
245 DLL are linked to different CRTs, and both are running in the
248 Intermixing multiple CRTs is possible, as long as their
249 internal states are kept intact. The Microsoft Knowledge Base
250 articles KB94248 "HOWTO: Use the C Run-Time" and KB140584
251 "HOWTO: Link with the Correct C Run-Time (CRT) Library"
252 mention the potential problems raised by intermixing.
254 If intermixing works for you, it's because your application
255 and DLLs are avoiding the corruption of each of the CRTs'
256 internal states, maybe by careful design, or maybe by fortune.
258 Also note that linking ZLIB1.DLL to non-Microsoft CRTs (such
259 as those provided by Borland) raises similar problems.
262 10. Why are you linking ZLIB1.DLL to MSVCRT.DLL?
264 - MSVCRT.DLL exists on every Windows 95 with a new service pack
265 installed, or with Microsoft Internet Explorer 4 or later, and
266 on all other Windows 4.x or later (Windows 98, Windows NT 4,
267 or later). It is freely distributable; if not present in the
268 system, it can be downloaded from Microsoft or from other
269 software provider for free.
271 The fact that MSVCRT.DLL does not exist on a virgin Windows 95
272 is not so problematic. The number of Windows 95 installations
273 is rapidly decreasing, Microsoft stopped supporting it a long
274 time ago, and many recent applications from various vendors,
275 including Microsoft, do not even run on it. Furthermore, no
276 serious user should run Windows 95 without a proper update
279 There is also the fact that the mainstream C compilers for
280 Windows are Microsoft Visual C++ 6.0, and gcc/MinGW. Both
281 are producing executables that link to MSVCRT.DLL by default,
282 without offering other dynamic CRTs as alternatives easy to
286 11. Why are you not linking ZLIB1.DLL to
287 <<my favorite C run-time library>> ?
289 - We considered and abandoned the following alternatives:
291 * Linking ZLIB1.DLL to a static C library (LIBC.LIB, or
292 LIBCMT.LIB) is not a good option. People are using the DLL
293 mainly to save disk space. If you are linking your program
294 to a static C library, you may as well consider linking zlib
297 * Linking ZLIB1.DLL to CRTDLL.DLL looks very appealing,
298 because CRTDLL.DLL is present on every Win32 installation.
299 Unfortunately, it has a series of problems: it raises
300 difficulties when using it with C++ code, it does not work
301 with 64-bit file offsets, (and so on...), and Microsoft
302 discontinued its support a long time ago.
304 * Linking ZLIB1.DLL to MSVCR70.DLL, supplied with the
305 Microsoft .NET platform and Visual C++ 7.0 or newer, is not
306 a good option. Although it is available for free download
307 and distribution, its presence is scarce on today's Win32
308 installations. If it will ever become more popular than
309 MSVCRT.DLL and will be pre-installed on the future Win32
310 systems, we will probably think again about it.
312 * Linking ZLIB1.DLL to NTDLL.DLL is not possible.
313 NTDLL.DLL exports only a part of the C library, and only on
317 12. I need to link my own DLL build to a CRT different than
318 MSVCRT.DLL. What can I do?
320 - Feel free to rebuild the DLL from the zlib sources, and link
321 it the way you want. You should, however, clearly state that
322 your build is unofficial. You should give it a different file
323 name, and/or install it in a private directory that can be
324 accessed by your application only, and is not visible to the
325 others (e.g. it's not in the SYSTEM or the SYSTEM32 directory,
326 and it's not in the PATH). Otherwise, your build may clash
327 with applications that link to the official build.
329 For example, in Cygwin, zlib is linked to the Cygwin runtime
330 CYGWIN1.DLL, and it is distributed under the name CYGZ.DLL.
333 13. May I include additional pieces of code that I find useful,
334 link them in ZLIB1.DLL, and export them?
336 - No. A legitimate build of ZLIB1.DLL must not include code
337 that does not originate from the official zlib source code.
338 But you can make your own private DLL build, under a different
339 file name, as suggested in the previous answer.
341 For example, in Borland Delphi and C++ Builder, zlib is a part
342 of the standard VCL library. If an application links to VCL
343 dynamically, the name of the distributable binary (VCLxx.DLL)
344 does not posess any danger of clashing with a legitimate but
345 incompatible ZLIB1.DLL.
348 14. May I remove some functionality out of ZLIB1.DLL, by enabling
349 macros like NO_GZCOMPRESS or NO_GZIP at compile time?
351 - No. A legitimate build of ZLIB1.DLL must provide the complete
352 zlib functionality, as implemented in the official zlib source
353 code. But you can make your own private DLL build, under a
354 different file name, as suggested in the previous answer.
357 15. I made my own ZLIB1.DLL build. Can I test it for compliance?
359 - We prefer that you download the official DLL from the zlib
360 web site. If you need something peculiar from this DLL, you
361 can send your suggestion to the zlib mailing list.
363 However, in case you do rebuild the DLL yourself, you can run
364 it with the test programs found in the DLL distribution.
365 Running these test programs is not a guarantee of compliance,
366 but a failure can imply a detected problem.
370 This document is written and maintained by
371 Cosmin Truta <cosmint@cs.ubbcluj.ro>
OSDN Git Service
