|
1
|
|
|
2
|
Frequently Asked Questions about ZLIB1.DLL |
|
3
|
|
|
4
|
|
|
5
|
This document describes the design, the rationale, and the usage |
|
6
|
of the common 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
|
https://www.zlib.net/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
|
|
|
224
|
10. 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
|
|
|
260
|
11. 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
|
|
|
277
|
12. 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
|
|
|
316
|
13. 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
|
|
|
341
|
14. 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
|
|
|
357
|
15. 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
|
|
|
370
|
16. 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
|
|
|
380
|
This document is written and maintained by |
|
381
|
Cosmin Truta <[email protected]> |
|
382
|
|