Name

deflate — Attempts to compress data until either the input buffer is empty or the output buffer is full.

Library

Libz.lib

Synopsis

#include <zlib.h>
int deflate(z_streamp stream, int flush);

Return Value

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 updated next_out and avail_out until deflate() returns with Z_OK (or Z_STREAM_END if flush is set to Z_FINISH) and a non-zero avail_out.

Detailed Description

The deflate() function attempts 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().

In addition, the stream input and output buffers should have been initialized as follows:

`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.

Examples

To compress data "hello" until either the input buffer is empty or the output buffer is full:

#include <stdio.h>
#include <zlib.h>

To compress data "hello" until either the input buffer is empty or the output buffer is full

void Deflate( )
{    
    z_stream c_stream; /* compression stream */
    Byte * compr;
    uLong comprLen = 20*sizeof(int); 
    compr    = (Byte*)calloc((uInt)comprLen, 1);   
    const char hello[] = "hello, hello!";
    uLong len = (uLong)strlen(hello)+1;

    c_stream.zalloc = (alloc_func)0;
    c_stream.zfree = (free_func)0;
    c_stream.opaque = (voidpf)0;

    err = deflateInit(&c_stream, Z_DEFAULT_COMPRESSION);  
    c_stream.next_in  = (Bytef*)hello;
    c_stream.next_out = compr;

    while (c_stream.total_in != len && c_stream.total_out < comprLen)
    {
        c_stream.avail_in = c_stream.avail_out = 1; /* force small buffers */
        err = deflate(&c_stream, Z_NO_FLUSH);
    }
    /* Finish the stream, still forcing small buffers: */
    deflateEnd(&c_stream);
    free(compr);   
}

Flush Operation

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().

Errors

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`.

Feedback

For additional information or queries on this page send feedback