0
|
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.org/
|
|
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 (e.g. it's not in the SYSTEM or the SYSTEM32 directory,
|
|
354 |
and it's not in the PATH). Otherwise, your build may clash
|
|
355 |
with 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>
|