1644 lines
42 KiB
Groff
1644 lines
42 KiB
Groff
.\" $NetBSD: zlib.3,v 1.8 2012/03/15 19:04:47 njoly Exp $
|
|
.\" $OpenBSD: zlib.3,v 1.1 2003/09/25 09:12:09 jmc Exp $
|
|
.\"
|
|
.\" Copyright (C) 1995-2002 Jean-loup Gailly and Mark Adler
|
|
.\"
|
|
.\" This software is provided 'as-is', without any express or implied
|
|
.\" warranty. In no event will the authors be held liable for any damages
|
|
.\" arising from the use of this software.
|
|
.\"
|
|
.\" Permission is granted to anyone to use this software for any purpose,
|
|
.\" including commercial applications, and to alter it and redistribute it
|
|
.\" freely, subject to the following restrictions:
|
|
.\"
|
|
.\" The origin of this software must not be misrepresented; you must not
|
|
.\" claim that you wrote the original software. If you use this software
|
|
.\" in a product, an acknowledgment in the product documentation would be
|
|
.\" appreciated but is not required.
|
|
.\" Altered source versions must be plainly marked as such, and must not be
|
|
.\" misrepresented as being the original software.
|
|
.\" This notice may not be removed or altered from any source distribution.
|
|
.\"
|
|
.\" Converted to mdoc format for the OpenBSD project
|
|
.\" by Jason McIntyre <jmc@openbsd.org>
|
|
.\"
|
|
.Dd May 1, 2004
|
|
.Dt ZLIB 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm zlib
|
|
.Nd general purpose compression library
|
|
.Sh SYNOPSIS
|
|
.In zlib.h
|
|
.Ss Basic functions
|
|
.Ft const char *
|
|
.Fn zlibVersion "void"
|
|
.Ft int
|
|
.Fn deflateInit "z_streamp strm" "int level"
|
|
.Ft int
|
|
.Fn deflate "z_streamp strm" "int flush"
|
|
.Ft int
|
|
.Fn deflateEnd "z_streamp strm"
|
|
.Ft int
|
|
.Fn inflateInit "z_streamp strm"
|
|
.Ft int
|
|
.Fn inflate "z_streamp strm" "int flush"
|
|
.Ft int
|
|
.Fn inflateEnd "z_streamp strm"
|
|
.Ss Advanced functions
|
|
.Ft int
|
|
.Fn deflateInit2 "z_streamp strm" "int level" "int method" \
|
|
"int windowBits" "int memLevel" "int strategy"
|
|
.Ft int
|
|
.Fn deflateSetDictionary "z_streamp strm" "const Bytef *dictionary" \
|
|
"uInt dictLength"
|
|
.Ft int
|
|
.Fn deflateCopy "z_streamp dest" "z_streamp source"
|
|
.Ft int
|
|
.Fn deflateReset "z_streamp strm"
|
|
.Ft int
|
|
.Fn deflateParams "z_streamp strm" "int level" "int strategy"
|
|
.Ft int
|
|
.Fn inflateInit2 "z_streamp strm" "int windowBits"
|
|
.Ft int
|
|
.Fn inflateSetDictionary "z_streamp strm" "const Bytef *dictionary" "uInt dictLength"
|
|
.Ft int
|
|
.Fn inflateSync "z_streamp strm"
|
|
.Ft int
|
|
.Fn inflateReset "z_streamp strm"
|
|
.Ss Utility functions
|
|
.Fd typedef voidp gzFile ;
|
|
.Pp
|
|
.Ft int
|
|
.Fn compress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen"
|
|
.Ft int
|
|
.Fn compress2 "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen" "int level"
|
|
.Ft int
|
|
.Fn uncompress "Bytef *dest" "uLongf *destLen" "const Bytef *source" "uLong sourceLen"
|
|
.Ft gzFile
|
|
.Fn gzopen "const char *path" "const char *mode"
|
|
.Ft gzFile
|
|
.Fn gzdopen "int fd" "const char *mode"
|
|
.Ft int
|
|
.Fn gzsetparams "gzFile file" "int level" "int strategy"
|
|
.Ft int
|
|
.Fn gzread "gzFile file" "voidp buf" "unsigned len"
|
|
.Ft int
|
|
.Fn gzwrite "gzFile file" "const voidp buf" "unsigned len"
|
|
.Ft int
|
|
.Fn gzprintf "gzFile file" "const char *format" "..."
|
|
.Ft int
|
|
.Fn gzputs "gzFile file" "const char *s"
|
|
.Ft char *
|
|
.Fn gzgets "gzFile file" "char *buf" "int len"
|
|
.Ft int
|
|
.Fn gzputc "gzFile file" "int c"
|
|
.Ft int
|
|
.Fn gzgetc "gzFile file"
|
|
.Ft int
|
|
.Fn gzflush "gzFile file" "int flush"
|
|
.Ft z_off_t
|
|
.Fn gzseek "gzFile file" "z_off_t offset" "int whence"
|
|
.Ft int
|
|
.Fn gzrewind "gzFile file"
|
|
.Ft z_off_t
|
|
.Fn gztell "gzFile file"
|
|
.Ft int
|
|
.Fn gzeof "gzFile file"
|
|
.Ft int
|
|
.Fn gzclose "gzFile file"
|
|
.Ft const char *
|
|
.Fn gzerror "gzFile file" "int *errnum"
|
|
.Ss Checksum functions
|
|
.Ft uLong
|
|
.Fn adler32 "uLong adler" "const Bytef *buf" "uInt len"
|
|
.Ft uLong
|
|
.Fn crc32 "uLong crc" "const Bytef *buf" "uInt len"
|
|
.Sh DESCRIPTION
|
|
This manual page describes the
|
|
.Nm
|
|
general purpose compression library, version 1.1.4.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
compression library provides in-memory compression and decompression functions,
|
|
including integrity checks of the uncompressed data.
|
|
This version of the library supports only one compression method
|
|
.Pq deflation
|
|
but other algorithms will be added later and will have the same
|
|
stream interface.
|
|
.Pp
|
|
Compression can be done in a single step if the buffers are large enough
|
|
.Pq for example if an input file is mmap'ed ,
|
|
or can be done by repeated calls of the compression function.
|
|
In the latter case, the application must provide more input
|
|
and/or consume the output
|
|
.Pq providing more output space
|
|
before each call.
|
|
.Pp
|
|
The library also supports reading and writing files in
|
|
.Xr gzip 1
|
|
.Pq .gz
|
|
format with an interface similar to that of
|
|
.Xr stdio 3 .
|
|
.Pp
|
|
The library does not install any signal handler.
|
|
The decoder checks the consistency of the compressed data,
|
|
so the library should never crash even in case of corrupted input.
|
|
.Pp
|
|
The functions within the library are divided into the following sections:
|
|
.Pp
|
|
.Bl -dash -offset indent -compact
|
|
.It
|
|
Basic functions
|
|
.It
|
|
Advanced functions
|
|
.It
|
|
Utility functions
|
|
.It
|
|
Checksum functions
|
|
.El
|
|
.Sh BASIC FUNCTIONS
|
|
.Bl -tag -width Ds
|
|
.It Fa const char * Fn zlibVersion "void" ;
|
|
.Pp
|
|
The application can compare
|
|
.Fn zlibVersion
|
|
and
|
|
.Dv ZLIB_VERSION
|
|
for consistency.
|
|
If the first character differs, the library code actually used is
|
|
not compatible with the
|
|
.In zlib.h
|
|
header file used by the application.
|
|
This check is automatically made by
|
|
.Fn deflateInit
|
|
and
|
|
.Fn inflateInit .
|
|
.It Fa int Fn deflateInit "z_streamp strm" "int level" ;
|
|
.Pp
|
|
The
|
|
.Fn deflateInit
|
|
function initializes the internal stream state for compression.
|
|
The fields
|
|
.Fa zalloc ,
|
|
.Fa zfree ,
|
|
and
|
|
.Fa opaque
|
|
must be initialized before by the caller.
|
|
If
|
|
.Fa zalloc
|
|
and
|
|
.Fa zfree
|
|
are set to
|
|
.Dv Z_NULL ,
|
|
.Fn deflateInit
|
|
updates them to use default allocation functions.
|
|
.Pp
|
|
The compression level must be
|
|
.Dv Z_DEFAULT_COMPRESSION ,
|
|
or between 0 and 9:
|
|
1 gives best speed, 9 gives best compression, 0 gives no compression at all
|
|
(the input data is simply copied a block at a time).
|
|
.Pp
|
|
.Dv Z_DEFAULT_COMPRESSION
|
|
requests a default compromise between speed and compression
|
|
.Pq currently equivalent to level 6 .
|
|
.Pp
|
|
.Fn deflateInit
|
|
returns
|
|
.Dv Z_OK
|
|
if successful,
|
|
.Dv Z_MEM_ERROR
|
|
if there was not enough memory,
|
|
.Dv Z_STREAM_ERROR
|
|
if level is not a valid compression level,
|
|
.Dv Z_VERSION_ERROR
|
|
if the
|
|
.Nm
|
|
library version
|
|
.Pq zlib_version
|
|
is incompatible with the version assumed by the caller
|
|
.Pq ZLIB_VERSION .
|
|
.Fa msg
|
|
is set to null if there is no error message.
|
|
.Fn deflateInit
|
|
does not perform any compression: this will be done by
|
|
.Fn deflate .
|
|
.It Fa int Fn deflate "z_streamp strm" "int flush" ;
|
|
.Pp
|
|
.Fn deflate
|
|
compresses as much data as possible, and stops when the input
|
|
buffer becomes empty or the output buffer becomes full.
|
|
It may introduce some output latency
|
|
.Pq reading input without producing any output
|
|
except when forced to flush.
|
|
.Pp
|
|
The detailed semantics are as follows.
|
|
.Fn deflate
|
|
performs one or both of the following actions:
|
|
.Pp
|
|
Compress more input starting at
|
|
.Fa next_in
|
|
and update
|
|
.Fa next_in
|
|
and
|
|
.Fa avail_in
|
|
accordingly.
|
|
If not all input can be processed
|
|
(because there is not enough room in the output buffer),
|
|
.Fa next_in
|
|
and
|
|
.Fa avail_in
|
|
are updated and processing will resume at this point for the next call to
|
|
.Fn deflate .
|
|
.Pp
|
|
Provide more output starting at
|
|
.Fa next_out
|
|
and update
|
|
.Fa next_out
|
|
and
|
|
.Fa avail_out
|
|
accordingly.
|
|
This action is forced if the parameter
|
|
.Fa flush
|
|
is non-zero.
|
|
Forcing
|
|
.Fa flush
|
|
frequently degrades the compression ratio,
|
|
so this parameter should be set only when necessary
|
|
.Pq in interactive applications .
|
|
Some output may be provided even if
|
|
.Fa flush
|
|
is not set.
|
|
.Pp
|
|
Before the call to
|
|
.Fn deflate ,
|
|
the application should ensure that at least
|
|
one of the actions is possible, by providing more input and/or consuming
|
|
more output, and updating
|
|
.Fa avail_in
|
|
or
|
|
.Fa avail_out
|
|
accordingly;
|
|
.Fa avail_out
|
|
should never be zero before the call.
|
|
The application can consume the compressed output when it wants,
|
|
for example when the output buffer is full
|
|
.Pq avail_out == 0 ,
|
|
or after each call to
|
|
.Fn deflate .
|
|
If
|
|
.Fn deflate
|
|
returns
|
|
.Dv Z_OK
|
|
and with zero
|
|
.Fa avail_out ,
|
|
it must be called again after making room in the
|
|
output buffer because there might be more output pending.
|
|
.Pp
|
|
If the parameter
|
|
.Fa flush
|
|
is set to
|
|
.Dv Z_SYNC_FLUSH ,
|
|
all pending output is flushed to the output buffer and the output
|
|
is aligned on a byte boundary, so that the decompressor can get all
|
|
input data available so far.
|
|
(In particular,
|
|
.Fa avail_in
|
|
is zero after the call if enough output space
|
|
has been provided before the call.)
|
|
Flushing may degrade compression for some compression algorithms
|
|
and so it should be used only when necessary.
|
|
.Pp
|
|
If
|
|
.Fa flush
|
|
is set to
|
|
.Dv Z_FULL_FLUSH ,
|
|
all output is flushed as with
|
|
.Dv Z_SYNC_FLUSH ,
|
|
and the compression state is reset so that decompression can restart from this
|
|
point if previous compressed data has been damaged or if random access
|
|
is desired.
|
|
Using
|
|
.Dv Z_FULL_FLUSH
|
|
too often can seriously degrade the compression.
|
|
.Pp
|
|
If
|
|
.Fn deflate
|
|
returns with avail_out == 0, this function must be called again
|
|
with the same value of the flush parameter and more output space
|
|
(updated
|
|
.Fa avail_out ) ,
|
|
until the flush is complete
|
|
.Pf ( Fn deflate
|
|
returns with non-zero
|
|
.Fa avail_out ) .
|
|
.Pp
|
|
If the parameter
|
|
.Fa flush
|
|
is set to
|
|
.Dv Z_FINISH ,
|
|
pending input is processed, pending output is flushed and
|
|
.Fn deflate
|
|
returns with
|
|
.Dv Z_STREAM_END
|
|
if there was enough output space; if
|
|
.Fn deflate
|
|
returns with
|
|
.Dv Z_OK ,
|
|
this function must be called again with
|
|
.Dv Z_FINISH
|
|
and more output space
|
|
(updated
|
|
.Fa avail_out
|
|
but no more input data, until it returns with
|
|
.Dv Z_STREAM_END
|
|
or an error.
|
|
After
|
|
.Fn deflate
|
|
has returned
|
|
.Dv Z_STREAM_END ,
|
|
the only possible operations on the stream are
|
|
.Fn deflateReset
|
|
or
|
|
.Fn deflateEnd .
|
|
.Pp
|
|
.Dv Z_FINISH
|
|
can be used immediately after
|
|
.Fn deflateInit
|
|
if all the compression is to be done in a single step.
|
|
In this case,
|
|
.Fa avail_out
|
|
must be at least 0.1% larger than
|
|
.Fa avail_in
|
|
plus 12 bytes.
|
|
If
|
|
.Fn deflate
|
|
does not return
|
|
.Dv Z_STREAM_END ,
|
|
then it must be called again as described above.
|
|
.Pp
|
|
.Fn deflate
|
|
sets strm-\*[Gt]adler to the Adler-32 checksum of all input read so far
|
|
(that is,
|
|
.Fa total_in
|
|
bytes).
|
|
.Pp
|
|
.Fn deflate
|
|
may update
|
|
.Fa data_type
|
|
if it can make a good guess about the input data type
|
|
.Pq Z_ASCII or Z_BINARY .
|
|
If in doubt, the data is considered binary.
|
|
This field is only for information purposes and does not affect
|
|
the compression algorithm in any manner.
|
|
.Pp
|
|
.Fn deflate
|
|
returns
|
|
.Dv Z_OK
|
|
if some progress has been made
|
|
.Pq more input processed or more output produced ,
|
|
.Dv Z_STREAM_END
|
|
if all input has been consumed and all output has been produced
|
|
(only when
|
|
.Fa flush
|
|
is set to
|
|
.Dv Z_FINISH ) ,
|
|
.Dv Z_STREAM_ERROR
|
|
if the stream state was inconsistent
|
|
(for example, if
|
|
.Fa next_in
|
|
or
|
|
.Fa next_out
|
|
was
|
|
.Dv NULL ) ,
|
|
.Dv Z_BUF_ERROR
|
|
if no progress is possible
|
|
(for example,
|
|
.Fa avail_in
|
|
or
|
|
.Fa avail_out
|
|
was zero).
|
|
.It Fa int Fn deflateEnd "z_streamp strm" ;
|
|
.Pp
|
|
All dynamically allocated data structures for this stream are freed.
|
|
This function discards any unprocessed input and does not flush any
|
|
pending output.
|
|
.Pp
|
|
.Fn deflateEnd
|
|
returns
|
|
.Dv Z_OK
|
|
if successful,
|
|
.Dv Z_STREAM_ERROR
|
|
if the stream state was inconsistent,
|
|
.Dv Z_DATA_ERROR
|
|
if the stream was freed prematurely
|
|
.Pq some input or output was discarded .
|
|
In the error case,
|
|
.Fa msg
|
|
may be set but then points to a static string
|
|
.Pq which must not be deallocated .
|
|
.It Fa int Fn inflateInit "z_streamp strm" ;
|
|
The
|
|
.Fn inflateInit
|
|
function initializes the internal stream state for decompression.
|
|
The fields
|
|
.Fa next_in ,
|
|
.Fa avail_in ,
|
|
.Fa zalloc ,
|
|
.Fa zfree ,
|
|
and
|
|
.Fa opaque
|
|
must be initialized before by the caller.
|
|
If
|
|
.Fa next_in
|
|
is not
|
|
.Dv Z_NULL
|
|
and
|
|
.Fa avail_in
|
|
is large enough
|
|
.Pq the exact value depends on the compression method ,
|
|
.Fn inflateInit
|
|
determines the compression method from the
|
|
.Nm
|
|
header and allocates all data structures accordingly;
|
|
otherwise the allocation will be deferred to the first call to
|
|
.Fn inflate .
|
|
If
|
|
.Fa zalloc
|
|
and
|
|
.Fa zfree
|
|
are set to
|
|
.Dv Z_NULL ,
|
|
.Fn inflateInit
|
|
updates them to use default allocation functions.
|
|
.Pp
|
|
.Fn inflateInit
|
|
returns
|
|
.Dv Z_OK
|
|
if successful,
|
|
.Dv Z_MEM_ERROR
|
|
if there was not enough memory,
|
|
.Dv Z_VERSION_ERROR
|
|
if the
|
|
.Nm
|
|
library version is incompatible with the version assumed by the caller.
|
|
.Fa msg
|
|
is set to null if there is no error message.
|
|
.Fn inflateInit
|
|
does not perform any decompression apart from reading the
|
|
.Nm
|
|
header if present: this will be done by
|
|
.Fn inflate .
|
|
(So
|
|
.Fa next_in
|
|
and
|
|
.Fa avail_in
|
|
may be modified,
|
|
but
|
|
.Fa next_out
|
|
and
|
|
.Fa avail_out
|
|
are unchanged.)
|
|
.It Fa int Fn inflate "z_streamp strm" "int flush" ;
|
|
.Fn inflate
|
|
decompresses as much data as possible, and stops when the input
|
|
buffer becomes empty or the output buffer becomes full.
|
|
It may introduce some output latency
|
|
.Pq reading input without producing any output
|
|
except when forced to flush.
|
|
.Pp
|
|
The detailed semantics are as follows.
|
|
.Fn inflate
|
|
performs one or both of the following actions:
|
|
.Pp
|
|
Decompress more input starting at
|
|
.Fa next_in
|
|
and update
|
|
.Fa next_in
|
|
and
|
|
.Fa avail_in
|
|
accordingly.
|
|
If not all input can be processed
|
|
(because there is not enough room in the output buffer),
|
|
.Fa next_in
|
|
is updated and processing will resume at this point for the next call to
|
|
.Fn inflate .
|
|
.Pp
|
|
Provide more output starting at
|
|
.Fa next_out
|
|
and update
|
|
.Fa next_out
|
|
and
|
|
.Fa avail_out
|
|
accordingly.
|
|
.Fn inflate
|
|
provides as much output as possible,
|
|
until there is no more input data or no more space in the output buffer
|
|
.Pq see below about the flush parameter .
|
|
.Pp
|
|
Before the call to
|
|
.Fn inflate ,
|
|
the application should ensure that at least one of the actions is possible,
|
|
by providing more input and/or consuming more output,
|
|
and updating the next_* and avail_* values accordingly.
|
|
The application can consume the uncompressed output when it wants,
|
|
for example when the output buffer is full (avail_out == 0),
|
|
or after each call to
|
|
.Fn inflate .
|
|
If
|
|
.Fn inflate
|
|
returns
|
|
.Dv Z_OK
|
|
and with zero
|
|
.Fa avail_out ,
|
|
it must be called again after making room
|
|
in the output buffer because there might be more output pending.
|
|
.Pp
|
|
If the parameter
|
|
.Fa flush
|
|
is set to
|
|
.Dv Z_SYNC_FLUSH ,
|
|
.Fn inflate
|
|
flushes as much output as possible to the output buffer.
|
|
The flushing behavior of
|
|
.Fn inflate
|
|
is not specified for values of the flush parameter other than
|
|
.Dv Z_SYNC_FLUSH
|
|
and
|
|
.Dv Z_FINISH ,
|
|
but the current implementation actually flushes as much output
|
|
as possible anyway.
|
|
.Pp
|
|
.Fn inflate
|
|
should normally be called until it returns
|
|
.Dv Z_STREAM_END
|
|
or an error.
|
|
However if all decompression is to be performed in a single step
|
|
.Pq a single call to inflate ,
|
|
the parameter
|
|
.Fa flush
|
|
should be set to
|
|
.Dv Z_FINISH .
|
|
In this case all pending input is processed and all pending output is flushed;
|
|
.Fa avail_out
|
|
must be large enough to hold all the uncompressed data.
|
|
(The size of the uncompressed data may have been saved
|
|
by the compressor for this purpose.)
|
|
The next operation on this stream must be
|
|
.Fn inflateEnd
|
|
to deallocate the decompression state.
|
|
The use of
|
|
.Dv Z_FINISH
|
|
is never required, but can be used to inform
|
|
.Fn inflate
|
|
that a faster routine may be used for the single
|
|
.Fn inflate
|
|
call.
|
|
.Pp
|
|
If a preset dictionary is needed at this point (see
|
|
.Fn inflateSetDictionary
|
|
below),
|
|
.Fn inflate
|
|
sets strm-\*[Gt]adler to the Adler-32 checksum of the dictionary
|
|
chosen by the compressor and returns
|
|
.Dv Z_NEED_DICT ;
|
|
otherwise it sets strm-\*[Gt]adler to the Adler-32 checksum of all output produced
|
|
so far
|
|
(that is,
|
|
.Fa total_out
|
|
bytes)
|
|
and returns
|
|
.Dv Z_OK ,
|
|
.Dv Z_STREAM_END ,
|
|
or an error code as described below.
|
|
At the end of the stream,
|
|
.Fn inflate
|
|
checks that its computed Adler-32 checksum is equal to that saved by the
|
|
compressor and returns
|
|
.Dv Z_STREAM_END
|
|
only if the checksum is correct.
|
|
.Pp
|
|
.Fn inflate
|
|
returns
|
|
.Dv Z_OK
|
|
if some progress has been made
|
|
.Pq more input processed or more output produced ,
|
|
.Dv Z_STREAM_END
|
|
if the end of the compressed data has been reached and all uncompressed output
|
|
has been produced,
|
|
.Dv Z_NEED_DICT
|
|
if a preset dictionary is needed at this point,
|
|
.Dv Z_DATA_ERROR
|
|
if the input data was corrupted (input stream not conforming to the
|
|
.Nm
|
|
format or incorrect Adler-32 checksum),
|
|
.Dv Z_STREAM_ERROR
|
|
if the stream structure was inconsistent
|
|
(for example, if
|
|
.Fa next_in
|
|
or
|
|
.Fa next_out
|
|
was
|
|
.Dv NULL ) ,
|
|
.Dv Z_MEM_ERROR
|
|
if there was not enough memory,
|
|
.Dv Z_BUF_ERROR
|
|
if no progress is possible or if there was not enough room in the output buffer
|
|
when
|
|
.Dv Z_FINISH
|
|
is used.
|
|
In the
|
|
.Dv Z_DATA_ERROR
|
|
case, the application may then call
|
|
.Fn inflateSync
|
|
to look for a good compression block.
|
|
.It Fa int Fn inflateEnd "z_streamp strm" ;
|
|
All dynamically allocated data structures for this stream are freed.
|
|
This function discards any unprocessed input and does not flush any
|
|
pending output.
|
|
.Pp
|
|
.Fn inflateEnd
|
|
returns
|
|
.Dv Z_OK
|
|
if successful, or
|
|
.Dv Z_STREAM_ERROR
|
|
if the stream state was inconsistent.
|
|
In the error case,
|
|
.Fa msg
|
|
may be set but then points to a static string
|
|
.Pq which must not be deallocated .
|
|
.El
|
|
.Sh ADVANCED FUNCTIONS
|
|
The following functions are needed only in some special applications.
|
|
.Bl -tag -width Ds
|
|
.It Fa int Fn deflateInit2 "z_streamp strm" "int level" "int method" \
|
|
"int windowBits" "int memLevel" "int strategy" ;
|
|
.Pp
|
|
This is another version of
|
|
.Fn deflateInit
|
|
with more compression options.
|
|
The fields
|
|
.Fa next_in ,
|
|
.Fa zalloc ,
|
|
.Fa zfree ,
|
|
and
|
|
.Fa opaque
|
|
must be initialized before by the caller.
|
|
.Pp
|
|
The
|
|
.Fa method
|
|
parameter is the compression method.
|
|
It must be
|
|
.Dv Z_DEFLATED
|
|
in this version of the library.
|
|
.Pp
|
|
The
|
|
.Fa windowBits
|
|
parameter is the base two logarithm of the window size
|
|
.Pq the size of the history buffer .
|
|
It should be in the range 8..15 for this version of the library.
|
|
Larger values of this parameter result in better compression
|
|
at the expense of memory usage.
|
|
The default value is 15 if
|
|
.Fn deflateInit
|
|
is used instead.
|
|
.Pp
|
|
The
|
|
.Fa memLevel
|
|
parameter specifies how much memory should be allocated
|
|
for the internal compression state.
|
|
memLevel=1 uses minimum memory but is slow and reduces compression ratio;
|
|
memLevel=9 uses maximum memory for optimal speed.
|
|
The default value is 8.
|
|
See
|
|
.In zconf.h
|
|
for total memory usage as a function of
|
|
.Fa windowBits
|
|
and
|
|
.Fa memLevel .
|
|
.Pp
|
|
The
|
|
.Fa strategy
|
|
parameter is used to tune the compression algorithm.
|
|
Use the value
|
|
.Dv Z_DEFAULT_STRATEGY
|
|
for normal data;
|
|
.Dv Z_FILTERED
|
|
for data produced by a filter
|
|
.Pq or predictor ;
|
|
or
|
|
.Dv Z_HUFFMAN_ONLY
|
|
to force Huffman encoding only
|
|
.Pq no string match .
|
|
Filtered data consists mostly of small values with a
|
|
somewhat random distribution.
|
|
In this case, the compression algorithm is tuned to compress them better.
|
|
The effect of
|
|
.Dv Z_FILTERED
|
|
is to force more Huffman coding and less string matching;
|
|
it is somewhat intermediate between
|
|
.Dv Z_DEFAULT
|
|
and
|
|
.Dv Z_HUFFMAN_ONLY .
|
|
The
|
|
.Fa strategy
|
|
parameter only affects the compression ratio but not the correctness of the
|
|
compressed output, even if it is not set appropriately.
|
|
.Pp
|
|
.Fn deflateInit2
|
|
returns
|
|
.Dv Z_OK
|
|
if successful,
|
|
.Dv Z_MEM_ERROR
|
|
if there was not enough memory,
|
|
.Dv Z_STREAM_ERROR
|
|
if a parameter is invalid
|
|
.Pq such as an invalid method .
|
|
.Fa msg
|
|
is set to null if there is no error message.
|
|
.Fn deflateInit2
|
|
does not perform any compression: this will be done by
|
|
.Fn deflate .
|
|
.It Fa int Fn deflateSetDictionary "z_streamp strm" \
|
|
"const Bytef *dictionary" "uInt dictLength" ;
|
|
.Pp
|
|
Initializes the compression dictionary from the given byte sequence
|
|
without producing any compressed output.
|
|
This function must be called immediately after
|
|
.Fn deflateInit ,
|
|
.Fn deflateInit2 ,
|
|
or
|
|
.Fn deflateReset ,
|
|
before any call to
|
|
.Fn deflate .
|
|
The compressor and decompressor must use exactly the same dictionary
|
|
(see
|
|
.Fn inflateSetDictionary ) .
|
|
.Pp
|
|
The dictionary should consist of strings
|
|
.Pq byte sequences
|
|
that are likely to be encountered later in the data to be compressed,
|
|
with the most commonly used strings preferably put towards
|
|
the end of the dictionary.
|
|
Using a dictionary is most useful when the data to be compressed is short
|
|
and can be predicted with good accuracy;
|
|
the data can then be compressed better than with the default empty dictionary.
|
|
.Pp
|
|
Depending on the size of the compression data structures selected by
|
|
.Fn deflateInit
|
|
or
|
|
.Fn deflateInit2 ,
|
|
a part of the dictionary may in effect be discarded,
|
|
for example if the dictionary is larger than the window size in
|
|
.Fn deflate
|
|
or
|
|
.Fn deflate2 .
|
|
Thus the strings most likely to be useful should be
|
|
put at the end of the dictionary, not at the front.
|
|
.Pp
|
|
Upon return of this function, strm-\*[Gt]adler is set to the Adler-32 value
|
|
of the dictionary; the decompressor may later use this value to determine
|
|
which dictionary has been used by the compressor.
|
|
(The Adler-32 value applies to the whole dictionary even if only a subset
|
|
of the dictionary is actually used by the compressor.)
|
|
.Pp
|
|
.Fn deflateSetDictionary
|
|
returns
|
|
.Dv Z_OK
|
|
if successful,
|
|
or
|
|
.Dv Z_STREAM_ERROR
|
|
if a parameter is invalid
|
|
.Pq such as NULL dictionary
|
|
or the stream state is inconsistent
|
|
(for example if
|
|
.Fn deflate
|
|
has already been called for this stream or if the compression method is bsort).
|
|
.Fn deflateSetDictionary
|
|
does not perform any compression: this will be done by
|
|
.Fn deflate .
|
|
.It Fa int Fn deflateCopy "z_streamp dest" "z_streamp source" ;
|
|
.Pp
|
|
The
|
|
.Fn deflateCopy
|
|
function sets the destination stream as a complete copy of the source stream.
|
|
.Pp
|
|
This function can be useful when several compression strategies will be
|
|
tried, for example when there are several ways of pre-processing the input
|
|
data with a filter.
|
|
The streams that will be discarded should then be freed by calling
|
|
.Fn deflateEnd .
|
|
Note that
|
|
.Fn deflateCopy
|
|
duplicates the internal compression state which can be quite large,
|
|
so this strategy is slow and can consume lots of memory.
|
|
.Pp
|
|
.Fn deflateCopy
|
|
returns
|
|
.Dv Z_OK
|
|
if successful,
|
|
.Dv Z_MEM_ERROR
|
|
if there was not enough memory,
|
|
.Dv Z_STREAM_ERROR
|
|
if the source stream state was inconsistent
|
|
(such as
|
|
.Fa zalloc
|
|
being NULL).
|
|
.Fa msg
|
|
is left unchanged in both source and destination.
|
|
.It Fa int Fn deflateReset "z_streamp strm" ;
|
|
.Pp
|
|
This function is equivalent to
|
|
.Fn deflateEnd
|
|
followed by
|
|
.Fn deflateInit ,
|
|
but does not free and reallocate all the internal compression state.
|
|
The stream will keep the same compression level and any other attributes
|
|
that may have been set by
|
|
.Fn deflateInit2 .
|
|
.Pp
|
|
.Fn deflateReset
|
|
returns
|
|
.Dv Z_OK
|
|
if successful, or
|
|
.Dv Z_STREAM_ERROR
|
|
if the source stream state was inconsistent
|
|
(such as
|
|
.Fa zalloc
|
|
or
|
|
.Fa state
|
|
being NULL).
|
|
.It Fa int Fn deflateParams "z_streamp strm" "int level" "int strategy" ;
|
|
.Pp
|
|
The
|
|
.Fn deflateParams
|
|
function dynamically updates the compression level and compression strategy.
|
|
The interpretation of level and strategy is as in
|
|
.Fn deflateInit2 .
|
|
This can be used to switch between compression and straight copy
|
|
of the input data, or to switch to a different kind of input data
|
|
requiring a different strategy.
|
|
If the compression level is changed, the input available so far
|
|
is compressed with the old level
|
|
.Pq and may be flushed ;
|
|
the new level will take effect only at the next call to
|
|
.Fn deflate .
|
|
.Pp
|
|
Before the call to
|
|
.Fn deflateParams ,
|
|
the stream state must be set as for a call to
|
|
.Fn deflate ,
|
|
since the currently available input may have to be compressed and flushed.
|
|
In particular, strm-\*[Gt]avail_out must be non-zero.
|
|
.Pp
|
|
.Fn deflateParams
|
|
returns
|
|
.Dv Z_OK
|
|
if successful,
|
|
.Dv Z_STREAM_ERROR
|
|
if the source stream state was inconsistent or if a parameter was invalid, or
|
|
.Dv Z_BUF_ERROR
|
|
if strm-\*[Gt]avail_out was zero.
|
|
.It Fa int Fn inflateInit2 "z_streamp strm" "int windowBits" ;
|
|
.Pp
|
|
This is another version of
|
|
.Fn inflateInit
|
|
with an extra parameter.
|
|
The fields
|
|
.Fa next_in ,
|
|
.Fa avail_in ,
|
|
.Fa zalloc ,
|
|
.Fa zfree ,
|
|
and
|
|
.Fa opaque
|
|
must be initialized before by the caller.
|
|
.Pp
|
|
The
|
|
.Fa windowBits
|
|
parameter is the base two logarithm of the maximum window size
|
|
.Pq the size of the history buffer .
|
|
It should be in the range 8..15 for this version of the library.
|
|
The default value is 15 if
|
|
.Fn inflateInit
|
|
is used instead.
|
|
If a compressed stream with a larger window size is given as input,
|
|
.Fn inflate
|
|
will return with the error code
|
|
.Dv Z_DATA_ERROR
|
|
instead of trying to allocate a larger window.
|
|
.Pp
|
|
.Fn inflateInit2
|
|
returns
|
|
.Dv Z_OK
|
|
if successful,
|
|
.Dv Z_MEM_ERROR
|
|
if there was not enough memory,
|
|
.Dv Z_STREAM_ERROR
|
|
if a parameter is invalid
|
|
(such as a negative
|
|
.Fa memLevel ) .
|
|
.Fa msg
|
|
is set to null if there is no error message.
|
|
.Fn inflateInit2
|
|
does not perform any decompression apart from reading the
|
|
.Nm
|
|
header if present: this will be done by
|
|
.Fn inflate .
|
|
(So
|
|
.Fa next_in
|
|
and
|
|
.Fa avail_in
|
|
may be modified, but
|
|
.Fa next_out
|
|
and
|
|
.Fa avail_out
|
|
are unchanged.)
|
|
.It Fa int Fn inflateSetDictionary "z_streamp strm" \
|
|
"const Bytef *dictionary" "uInt dictLength" ;
|
|
.Pp
|
|
Initializes the decompression dictionary from the given uncompressed byte
|
|
sequence.
|
|
This function must be called immediately after a call to
|
|
.Fn inflate
|
|
if this call returned
|
|
.Dv Z_NEED_DICT .
|
|
The dictionary chosen by the compressor can be determined from the
|
|
Adler-32 value returned by this call to
|
|
.Fn inflate .
|
|
The compressor and decompressor must use exactly the same dictionary
|
|
(see
|
|
.Fn deflateSetDictionary ) .
|
|
.Pp
|
|
.Fn inflateSetDictionary
|
|
returns
|
|
.Dv Z_OK
|
|
if successful,
|
|
.Dv Z_STREAM_ERROR
|
|
if a parameter is invalid
|
|
.Pq such as NULL dictionary
|
|
or the stream state is inconsistent,
|
|
.Dv Z_DATA_ERROR
|
|
if the given dictionary doesn't match the expected one
|
|
.Pq incorrect Adler-32 value .
|
|
.Fn inflateSetDictionary
|
|
does not perform any decompression: this will be done by subsequent calls of
|
|
.Fn inflate .
|
|
.It Fa int Fn inflateSync "z_streamp strm" ;
|
|
.Pp
|
|
Skips invalid compressed data until a full flush point
|
|
(see above the description of
|
|
.Fn deflate
|
|
with
|
|
.Dv Z_FULL_FLUSH )
|
|
can be found, or until all available input is skipped.
|
|
No output is provided.
|
|
.Pp
|
|
.Fn inflateSync
|
|
returns
|
|
.Dv Z_OK
|
|
if a full flush point has been found,
|
|
.Dv Z_BUF_ERROR
|
|
if no more input was provided,
|
|
.Dv Z_DATA_ERROR
|
|
if no flush point has been found, or
|
|
.Dv Z_STREAM_ERROR
|
|
if the stream structure was inconsistent.
|
|
In the success case, the application may save the current value of
|
|
.Fa total_in
|
|
which indicates where valid compressed data was found.
|
|
In the error case, the application may repeatedly call
|
|
.Fn inflateSync ,
|
|
providing more input each time, until success or end of the input data.
|
|
.It Fa int Fn inflateReset "z_streamp strm" ;
|
|
.Pp
|
|
This function is equivalent to
|
|
.Fn inflateEnd
|
|
followed by
|
|
.Fn inflateInit ,
|
|
but does not free and reallocate all the internal decompression state.
|
|
The stream will keep attributes that may have been set by
|
|
.Fn inflateInit2 .
|
|
.Pp
|
|
.Fn inflateReset
|
|
returns
|
|
.Dv Z_OK
|
|
if successful, or
|
|
.Dv Z_STREAM_ERROR
|
|
if the source stream state was inconsistent
|
|
(such as
|
|
.Fa zalloc
|
|
or
|
|
.Fa state
|
|
being NULL).
|
|
.El
|
|
.Sh UTILITY FUNCTIONS
|
|
The following utility functions are implemented on top of the
|
|
basic stream-oriented functions.
|
|
To simplify the interface,
|
|
some default options are assumed (compression level and memory usage,
|
|
standard memory allocation functions).
|
|
The source code of these utility functions can easily be modified
|
|
if you need special options.
|
|
.Bl -tag -width Ds
|
|
.It Fa int Fn compress "Bytef *dest" "uLongf *destLen" \
|
|
"const Bytef *source" "uLong sourceLen" ;
|
|
.Pp
|
|
The
|
|
.Fn compress
|
|
function compresses the source buffer into the destination buffer.
|
|
.Fa sourceLen
|
|
is the byte length of the source buffer.
|
|
Upon entry,
|
|
.Fa destLen
|
|
is the total size of the destination buffer,
|
|
which must be at least 0.1% larger than
|
|
.Fa sourceLen
|
|
plus 12 bytes.
|
|
Upon exit,
|
|
.Fa destLen
|
|
is the actual size of the compressed buffer.
|
|
This function can be used to compress a whole file at once if the
|
|
input file is mmap'ed.
|
|
.Pp
|
|
.Fn compress
|
|
returns
|
|
.Dv Z_OK
|
|
if successful,
|
|
.Dv Z_MEM_ERROR
|
|
if there was not enough memory, or
|
|
.Dv Z_BUF_ERROR
|
|
if there was not enough room in the output buffer.
|
|
.It Fa int Fn compress2 "Bytef *dest" "uLongf *destLen" \
|
|
"const Bytef *source" "uLong sourceLen" "int level" ;
|
|
.Pp
|
|
The
|
|
.Fn compress2
|
|
function compresses the source buffer into the destination buffer.
|
|
The
|
|
.Fa level
|
|
parameter has the same meaning as in
|
|
.Fn deflateInit .
|
|
.Fa sourceLen
|
|
is the byte length of the source buffer.
|
|
Upon entry,
|
|
.Fa destLen
|
|
is the total size of the destination buffer,
|
|
which must be at least 0.1% larger than
|
|
.Fa sourceLen
|
|
plus 12 bytes.
|
|
Upon exit,
|
|
.Fa destLen
|
|
is the actual size of the compressed buffer.
|
|
.Pp
|
|
.Fn compress2
|
|
returns
|
|
.Dv Z_OK
|
|
if successful,
|
|
.Dv Z_MEM_ERROR
|
|
if there was not enough memory,
|
|
.Dv Z_BUF_ERROR
|
|
if there was not enough room in the output buffer, or
|
|
.Dv Z_STREAM_ERROR
|
|
if the level parameter is invalid.
|
|
.It Fa int Fn uncompress "Bytef *dest" "uLongf *destLen" \
|
|
"const Bytef *source" "uLong sourceLen" ;
|
|
.Pp
|
|
The
|
|
.Fn uncompress
|
|
function decompresses the source buffer into the destination buffer.
|
|
.Fa sourceLen
|
|
is the byte length of the source buffer.
|
|
Upon entry,
|
|
.Fa destLen
|
|
is the total size of the destination buffer,
|
|
which must be large enough to hold the entire uncompressed data.
|
|
(The size of the uncompressed data must have been saved previously
|
|
by the compressor and transmitted to the decompressor
|
|
by some mechanism outside the scope of this compression library.)
|
|
Upon exit,
|
|
.Fa destLen
|
|
is the actual size of the compressed buffer.
|
|
This function can be used to decompress a whole file at once if the
|
|
input file is mmap'ed.
|
|
.Pp
|
|
.Fn uncompress
|
|
returns
|
|
.Dv Z_OK
|
|
if successful,
|
|
.Dv Z_MEM_ERROR
|
|
if there was not enough memory,
|
|
.Dv Z_BUF_ERROR
|
|
if there was not enough room in the output buffer, or
|
|
.Dv Z_DATA_ERROR
|
|
if the input data was corrupted.
|
|
.It Fa gzFile Fn gzopen "const char *path" "const char *mode" ;
|
|
.Pp
|
|
The
|
|
.Fn gzopen
|
|
function opens a gzip
|
|
.Pq .gz
|
|
file for reading or writing.
|
|
The mode parameter is as in
|
|
.Xr fopen 3
|
|
.Po
|
|
.Qq rb
|
|
or
|
|
.Qq wb
|
|
.Pc
|
|
but can also include a compression level
|
|
.Pq Qq wb9
|
|
or a strategy:
|
|
.Sq f
|
|
for filtered data, as in
|
|
.Qq wb6f ;
|
|
.Sq h
|
|
for Huffman only compression, as in
|
|
.Qq wb1h .
|
|
(See the description of
|
|
.Fn deflateInit2
|
|
for more information about the strategy parameter.)
|
|
.Pp
|
|
.Fn gzopen
|
|
can be used to read a file which is not in gzip format;
|
|
in this case
|
|
.Fn gzread
|
|
will directly read from the file without decompression.
|
|
.Pp
|
|
.Fn gzopen
|
|
returns
|
|
.Dv NULL
|
|
if the file could not be opened or if there was
|
|
insufficient memory to allocate the (de)compression state;
|
|
errno can be checked to distinguish the two cases (if errno is zero, the
|
|
.Nm
|
|
error is
|
|
.Dv Z_MEM_ERROR ) .
|
|
.It Fa gzFile Fn gzdopen "int fd" "const char *mode" ;
|
|
.Pp
|
|
The
|
|
.Fn gzdopen
|
|
function associates a gzFile with the file descriptor
|
|
.Fa fd .
|
|
File descriptors are obtained from calls like
|
|
.Xr open 2 ,
|
|
.Xr dup 2 ,
|
|
.Xr creat 3 ,
|
|
.Xr pipe 2 ,
|
|
or
|
|
.Xr fileno 3
|
|
(if the file has been previously opened with
|
|
.Xr fopen 3 ) .
|
|
The
|
|
.Fa mode
|
|
parameter is as in
|
|
.Fn gzopen .
|
|
.Pp
|
|
The next call to
|
|
.Fn gzclose
|
|
on the returned gzFile will also close the file descriptor fd,
|
|
just like fclose(fdopen(fd), mode) closes the file descriptor fd.
|
|
If you want to keep fd open, use gzdopen(dup(fd), mode).
|
|
.Pp
|
|
.Fn gzdopen
|
|
returns
|
|
.Dv NULL
|
|
if there was insufficient memory to allocate the (de)compression state.
|
|
.It Fa int Fn gzsetparams "gzFile file" "int level" "int strategy" ;
|
|
.Pp
|
|
The
|
|
.Fn gzsetparams
|
|
function dynamically updates the compression level or strategy.
|
|
See the description of
|
|
.Fn deflateInit2
|
|
for the meaning of these parameters.
|
|
.Pp
|
|
.Fn gzsetparams
|
|
returns
|
|
.Dv Z_OK
|
|
if successful, or
|
|
.Dv Z_STREAM_ERROR
|
|
if the file was not opened for writing.
|
|
.It Fa int Fn gzread "gzFile file" "voidp buf" "unsigned len" ;
|
|
.Pp
|
|
The
|
|
.Fn gzread
|
|
function reads the given number of uncompressed bytes from the compressed file.
|
|
If the input file was not in gzip format,
|
|
.Fn gzread
|
|
copies the given number of bytes into the buffer.
|
|
.Pp
|
|
.Fn gzread
|
|
returns the number of uncompressed bytes actually read
|
|
(0 for end of file, \-1 for error).
|
|
.It Fa int Fn gzwrite "gzFile file" "const voidp buf" "unsigned len" ;
|
|
.Pp
|
|
The
|
|
.Fn gzwrite
|
|
function writes the given number of uncompressed bytes into the compressed file.
|
|
.Fn gzwrite
|
|
returns the number of uncompressed bytes actually written
|
|
.Pq 0 in case of error .
|
|
.It Fa int Fn gzprintf "gzFile file" "const char *format" "..." ;
|
|
.Pp
|
|
The
|
|
.Fn gzprintf
|
|
function converts, formats, and writes the args to the compressed file
|
|
under control of the format string, as in
|
|
.Xr fprintf 3 .
|
|
.Fn gzprintf
|
|
returns the number of uncompressed bytes actually written
|
|
.Pq 0 in case of error .
|
|
.It Fa int Fn gzputs "gzFile file" "const char *s" ;
|
|
.Pp
|
|
The
|
|
.Fn gzputs
|
|
function writes the given null-terminated string to the compressed file,
|
|
excluding the terminating null character.
|
|
.Pp
|
|
.Fn gzputs
|
|
returns the number of characters written, or \-1 in case of error.
|
|
.It Fa char * Fn gzgets "gzFile file" "char *buf" "int len" ;
|
|
.Pp
|
|
The
|
|
.Fn gzgets
|
|
function reads bytes from the compressed file until len\-1 characters are read,
|
|
or a newline character is read and transferred to
|
|
.Fa buf ,
|
|
or an end-of-file condition is encountered.
|
|
The string is then terminated with a null character.
|
|
.Pp
|
|
.Fn gzgets
|
|
returns
|
|
.Fa buf ,
|
|
or
|
|
.Dv Z_NULL
|
|
in case of error.
|
|
.It Fa int Fn gzputc "gzFile file" "int c" ;
|
|
.Pp
|
|
The
|
|
.Fn gzputc
|
|
function writes
|
|
.Fa c ,
|
|
converted to an unsigned char, into the compressed file.
|
|
.Fn gzputc
|
|
returns the value that was written, or \-1 in case of error.
|
|
.It Fa int Fn gzgetc "gzFile file" ;
|
|
.Pp
|
|
The
|
|
.Fn gzgetc
|
|
function reads one byte from the compressed file.
|
|
.Fn gzgetc
|
|
returns this byte or \-1 in case of end of file or error.
|
|
.It Fa int Fn gzflush "gzFile file" "int flush" ;
|
|
.Pp
|
|
The
|
|
.Fn gzflush
|
|
function flushes all pending output into the compressed file.
|
|
The parameter
|
|
.Fa flush
|
|
is as in the
|
|
.Fn deflate
|
|
function.
|
|
The return value is the
|
|
.Nm
|
|
error number (see function
|
|
.Fn gzerror
|
|
below).
|
|
.Fn gzflush
|
|
returns
|
|
.Dv Z_OK
|
|
if the flush parameter is
|
|
.Dv Z_FINISH
|
|
and all output could be flushed.
|
|
.Pp
|
|
.Fn gzflush
|
|
should be called only when strictly necessary because it can
|
|
degrade compression.
|
|
.It Fa z_off_t Fn gzseek "gzFile file" "z_off_t offset" "int whence" ;
|
|
.Pp
|
|
Sets the starting position for the next
|
|
.Fn gzread
|
|
or
|
|
.Fn gzwrite
|
|
on the given compressed file.
|
|
The offset represents a number of bytes in the uncompressed data stream.
|
|
The whence parameter is defined as in
|
|
.Xr lseek 2 ;
|
|
the value
|
|
.Dv SEEK_END
|
|
is not supported.
|
|
.Pp
|
|
If the file is opened for reading, this function is emulated but can be
|
|
extremely slow.
|
|
If the file is opened for writing, only forward seeks are supported;
|
|
.Fn gzseek
|
|
then compresses a sequence of zeroes up to the new starting position.
|
|
.Pp
|
|
.Fn gzseek
|
|
returns the resulting offset location as measured in bytes from
|
|
the beginning of the uncompressed stream, or \-1 in case of error,
|
|
in particular if the file is opened for writing and the new starting position
|
|
would be before the current position.
|
|
.It Fa int Fn gzrewind "gzFile file" ;
|
|
.Pp
|
|
The
|
|
.Fn gzrewind
|
|
function rewinds the given
|
|
.Fa file .
|
|
This function is supported only for reading.
|
|
.Pp
|
|
gzrewind(file) is equivalent to (int)gzseek(file, 0L, SEEK_SET).
|
|
.It Fa z_off_t Fn gztell "gzFile file" ;
|
|
.Pp
|
|
The
|
|
.Fn gztell
|
|
function returns the starting position for the next
|
|
.Fn gzread
|
|
or
|
|
.Fn gzwrite
|
|
on the given compressed file.
|
|
This position represents a number of bytes in the uncompressed data stream.
|
|
.Pp
|
|
gztell(file) is equivalent to gzseek(file, 0L, SEEK_CUR).
|
|
.It Fa int Fn gzeof "gzFile file" ;
|
|
.Pp
|
|
The
|
|
.Fn gzeof
|
|
function returns 1 when
|
|
.Dv EOF
|
|
has previously been detected reading the given input stream, otherwise zero.
|
|
.It Fa int Fn gzclose "gzFile file" ;
|
|
.Pp
|
|
The
|
|
.Fn gzclose
|
|
function flushes all pending output if necessary, closes the compressed file
|
|
and deallocates all the (de)compression state.
|
|
The return value is the
|
|
.Nm
|
|
error number (see function
|
|
.Fn gzerror
|
|
below).
|
|
.It Fa const char * Fn gzerror "gzFile file" "int *errnum" ;
|
|
.Pp
|
|
The
|
|
.Fn gzerror
|
|
function returns the error message for the last error which occurred on the
|
|
given compressed
|
|
.Fa file .
|
|
.Fa errnum
|
|
is set to the
|
|
.Nm
|
|
error number.
|
|
If an error occurred in the file system and not in the compression library,
|
|
.Fa errnum
|
|
is set to
|
|
.Dv Z_ERRNO
|
|
and the application may consult errno to get the exact error code.
|
|
.El
|
|
.Sh CHECKSUM FUNCTIONS
|
|
These functions are not related to compression but are exported
|
|
anyway because they might be useful in applications using the
|
|
compression library.
|
|
.Bl -tag -width Ds
|
|
.It Fa uLong Fn adler32 "uLong adler" "const Bytef *buf" "uInt len" ;
|
|
The
|
|
.Fn adler32
|
|
function updates a running Adler-32 checksum with the bytes buf[0..len-1]
|
|
and returns the updated checksum.
|
|
If
|
|
.Fa buf
|
|
is
|
|
.Dv NULL ,
|
|
this function returns the required initial value for the checksum.
|
|
.Pp
|
|
An Adler-32 checksum is almost as reliable as a CRC32 but can be computed
|
|
much faster.
|
|
Usage example:
|
|
.Bd -literal -offset indent
|
|
uLong adler = adler32(0L, Z_NULL, 0);
|
|
|
|
while (read_buffer(buffer, length) != EOF) {
|
|
adler = adler32(adler, buffer, length);
|
|
}
|
|
if (adler != original_adler) error();
|
|
.Ed
|
|
.It Fa uLong Fn crc32 "uLong crc" "const Bytef *buf" "uInt len" ;
|
|
The
|
|
.Fn crc32
|
|
function updates a running CRC with the bytes buf[0..len-1]
|
|
and returns the updated CRC.
|
|
If
|
|
.Fa buf
|
|
is
|
|
.Dv NULL ,
|
|
this function returns the required initial value for the CRC.
|
|
Pre- and post-conditioning
|
|
.Pq one's complement
|
|
is performed within this function so it shouldn't be done by the application.
|
|
Usage example:
|
|
.Bd -literal -offset indent
|
|
uLong crc = crc32(0L, Z_NULL, 0);
|
|
|
|
while (read_buffer(buffer, length) != EOF) {
|
|
crc = crc32(crc, buffer, length);
|
|
}
|
|
if (crc != original_crc) error();
|
|
.Ed
|
|
.El
|
|
.Sh STRUCTURES
|
|
.Bd -literal
|
|
struct internal_state;
|
|
|
|
typedef struct z_stream_s {
|
|
Bytef *next_in; /* next input byte */
|
|
uInt avail_in; /* number of bytes available at next_in */
|
|
uLong total_in; /* total nb of input bytes read so far */
|
|
|
|
Bytef *next_out; /* next output byte should be put there */
|
|
uInt avail_out; /* remaining free space at next_out */
|
|
uLong total_out; /* total nb of bytes output so far */
|
|
|
|
char *msg; /* last error message, NULL if no error */
|
|
struct internal_state FAR *state; /* not visible by applications */
|
|
|
|
alloc_func zalloc; /* used to allocate the internal state */
|
|
free_func zfree; /* used to free the internal state */
|
|
voidpf opaque; /* private data object passed to zalloc and zfree*/
|
|
|
|
int data_type; /*best guess about the data type: ascii or binary*/
|
|
uLong adler; /* Adler-32 value of the uncompressed data */
|
|
uLong reserved; /* reserved for future use */
|
|
} z_stream;
|
|
|
|
typedef z_stream FAR * z_streamp;
|
|
.Ed
|
|
.Pp
|
|
The application must update
|
|
.Fa next_in
|
|
and
|
|
.Fa avail_in
|
|
when
|
|
.Fa avail_in
|
|
has dropped to zero.
|
|
It must update
|
|
.Fa next_out
|
|
and
|
|
.Fa avail_out
|
|
when
|
|
.Fa avail_out
|
|
has dropped to zero.
|
|
The application must initialize
|
|
.Fa zalloc ,
|
|
.Fa zfree ,
|
|
and
|
|
.Fa opaque
|
|
before calling the init function.
|
|
All other fields are set by the compression library
|
|
and must not be updated by the application.
|
|
.Pp
|
|
The
|
|
.Fa opaque
|
|
value provided by the application will be passed as the first
|
|
parameter for calls to
|
|
.Fn zalloc
|
|
and
|
|
.Fn zfree .
|
|
This can be useful for custom memory management.
|
|
The compression library attaches no meaning to the
|
|
.Fa opaque
|
|
value.
|
|
.Pp
|
|
.Fa zalloc
|
|
must return
|
|
.Dv Z_NULL
|
|
if there is not enough memory for the object.
|
|
If
|
|
.Nm
|
|
is used in a multi-threaded application,
|
|
.Fa zalloc
|
|
and
|
|
.Fa zfree
|
|
must be thread safe.
|
|
.Pp
|
|
On 16-bit systems, the functions
|
|
.Fa zalloc
|
|
and
|
|
.Fa zfree
|
|
must be able to allocate exactly 65536 bytes,
|
|
but will not be required to allocate more than this if the symbol MAXSEG_64K
|
|
is defined (see
|
|
.In zconf.h ) .
|
|
.Pp
|
|
WARNING: On MSDOS, pointers returned by
|
|
.Fa zalloc
|
|
for objects of exactly 65536 bytes *must* have their offset normalized to zero.
|
|
The default allocation function provided by this library ensures this (see
|
|
.Pa zutil.c ) .
|
|
To reduce memory requirements and avoid any allocation of 64K objects,
|
|
at the expense of compression ratio,
|
|
compile the library with -DMAX_WBITS=14 (see
|
|
.In zconf.h ) .
|
|
.Pp
|
|
The fields
|
|
.Fa total_in
|
|
and
|
|
.Fa total_out
|
|
can be used for statistics or progress reports.
|
|
After compression,
|
|
.Fa total_in
|
|
holds the total size of the uncompressed data and may be saved for use
|
|
in the decompressor
|
|
(particularly if the decompressor wants to decompress everything
|
|
in a single step).
|
|
.Sh CONSTANTS
|
|
.Bd -literal
|
|
#define Z_NO_FLUSH 0
|
|
#define Z_PARTIAL_FLUSH 1 /* will be removed, use Z_SYNC_FLUSH instead */
|
|
#define Z_SYNC_FLUSH 2
|
|
#define Z_FULL_FLUSH 3
|
|
#define Z_FINISH 4
|
|
/* Allowed flush values; see deflate() below for details */
|
|
|
|
#define Z_OK 0
|
|
#define Z_STREAM_END 1
|
|
#define Z_NEED_DICT 2
|
|
#define Z_ERRNO (-1)
|
|
#define Z_STREAM_ERROR (-2)
|
|
#define Z_DATA_ERROR (-3)
|
|
#define Z_MEM_ERROR (-4)
|
|
#define Z_BUF_ERROR (-5)
|
|
#define Z_VERSION_ERROR (-6)
|
|
/* Return codes for the compression/decompression functions.
|
|
* Negative values are errors,
|
|
* positive values are used for special but normal events.
|
|
*/
|
|
|
|
#define Z_NO_COMPRESSION 0
|
|
#define Z_BEST_SPEED 1
|
|
#define Z_BEST_COMPRESSION 9
|
|
#define Z_DEFAULT_COMPRESSION (-1)
|
|
/* compression levels */
|
|
|
|
#define Z_FILTERED 1
|
|
#define Z_HUFFMAN_ONLY 2
|
|
#define Z_DEFAULT_STRATEGY 0
|
|
/* compression strategy; see deflateInit2() below for details */
|
|
|
|
#define Z_BINARY 0
|
|
#define Z_ASCII 1
|
|
#define Z_UNKNOWN 2
|
|
/* Possible values of the data_type field */
|
|
|
|
#define Z_DEFLATED 8
|
|
/* The deflate compression method
|
|
* (the only one supported in this version)
|
|
*/
|
|
|
|
#define Z_NULL 0 /* for initializing zalloc, zfree, opaque */
|
|
|
|
#define zlib_version zlibVersion()
|
|
/* for compatibility with versions \*[Lt] 1.0.2 */
|
|
.Ed
|
|
.Sh VARIOUS HACKS
|
|
deflateInit and inflateInit are macros to allow checking the
|
|
.Nm
|
|
version and the compiler's view of
|
|
.Fa z_stream .
|
|
.Bl -tag -width Ds
|
|
.It Fa int Fn deflateInit_ "z_stream strm" "int level" \
|
|
"const char *version" "int stream_size" ;
|
|
.It Fa int Fn inflateInit_ "z_stream strm" "const char *version" \
|
|
"int stream_size" ;
|
|
.It Fa int Fn deflateInit2_ "z_stream strm" "int level" "int method" \
|
|
"int windowBits" "int memLevel" "int strategy" "const char *version" \
|
|
"int stream_size" ;
|
|
.It Fa int Fn inflateInit2_ "z_stream strm" "int windowBits" \
|
|
"const char *version" "int stream_size" ;
|
|
.It Fa const char * Fn zError "int err" ;
|
|
.It Fa int Fn inflateSyncPoint "z_streamp z" ;
|
|
.It Fa const uLongf * Fn "get_crc_table" "void" ;
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Bl -tag -width 12n -compact
|
|
.It RFC 1950
|
|
ZLIB Compressed Data Format Specification.
|
|
.It RFC 1951
|
|
DEFLATE Compressed Data Format Specification.
|
|
.It RFC 1952
|
|
GZIP File Format Specification.
|
|
.El
|
|
.Pp
|
|
.Lk http://www.gzip.org/zlib/ "zlib"
|
|
.Sh HISTORY
|
|
This manual page is based on an HTML version of
|
|
.In zlib.h
|
|
converted by
|
|
.An piaip Aq piaip@csie.ntu.edu.tw
|
|
and was converted to mdoc format by the
|
|
.Ox
|
|
project.
|
|
.Sh AUTHORS
|
|
.An Jean-loup Gailly Aq jloup@gzip.org
|
|
.An Mark Adler Aq madler@alumni.caltech.edu
|