external/zlib-1.2.11/FAQ
author Sam Lantinga <slouken@libsdl.org>
Fri, 26 Oct 2018 14:58:01 -0700
changeset 617 d64228a395fc
parent 521 9ed2f7d4a251
permissions -rw-r--r--
Fixed webp library detection when cross-compiling for Windows
slouken@521
     1
slouken@521
     2
                Frequently Asked Questions about zlib
slouken@521
     3
slouken@521
     4
slouken@521
     5
If your question is not there, please check the zlib home page
slouken@521
     6
http://zlib.net/ which may have more recent information.
slouken@521
     7
The lastest zlib FAQ is at http://zlib.net/zlib_faq.html
slouken@521
     8
slouken@521
     9
slouken@521
    10
 1. Is zlib Y2K-compliant?
slouken@521
    11
slouken@521
    12
    Yes. zlib doesn't handle dates.
slouken@521
    13
slouken@521
    14
 2. Where can I get a Windows DLL version?
slouken@521
    15
slouken@521
    16
    The zlib sources can be compiled without change to produce a DLL.  See the
slouken@521
    17
    file win32/DLL_FAQ.txt in the zlib distribution.  Pointers to the
slouken@521
    18
    precompiled DLL are found in the zlib web site at http://zlib.net/ .
slouken@521
    19
slouken@521
    20
 3. Where can I get a Visual Basic interface to zlib?
slouken@521
    21
slouken@521
    22
    See
slouken@521
    23
        * http://marknelson.us/1997/01/01/zlib-engine/
slouken@521
    24
        * win32/DLL_FAQ.txt in the zlib distribution
slouken@521
    25
slouken@521
    26
 4. compress() returns Z_BUF_ERROR.
slouken@521
    27
slouken@521
    28
    Make sure that before the call of compress(), the length of the compressed
slouken@521
    29
    buffer is equal to the available size of the compressed buffer and not
slouken@521
    30
    zero.  For Visual Basic, check that this parameter is passed by reference
slouken@521
    31
    ("as any"), not by value ("as long").
slouken@521
    32
slouken@521
    33
 5. deflate() or inflate() returns Z_BUF_ERROR.
slouken@521
    34
slouken@521
    35
    Before making the call, make sure that avail_in and avail_out are not zero.
slouken@521
    36
    When setting the parameter flush equal to Z_FINISH, also make sure that
slouken@521
    37
    avail_out is big enough to allow processing all pending input.  Note that a
slouken@521
    38
    Z_BUF_ERROR is not fatal--another call to deflate() or inflate() can be
slouken@521
    39
    made with more input or output space.  A Z_BUF_ERROR may in fact be
slouken@521
    40
    unavoidable depending on how the functions are used, since it is not
slouken@521
    41
    possible to tell whether or not there is more output pending when
slouken@521
    42
    strm.avail_out returns with zero.  See http://zlib.net/zlib_how.html for a
slouken@521
    43
    heavily annotated example.
slouken@521
    44
slouken@521
    45
 6. Where's the zlib documentation (man pages, etc.)?
slouken@521
    46
slouken@521
    47
    It's in zlib.h .  Examples of zlib usage are in the files test/example.c
slouken@521
    48
    and test/minigzip.c, with more in examples/ .
slouken@521
    49
slouken@521
    50
 7. Why don't you use GNU autoconf or libtool or ...?
slouken@521
    51
slouken@521
    52
    Because we would like to keep zlib as a very small and simple package.
slouken@521
    53
    zlib is rather portable and doesn't need much configuration.
slouken@521
    54
slouken@521
    55
 8. I found a bug in zlib.
slouken@521
    56
slouken@521
    57
    Most of the time, such problems are due to an incorrect usage of zlib.
slouken@521
    58
    Please try to reproduce the problem with a small program and send the
slouken@521
    59
    corresponding source to us at zlib@gzip.org .  Do not send multi-megabyte
