Linux Standard Base Specification 2.1 | ||
---|---|---|
<<< Previous | Next >>> |
The deflate() function shall attempt to compress data until either the input buffer is empty or the output buffer is full. The stream references a z_stream structure. Before the first call to deflate(), this structure should have been initialized by a call to deflateInit2_().
Note: deflateInit2_() is only in the binary standard; source level applications should initialize stream via a call to deflateInit() or deflateInit2().
next_in
should point to the data to be compressed.
avail_in
should contain the number of bytes of data in the
buffer referenced by next_in
.
next_out
should point to a buffer where compressed data may be placed.
avail_out
should contain the size in bytes of the
buffer referenced by next_out
The deflate() function shall perform one or both of the following actions:
Compress input data from next_in
and update next_in
,
avail_in
and
total_in
to reflect the data that has been
compressed.
Fill the output buffer referenced by next_out
,
and update next_out
,
avail_out
and
total_out
to reflect the compressed data that
has been placed there. If flush is not
Z_NO_FLUSH
, and
avail_out
indicates that there is still space in
output buffer, this action shall always occur (see below for further details).
The deflate() function shall return when either
avail_in
reaches zero (indicating that all the input
data has been compressed), or avail_out
reaches
zero (indicating that the output buffer is full).
On success, the deflate() function shall set the
adler
field of the stream
to the adler32() checksum of all the input data compressed
so far (represented by total_in
).
If the deflate() function shall attempt to determine
the type of input data, and set field data_type
in stream to Z_ASCII
if the
majority of the data bytes fall within the ASCII (ISO 646) printable
character range. Otherwise, it shall set data_type
to Z_BINARY
.
This data type is informational only, and does not affect the compression
algorithm.
Note: Future versions of the LSB may remove this requirement, since it is based on an outdated character set that does not support Internationalization, and does not affect the algorithm. It is included for information only at this release. Applications should not depend on this field.
The parameter flush determines when compressed bits
are added to the output buffer in next_out
.
If flush is Z_NO_FLUSH
,
deflate()
may return with some data pending output, and not yet added to the
output buffer.
If flush is Z_SYNC_FLUSH
,
deflate() shall flush all pending output to
next_out
and align the output to a byte
boundary. A synchronization point is generated in the output.
If flush is Z_FULL_FLUSH
,
all output shall be flushed, as for Z_SYNC_FLUSH
,
and the compression state shall be reset.
A synchronization point is generated in the output.
Rationale:
Z_SYNC_FLUSH
is intended to ensure that the compressed data contains all the data compressed so far, and allows a decompressor to reconstruct all of the input data.Z_FULL_FLUSH
allows decompression to restart from this point if the previous compressed data has been lost or damaged. Flushing is likely to degrade the performance of the compression system, and should only be used where necessary.
If flush is set to Z_FINISH
,
all pending input shall be processed and deflate()
shall return with Z_STREAM_END if there is
sufficient space in the output buffer at next_out
,
as indicated by avail_out
. If
deflate() is called with flush
set to Z_FINISH
and there is insufficient space to store
the compressed data, and no other error has occurred during compression,
deflate() shall return Z_OK,
and the application should call deflate() again with
flush unchanged, and having updated next_out
and avail_out
.
If all the compression is to be done in a single step,
deflate()
may be called with flush set to
Z_FINISH
immediately after the stream
has been initialized if avail_out
is set to at least the value returned by deflateBound().
On success, deflate() shall return
Z_OK, unless flush was set
to Z_FINISH
and there was sufficient space in the output buffer
to compress all of the input data. In this case, deflate()
shall return Z_STREAM_END.
On error, deflate() shall return a value to indicate
the error.
Note: If deflate() returns Z_OK and has set
avail_out
to zero, the function should be called again with the same value for flush, and with updatednext_out
andavail_out
until deflate() returns with Z_OK (or Z_STREAM_END if flush is set toZ_FINISH
) and a non-zeroavail_out
.
On error, deflate() shall return a value as described
below, and set the msg
field of
stream to point to a string describing the error:
Z_BUF_ERROR
No progress is possible; either avail_in
or avail_out
was zero.
Z_MEM_ERROR
Insufficient memory.
Z_STREAM_ERROR
The state (as represented in stream) is inconsistent, or
stream was NULL
.
<<< Previous | Home | Next >>> |
crc32 | Up | deflateBound |