inflate

Name

inflate -- decompress data

Synopsis

#include <zlib.h>

int inflate(z_streamp stream, int flush);

Description

The inflate() function shall attempt to decompress 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 inflate(), this structure should have been initialized by a call to inflateInit2_().

Note: inflateInit2_() is only in the binary standard; source level applications should initialize stream via a call to inflateInit() or inflateInit2().

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

next_in 

should point to the data to be decompressed.

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 decompressed data may be placed.

avail_out 

should contain the size in bytes of the buffer referenced by next_out

The inflate() function shall perform one or both of the following actions:

  1. Decompress input data from next_in and update next_in, avail_in and total_in to reflect the data that has been decompressed.

  2. Fill the output buffer referenced by next_out, and update next_out, avail_out, and total_out to reflect the decompressed 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 inflate() 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).

Flush Operation

The parameter flush determines when uncompressed bytes are added to the output buffer in next_out. If flush is Z_NO_FLUSH, inflate() may return with some data pending output, and not yet added to the output buffer.

If flush is Z_SYNC_FLUSH, inflate() shall flush all pending output to next_out, and update next_out and avail_out accordingly.

If flush is set to Z_BLOCK, inflate() shall stop adding data to the output buffer if and when the next compressed block boundary is reached (see RFC 1951: DEFLATE Compressed Data Format Specification).

If flush is set to Z_FINISH, all of the compressed input shall be decompressed and added to the output. If there is insufficient output space (i.e. the compressed input data uncompresses to more than avail_out bytes), then inflate() shall fail and return Z_BUF_ERROR.

Return Value

On success, inflate() shall return Z_OK if decompression progress has been made, or Z_STREAM_END if all of the input data has been decompressed and there was sufficient space in the output buffer to store the uncompressed result. On error, inflate() shall return a value to indicate the error.

Note: If inflate() 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 inflate() returns with either Z_OK or Z_STREAM_END and a non-zero avail_out.

On success, inflate() shall set the adler to the Adler-32 checksum of the output produced so far (i.e. total_out bytes).

Errors

On error, inflate() shall return a value as described below, and may 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.

Z_NEED_DICT 

A preset dictionary is required. The adler field shall be set to the Adler-32 checksum of the dictionary chosen by the compressor.