slouken@521
    60
    data files without prior agreement.
slouken@521
    61
slouken@521
    62
 9. Why do I get "undefined reference to gzputc"?
slouken@521
    63
slouken@521
    64
    If "make test" produces something like
slouken@521
    65
slouken@521
    66
       example.o(.text+0x154): undefined reference to `gzputc'
slouken@521
    67
slouken@521
    68
    check that you don't have old files libz.* in /usr/lib, /usr/local/lib or
slouken@521
    69
    /usr/X11R6/lib. Remove any old versions, then do "make install".
slouken@521
    70
slouken@521
    71
10. I need a Delphi interface to zlib.
slouken@521
    72
slouken@521
    73
    See the contrib/delphi directory in the zlib distribution.
slouken@521
    74
slouken@521
    75
11. Can zlib handle .zip archives?
slouken@521
    76
slouken@521
    77
    Not by itself, no.  See the directory contrib/minizip in the zlib
slouken@521
    78
    distribution.
slouken@521
    79
slouken@521
    80
12. Can zlib handle .Z files?
slouken@521
    81
slouken@521
    82
    No, sorry.  You have to spawn an uncompress or gunzip subprocess, or adapt
slouken@521
    83
    the code of uncompress on your own.
slouken@521
    84
slouken@521
    85
13. How can I make a Unix shared library?
slouken@521
    86
slouken@521
    87
    By default a shared (and a static) library is built for Unix.  So:
slouken@521
    88
slouken@521
    89
    make distclean
slouken@521
    90
    ./configure
slouken@521
    91
    make
slouken@521
    92
slouken@521
    93
14. How do I install a shared zlib library on Unix?
slouken@521
    94
slouken@521
    95
    After the above, then:
slouken@521
    96
slouken@521
    97
    make install
slouken@521
    98
slouken@521
    99
    However, many flavors of Unix come with a shared zlib already installed.
slouken@521
   100
    Before going to the trouble of compiling a shared version of zlib and
slouken@521
   101
    trying to install it, you may want to check if it's already there!  If you
slouken@521
   102
    can #include <zlib.h>, it's there.  The -lz option will probably link to
slouken@521
   103
    it.  You can check the version at the top of zlib.h or with the
slouken@521
   104
    ZLIB_VERSION symbol defined in zlib.h .
slouken@521
   105
slouken@521
   106
15. I have a question about OttoPDF.
slouken@521
   107
slouken@521
   108
    We are not the authors of OttoPDF. The real author is on the OttoPDF web
slouken@521
   109
    site: Joel Hainley, jhainley@myndkryme.com.
slouken@521
   110
slouken@521
   111
16. Can zlib decode Flate data in an Adobe PDF file?
slouken@521
   112
slouken@521
   113
    Yes. See http://www.pdflib.com/ . To modify PDF forms, see
slouken@521
   114
    http://sourceforge.net/projects/acroformtool/ .
slouken@521
   115
slouken@521
   116
17. Why am I getting this "register_frame_info not found" error on Solaris?
slouken@521
   117
slouken@521
   118
    After installing zlib 1.1.4 on Solaris 2.6, running applications using zlib
slouken@521
   119
    generates an error such as:
slouken@521
   120
slouken@521
   121
        ld.so.1: rpm: fatal: relocation error: file /usr/local/lib/libz.so:
slouken@521
   122
        symbol __register_frame_info: referenced symbol not found
slouken@521
   123
slouken@521
   124
    The symbol __register_frame_info is not part of zlib, it is generated by
slouken@521
   125
    the C compiler (cc or gcc).  You must recompile applications using zlib
slouken@521
   126
    which have this problem.  This problem is specific to Solaris.  See
slouken@521
   127
    http://www.sunfreeware.com for Solaris versions of zlib and applications
slouken@521
   128
    using zlib.
slouken@521
   129
slouken@521
   130
18. Why does gzip give an error on a file I make with compress/deflate?
slouken@521
   131
slouken@521
   132
    The compress and deflate functions produce data in the zlib format, which
slouken@521
   133
    is different and incompatible with the gzip format.  The gz* functions in
slouken@521
   134
    zlib on the other hand use the gzip format.  Both the zlib and gzip formats
slouken@521
   135
    use the same compressed data format internally, but have different headers
slouken@521
   136
    and trailers around the compressed data.
slouken@521
   137
slouken@521
   138
19. Ok, so why are there two different formats?
slouken@521
   139
slouken@521
   140
    The gzip format was designed to retain the directory information about a
slouken@521
   141
    single file, such as the name and last modification date.  The zlib format
slouken@521
   142
    on the other hand was designed for in-memory and communication channel
slouken@521
   143
    applications, and has a much more compact header and trailer and uses a
slouken@521
   144
    faster integrity check than gzip.
slouken@521
   145
slouken@521
   146
20. Well that's nice, but how do I make a gzip file in memory?
slouken@521
   147
slouken@521
   148
    You can request that deflate write the gzip format instead of the zlib
slouken@521
   149
    format using deflateInit2().  You can also request that inflate decode the
slouken@521
   150
    gzip format using inflateInit2().  Read zlib.h for more details.
slouken@521
   151
slouken@521
   152
21. Is zlib thread-safe?
slouken@521
   153
slouken@521
   154
    Yes.  However any library routines that zlib uses and any application-
slouken@521
   155
    provided memory allocation routines must also be thread-safe.  zlib's gz*
slouken@521
   156
    functions use stdio library routines, and most of zlib's functions use the
slouken@521
   157
    library memory allocation routines by default.  zlib's *Init* functions
slouken@521
   158
    allow for the application to provide custom memory allocation routines.
slouken@521
   159
slouken@521
   160
    Of course, you should only operate on any given zlib or gzip stream from a
slouken@521
   161
    single thread at a time.
slouken@521
   162
slouken@521
   163
22. Can I use zlib in my commercial application?
slouken@521
   164
slouken@521
   165
    Yes.  Please read the license in zlib.h.
slouken@521
   166
slouken@521
   167
23. Is zlib under the GNU license?
slouken@521
   168
slouken@521
   169
    No.  Please read the license in zlib.h.
slouken@521
   170
slouken@521
   171
24. The license says that altered source versions must be "plainly marked". So
slouken@521
   172
    what exactly do I need to do to meet that requirement?
slouken@521
   173
slouken@521
   174
    You need to change the ZLIB_VERSION and ZLIB_VERNUM #defines in zlib.h.  In
slouken@521
   175
    particular, the final version number needs to be changed to "f", and an
slouken@521
   176
    identification string should be appended to ZLIB_VERSION.  Version numbers
slouken@521
   177
    x.x.x.f are reserved for modifications to zlib by others than the zlib
slouken@521
   178
    maintainers.  For example, if the version of the base zlib you are altering
slouken@521
   179
    is "1.2.3.4", then in zlib.h you should change ZLIB_VERNUM to 0x123f, and
slouken@521
   180
    ZLIB_VERSION to something like "1.2.3.f-zachary-mods-v3".  You can also
slouken@521
   181
    update the version strings in deflate.c and inftrees.c.
slouken@521
   182
slouken@521
   183
    For altered source distributions, you should also note the origin and
slouken@521
   184
    nature of the changes in zlib.h, as well as in ChangeLog and README, along
slouken@521
   185
    with the dates of the alterations.  The origin should include at least your
slouken@521
   186
    name (or your company's name), and an email address to contact for help or
slouken@521
   187
    issues with the library.
slouken@521
   188
slouken@521
   189
    Note that distributing a compiled zlib library along with zlib.h and
slouken@521
   190
    zconf.h is also a source distribution, and so you should change
slouken@521
   191
    ZLIB_VERSION and ZLIB_VERNUM and note the origin and nature of the changes
slouken@521
   192
    in zlib.h as you would for a full source distribution.
slouken@521
   193
slouken@521
   194
25. Will zlib work on a big-endian or little-endian architecture, and can I
slouken@521
   195
    exchange compressed data between them?
slouken@521
   196
slouken@521
   197
    Yes and yes.
slouken@521
   198
slouken@521
   199
26. Will zlib work on a 64-bit machine?
slouken@521
   200
slouken@521
   201
    Yes.  It has been tested on 64-bit machines, and has no dependence on any
slouken@521
   202
    data types being limited to 32-bits in length.  If you have any
slouken@521
   203
    difficulties, please provide a complete problem report to zlib@gzip.org
slouken@521
   204
slouken@521
   205
27. Will zlib decompress data from the PKWare Data Compression Library?
slouken@521
   206
slouken@521
   207
    No.  The PKWare DCL uses a completely different compressed data format than
slouken@521
   208
    does PKZIP and zlib.  However, you can look in zlib's contrib/blast
slouken@521
   209
    directory for a possible solution to your problem.
slouken@521
   210
slouken@521
   211
28. Can I access data randomly in a compressed stream?
slouken@521
   212
slouken@521
   213
    No, not without some preparation.  If when compressing you periodically use
slouken@521
   214
    Z_FULL_FLUSH, carefully write all the pending data at those points, and
slouken@521
   215
    keep an index of those locations, then you can start decompression at those
slouken@521
   216
    points.  You have to be careful to not use Z_FULL_FLUSH too often, since it
slouken@521
   217
    can significantly degrade compression.  Alternatively, you can scan a
slouken@521
   218
    deflate stream once to generate an index, and then use that index for
slouken@521
   219
    random access.  See examples/zran.c .
slouken@521
   220
slouken@521
   221
29. Does zlib work on MVS, OS/390, CICS, etc.?
slouken@521
   222
slouken@521
   223
    It has in the past, but we have not heard of any recent evidence.  There
slouken@521
   224
    were working ports of zlib 1.1.4 to MVS, but those links no longer work.
slouken@521
   225
    If you know of recent, successful applications of zlib on these operating
slouken@521
   226
    systems, please let us know.  Thanks.
slouken@521
   227
slouken@521
   228
30. Is there some simpler, easier to read version of inflate I can look at to
slouken@521
   229
    understand the deflate format?
slouken@521
   230
slouken@521
   231
    First off, you should read RFC 1951.  Second, yes.  Look in zlib's
slouken@521
   232
    contrib/puff directory.
slouken@521
   233
slouken@521
   234
31. Does zlib infringe on any patents?
slouken@521
   235
slouken@521
   236
    As far as we know, no.  In fact, that was originally the whole point behind
slouken@521
   237
    zlib.  Look here for some more information:
slouken@521
   238
slouken@521
   239
    http://www.gzip.org/#faq11
slouken@521
   240
slouken@521
   241
32. Can zlib work with greater than 4 GB of data?
slouken@521
   242
slouken@521
   243
    Yes.  inflate() and deflate() will process any amount of data correctly.
slouken@521
   244
    Each call of inflate() or deflate() is limited to input and output chunks
slouken@521
   245
    of the maximum value that can be stored in the compiler's "unsigned int"
slouken@521
   246
    type, but there is no limit to the number of chunks.  Note however that the
slouken@521
   247
    strm.total_in and strm_total_out counters may be limited to 4 GB.  These
slouken@521
   248
    counters are provided as a convenience and are not used internally by
slouken@521
   249
    inflate() or deflate().  The application can easily set up its own counters
slouken@521
   250
    updated after each call of inflate() or deflate() to count beyond 4 GB.
slouken@521
   251
    compress() and uncompress() may be limited to 4 GB, since they operate in a
slouken@521
   252
    single call.  gzseek() and gztell() may be limited to 4 GB depending on how
slouken@521
   253
    zlib is compiled.  See the zlibCompileFlags() function in zlib.h.
slouken@521
   254
slouken@521
   255
    The word "may" appears several times above since there is a 4 GB limit only
slouken@521
   256
    if the compiler's "long" type is 32 bits.  If the compiler's "long" type is
slouken@521
   257
    64 bits, then the limit is 16 exabytes.
slouken@521
   258
slouken@521
   259
33. Does zlib have any security vulnerabilities?
slouken@521
   260
slouken@521
   261
    The only one that we are aware of is potentially in gzprintf().  If zlib is
slouken@521
   262
    compiled to use sprintf() or vsprintf(), then there is no protection
slouken@521
   263
    against a buffer overflow of an 8K string space (or other value as set by
slouken@521
   264
    gzbuffer()), other than the caller of gzprintf() assuring that the output
slouken@521
   265
    will not exceed 8K.  On the other hand, if zlib is compiled to use
slouken@521
   266
    snprintf() or vsnprintf(), which should normally be the case, then there is
slouken@521
   267
    no vulnerability.  The ./configure script will display warnings if an
slouken@521
   268
    insecure variation of sprintf() will be used by gzprintf().  Also the
slouken@521
   269
    zlibCompileFlags() function will return information on what variant of
slouken@521
   270
    sprintf() is used by gzprintf().
slouken@521
   271
slouken@521
   272
    If you don't have snprintf() or vsnprintf() and would like one, you can
slouken@521
   273
    find a portable implementation here:
slouken@521
   274
slouken@521
   275
        http://www.ijs.si/software/snprintf/
slouken@521
   276
slouken@521
   277
    Note that you should be using the most recent version of zlib.  Versions
slouken@521
   278
    1.1.3 and before were subject to a double-free vulnerability, and versions
slouken@521
   279
    1.2.1 and 1.2.2 were subject to an access exception when decompressing
slouken@521
   280
    invalid compressed data.
slouken@521
   281
slouken@521
   282
34. Is there a Java version of zlib?
slouken@521
   283
slouken@521
   284
    Probably what you want is to use zlib in Java. zlib is already included
slouken@521
   285
    as part of the Java SDK in the java.util.zip package. If you really want
slouken@521
   286
    a version of zlib written in the Java language, look on the zlib home
slouken@521
   287
    page for links: http://zlib.net/ .
slouken@521
   288
slouken@521
   289
35. I get this or that compiler or source-code scanner warning when I crank it
slouken@521
   290
    up to maximally-pedantic. Can't you guys write proper code?
slouken@521
   291
slouken@521
   292
    Many years ago, we gave up attempting to avoid warnings on every compiler
slouken@521
   293
    in the universe.  It just got to be a waste of time, and some compilers
slouken@521
   294
    were downright silly as well as contradicted each other.  So now, we simply
slouken@521
   295
    make sure that the code always works.
slouken@521
   296
slouken@521
   297
36. Valgrind (or some similar memory access checker) says that deflate is
slouken@521
   298
    performing a conditional jump that depends on an uninitialized value.
slouken@521
   299
    Isn't that a bug?
slouken@521
   300
slouken@521
   301
    No.  That is intentional for performance reasons, and the output of deflate
slouken@521
   302
    is not affected.  This only started showing up recently since zlib 1.2.x
slouken@521
   303
    uses malloc() by default for allocations, whereas earlier versions used
slouken@521
   304
    calloc(), which zeros out the allocated memory.  Even though the code was
slouken@521
   305
    correct, versions 1.2.4 and later was changed to not stimulate these
slouken@521
   306
    checkers.
slouken@521
   307
slouken@521
   308
37. Will zlib read the (insert any ancient or arcane format here) compressed
slouken@521
   309
    data format?
slouken@521
   310
slouken@521
   311
    Probably not. Look in the comp.compression FAQ for pointers to various
slouken@521
   312
    formats and associated software.
slouken@521
   313
slouken@521
   314
38. How can I encrypt/decrypt zip files with zlib?
slouken@521
   315
slouken@521
   316
    zlib doesn't support encryption.  The original PKZIP encryption is very
slouken@521
   317
    weak and can be broken with freely available programs.  To get strong
slouken@521
   318
    encryption, use GnuPG, http://www.gnupg.org/ , which already includes zlib
slouken@521
   319
    compression.  For PKZIP compatible "encryption", look at
slouken@521
   320
    http://www.info-zip.org/
slouken@521
   321
slouken@521
   322
39. What's the difference between the "gzip" and "deflate" HTTP 1.1 encodings?
slouken@521
   323
slouken@521
   324
    "gzip" is the gzip format, and "deflate" is the zlib format.  They should
slouken@521
   325
    probably have called the second one "zlib" instead to avoid confusion with
slouken@521
   326
    the raw deflate compressed data format.  While the HTTP 1.1 RFC 2616
slouken@521
   327
    correctly points to the zlib specification in RFC 1950 for the "deflate"
slouken@521
   328
    transfer encoding, there have been reports of servers and browsers that
slouken@521
   329
    incorrectly produce or expect raw deflate data per the deflate
slouken@521
   330
    specification in RFC 1951, most notably Microsoft.  So even though the
slouken@521
   331
    "deflate" transfer encoding using the zlib format would be the more
slouken@521
   332
    efficient approach (and in fact exactly what the zlib format was designed
slouken@521
   333
    for), using the "gzip" transfer encoding is probably more reliable due to
slouken@521
   334
    an unfortunate choice of name on the part of the HTTP 1.1 authors.
slouken@521
   335
slouken@521
   336
    Bottom line: use the gzip format for HTTP 1.1 encoding.
slouken@521
   337
slouken@521
   338
40. Does zlib support the new "Deflate64" format introduced by PKWare?
slouken@521
   339
slouken@521
   340
    No.  PKWare has apparently decided to keep that format proprietary, since
slouken@521
   341
    they have not documented it as they have previous compression formats.  In
slouken@521
   342
    any case, the compression improvements are so modest compared to other more
slouken@521
   343
    modern approaches, that it's not worth the effort to implement.
slouken@521
   344
slouken@521
   345
41. I'm having a problem with the zip functions in zlib, can you help?
slouken@521
   346
slouken@521
   347
    There are no zip functions in zlib.  You are probably using minizip by
slouken@521
   348
    Giles Vollant, which is found in the contrib directory of zlib.  It is not
slouken@521
   349
    part of zlib.  In fact none of the stuff in contrib is part of zlib.  The
slouken@521
   350
    files in there are not supported by the zlib authors.  You need to contact
slouken@521
   351
    the authors of the respective contribution for help.
slouken@521
   352
slouken@521
   353
42. The match.asm code in contrib is under the GNU General Public License.
slouken@521
   354
    Since it's part of zlib, doesn't that mean that all of zlib falls under the
slouken@521
   355
    GNU GPL?
slouken@521
   356
slouken@521
   357
    No.  The files in contrib are not part of zlib.  They were contributed by
slouken@521
   358
    other authors and are provided as a convenience to the user within the zlib
slouken@521
   359
    distribution.  Each item in contrib has its own license.
slouken@521
   360
slouken@521
   361
43. Is zlib subject to export controls?  What is its ECCN?
slouken@521
   362
slouken@521
   363
    zlib is not subject to export controls, and so is classified as EAR99.
slouken@521
   364
slouken@521
   365
44. Can you please sign these lengthy legal documents and fax them back to us
slouken@521
   366
    so that we can use your software in our product?
slouken@521
   367
slouken@521
   368
    No. Go away. Shoo.