5. BZIP2

group BZIP2_API

bzip2 compresses files using the Burrows-Wheeler block-sorting text compression algorithm, and Huffman coding. Compression is considerably better than that achieved by more conventional LZ77/LZ78-based compressors, and approaches the performance of the PPM family of statistical compressors.

Core (low-level) library functions

int BZ2_bzCompressInit(bz_stream *strm, int blockSize100k, int verbosity, int workFactor)

Prepares for compression.

Parameters	Direction	Description
strm	in,out	Holds all data pertaining to the compression activity. It should be allocated and initialised prior to the call.
blockSize100k	in	Specifies the block size to be used for compression. It should be a value between 1 and 9 inclusive, and the actual block size used is 100000 x this figure.
verbosity	in	A number between 0 and 4 inclusive. 0 is silent, and greater numbers give increasingly verbose monitoring/debugging output.
workFactor	in	Controls how the compression phase behaves when presented with worst case, highly repetitive, input data.

Note

1. blockSize100k = 9 gives the best compression but takes most memory.

2. If the library has been compiled with -DBZ_NO_STDIO, no monitoring/debugging output will appear for any verbosity setting.

3. If compression runs into difficulties caused by repetitive data, the library switches from the standard sorting algorithm to a fallback algorithm . The fallback is slower than the standard algorithm by perhaps a factor of three, but always behaves reasonably, no matter how bad the input.

4. Lower values of workFactor reduce the amount of effort the standard algorithm will expend before resorting to the fallback. Set this parameter carefully;

   • too low, and many inputs will be handled by the fallback algorithm and so compress rather slowly,

   • too high, and your average-to-worst case compression times can become very large.

   • The default value of 30

     gives reasonable behaviour over a wide range of circumstances.

     Allowable values range from

     0 to 250 inclusive. 0 is a special case, equivalent to using the default value of 30.

5. Upon return, the internal state will have been allocated and initialised, and total_in_lo32, total_in_hi32, total_out_lo32 and total_out_hi32

   will have been set to zero. These four fields are used by the library to inform the caller of the total amount of data passed into and out of the library, respectively. You should not try to change them.

   As of version 1.0, 64-bit counts are maintained, even on 32-bit platforms, using the

   _hi32 fields to store the upper 32 bits of the count. So, for example, the total amount of data in is (total_in_hi32 << 32) + total_in_lo32.

Returns:

Result	Description
Success	BZ_OK
Fail	BZ_CONFIG_ERROR - If the library has been mis-compiled
	BZ_PARAM_ERROR If strm is NULL or blockSize < 1 or blockSize > 9 or verbosity < 0 or verbosity > 4 or workFactor < 0 or workFactor > 250
	BZ_MEM_ERROR - If available memory is insufficient.

int BZ2_bzCompress(bz_stream *strm, int action)

Provides more input and/or output buffer space for the library. The caller maintains input and output buffers, and calls BZ2_bzCompress to transfer data between them.

BZ2_bzCompress updates

next_in, avail_in and total_in to reflect the number of bytes it has read. It also updates next_out, avail_out and total_out

to reflect the number of bytes output.

A second purpose of BZ2_bzCompress is to request a change of mode of the compressed stream.

Parameters	Direction	Description
strm	in,out	Holds all data pertaining to the compression activity.
action	in	An integer value indicating the action to be taken.

Here’s a table which shows which actions are allowable in each state, what action will be taken, what the next state is, and what the non-error return values are. Note that you can’t explicitly ask what state the stream is in, but nor do you need to &#8212; it can be inferred from the values returned by BZ2_bzCompress.

State/ Action	Action Taken	Next State	Return Value
IDLE/any	Illegal. IDLE state only exists after BZ2_bzCompressEnd or before BZ2_bzCompressInit.	-	BZ_SEQUENCE_ERROR
RUNNING/BZ_RUN	Compress from next_in to next_out as much as possible.	RUNNING	BZ_RUN_OK
RUNNING/BZ_FLUSH	Remember current value of next_in . Compress from next_in to next_out as much as possible, but do not accept any more input.	FLUSHING	BZ_FLUSH_OK
RUNNING/BZ_FINISH	Remember current value of next_in . Compress from next_in to next_out as much as possible, but do not accept any more input.	FINISHING	BZ_FINISH_OK
FLUSHING/BZ_FLUSH	Compress from next_in to next_out as much as possible, but do not accept any more input.
	If all the existing input has been used up and all compressed output has been removed	RUNNING	BZ_RUN_OK
	else	FLUSHING	BZ_FLUSH_OK
FLUSHING/other	Illegal.	-	BZ_SEQUENCE_ERROR
FINISHING/BZ_FINISH	Compress from next_in to next_out as much as possible, but to not accept any more input.
	If all the existing input has been used up and all compressed output has been removed	IDLE	BZ_STREAM_END
	else	FINISHING	BZ_FINISH_OK
FINISHING/other	Illegal.	-	BZ_SEQUENCE_ERROR

Trivial other possible return value:

• BZ_PARAM_ERROR - If strm is NULL, or strm->s is NULL

Note

1. Before each call to BZ2_bzCompress, next_in should point at the data to be compressed, and avail_inshould indicate the number of bytes the library may read. Similarly, next_out should point to a buffer in which the compressed data is to be placed, with avail_out indicating the available output space.

2. You may provide and remove as little or as much data as you like on each call of BZ2_bzCompress. In the limit, it is acceptable to supply and remove data one byte at a time, although this would be terribly inefficient. You should always ensure that at least one byte of output space is available at each call.

Returns:

int BZ2_bzCompressEnd(bz_stream *strm)

Releases all memory associated with a compression stream.

Parameters	Direction	Description
strm	in,out	Holds all data pertaining to the compression activity.

Returns:

Result	Description
Success	BZ_OK
Fail	BZ_PARAM_ERROR - If strm is NULL or strm->s is NULL

int BZ2_bzDecompressInit(bz_stream *strm, int verbosity, int small)

Prepares for decompression.

Parameters	Direction	Description
strm	in,out	Holds all data pertaining to the decompression activity. strm should be allocated and initialised before the call.
verbosity	in	A number between 0 and 4 inclusive. 0 is silent, and greater numbers give increasingly verbose monitoring/debugging output.
small	in	If small is nonzero , the library will use an alternative decompression algorithm which uses less memory but at the cost of decompressing more slowly.

Note

1. Fields bzalloc, bzfree and opaque

   should be set if a custom memory allocator is required, or made NULL for the normal malloc / free routines.

   Upon return, the internal state will have been initialised, and

   total_in and total_out will be zero.

2. If the library has been compiled with -DBZ_NO_STDIO, no monitoring/debugging output will appear for any verbosity setting.

3. The amount of memory needed to decompress a stream cannot be determined until the stream’s header has been read, so even if BZ2_bzDecompressInit succeeds, a subsequent BZ2_bzDecompress could fail with BZ_MEM_ERROR.

Returns:

Result	Description
Success	BZ_OK
Fail	BZ_CONFIG_ERROR - If the library has been mis-compiled
	BZ_PARAM_ERROR - If ( small != 0 && small != 1 ) or (verbosity < 0 || verbosity > 4)
	BZ_MEM_ERROR - If available memory is insufficient.

int BZ2_bzDecompress(bz_stream *strm)

Provides more input and/or output buffer space for the library. The caller maintains input and output buffers, and uses BZ2_bzDecompress to transfer data between them.

BZ2_bzDecompress updates

next_in, avail_in and total_in to reflect the number of bytes it has read. It also updates next_out, avail_out and total_out to reflect the number of bytes output.

Parameters	Direction	Description
strm	in,out	Holds all data pertaining to the decompression activity.

Note

1. Before each call to BZ2_bzDecompress, next_in should point at the compressed data, and avail_in should indicate the number of bytes the library may read. Similarly, next_out should point to a buffer in which the uncompressed output is to be placed, with avail_out indicating available output space.

2. You may provide and remove as little or as much data as you like on each call of BZ2_bzDecompress. In the limit, it is acceptable to supply and remove data one byte at a time, although this would be terribly inefficient. You should always ensure that at least one byte of output space is available at each call.

3. You should provide input and remove output as described above, and repeatedly call BZ2_bzDecompress until BZ_STREAM_END is returned. Appearance of BZ_STREAM_END denotes that BZ2_bzDecompress has detected the logical end of the compressed stream. BZ2_bzDecompress will not produce BZ_STREAM_END until all output data has been placed into the output buffer, so once BZ_STREAM_END appears, you are guaranteed to have available all the decompressed output, and BZ2_bzDecompressEnd can safely be called.

4. If case of an error return value, you should call BZ2_bzDecompressEnd to clean up and release memory.

Returns:

Result	Description
Success	BZ_OK
Fail	BZ_PARAM_ERROR - If strm is NULL or strm->s is NULL or strm->avail_out < 1
	BZ_SEQUENCE_ERROR - If s->state is BZ_X_IDLE
	BZ_DATA_ERROR - If a data integrity error is detected in the compressed stream
	BZ_DATA_ERROR_MAGIC - If the compressed stream doesn’t begin with the right magic bytes
	BZ_MEM_ERROR - If available memory is insufficient.
	BZ_STREAM_END - If the logical end of the data stream was detected and all output in has been consumed, eg s->avail_out > 0

int BZ2_bzDecompressEnd(bz_stream *strm)

Releases all memory associated with a decompression stream.

Parameters	Direction	Description
strm	in,out	Holds all data pertaining to the decompression activity.

Returns:

Result	Description
Success	BZ_OK
Fail	BZ_PARAM_ERROR - If strm is NULL or strm->s is NULL

High(er) level library functions

This interface provides functions for reading and writing bzip2 format files. First, some general points.

1. All of the functions take an int* first argument, bzerror. After each call, bzerror should be consulted first to determine the outcome of the call. If bzerror is BZ_OK, the call completed successfully, and only then should the return value of the function (if any) be consulted. If bzerror is BZ_IO_ERROR, there was an error reading/writing the underlying compressed file, and you should then consult errno / perror to determine the cause of the difficulty. bzerror may also be set to various other values; precise details are given on a per-function basis below.

2. If bzerror indicates an error (ie, anything except BZ_OK and BZ_STREAM_END), you should immediately call BZ2_bzReadClose (or BZ2_bzWriteClose, depending on whether you are attempting to read or to write) to free up all resources associated with the stream. Once an error has been indicated, behaviour of all calls except BZ2_bzReadClose / BZ2_bzWriteClose is undefined. The implication is that

   • bzerror should be checked after each call, and

   • if bzerror indicates an error, BZ2_bzReadClose / BZ2_bzWriteClose should then be called to clean up.

3. The FILE* arguments passed to BZ2_bzReadOpen / BZ2_bzWriteOpen should be set to binary mode. Most Unix systems will do this by default, but other platforms, including Windows and Mac, will not. If you omit this, you may encounter problems when moving code to new platforms.

4. Memory allocation requests are handled by malloc / free. At present there is no facility for user-defined memory allocators in the file I/O functions (could easily be added, though).

BZFILE *BZ2_bzReadOpen(int *bzerror, FILE *f, int verbosity, int small, void *unused, int nUnused)

Prepare to read compressed data from file handle f.

Parameters	Direction	Description
bzerror	out	It should be consulted first to determine the outcome of the call. If bzerror is BZ_OK, the call completed successfully, and only then should the return value of the function (if any) be consulted.
f	in	Refers to a file which has been opened for reading, and for which the error indicator (ferror(f)) is not set.
verbosity	in	A number between 0 and 4 inclusive. 0 is silent, and greater numbers give increasingly verbose monitoring/debugging output.
small	in	If small is 1, the library will try to decompress using less memory, at the expense of speed.
unused	in,out	Points to data that will be decompressed by BZ2_bzRead before starting to read from the file f.
nUnused	in,out	Number of bytes to be decompressed by BZ2_bzRead starting at unused.

Note

1. Possible assignments to bzerror:

   • BZ_CONFIG_ERROR - If the library has been mis-compiled

   • BZ_PARAM_ERROR - If

     • f is NULL

     • or small is neither 0 nor 1

     • or ( unused == NULL && nUnused != 0 )

     • or ( unused != NULL && !(0 <= nUnused <= BZ_MAX_UNUSED) )

   • BZ_IO_ERROR - If ferror(f) is nonzero

   • BZ_MEM_ERROR - If available memory is insufficient.

   • BZ_OK - otherwise.

2. BZ2_bzRead will decompress the nUnused bytes starting at unused, before starting to read from the file f. At most BZ_MAX_UNUSED bytes may be supplied like this. If this facility is not required, you should pass NULL and 0 for unused and nUnused respectively.

3. The amount of memory needed to decompress a file cannot be determined until the file’s header has been read. So it is possible that BZ2_bzReadOpen returns BZ_OK but a subsequent call of BZ2_bzRead will return BZ_MEM_ERROR.

Returns:

Result	Description
Success	Pointer to an abstract BZFILE, if bzerror is BZ_OK
Fail	NULL

void BZ2_bzReadClose(int *bzerror, BZFILE *b)

Releases all memory pertaining to the compressed file b.

Parameters	Direction	Description
bzerror	out	It should be consulted first to determine the outcome of the call. If bzerror is BZ_OK, the call completed successfully, and only then should the return value of the function (if any) be consulted.
b	in,out	Refers to the compressed file.

Note

1. Possible assignments to bzerror:

   • BZ_SEQUENCE_ERROR - If b was opened with BZ2_bzOpenWrite

   • BZ_OK - otherwise

2. BZ2_bzReadClose does not call fclose on the underlying file handle, so you should do that yourself if appropriate.

3. BZ2_bzReadClose should be called to clean up after all error situations.

Returns:

void

void BZ2_bzReadGetUnused(int *bzerror, BZFILE *b, void **unused, int *nUnused)

Returns data which was read from the compressed file but was not needed to get to the logical end-of-stream.

Parameters	Direction	Description
bzerror	out	It should be consulted first to determine the outcome of the call. If bzerror is BZ_OK, the call completed successfully, and only then should the return value of the function (if any) be consulted.
b	in	Refers to the compressed file.
unused	in,out	*unused is set to the address of the data.
nUnused	in,out	*nUnused is set to the number of bytes. It is a value between 0 and BZ_MAX_UNUSED inclusive.

Note

1. Possible assignments to bzerror:

   • BZ_PARAM_ERROR - If

     • b is NULL or

     • unused is NULL or nUnused is NULL

   • BZ_SEQUENCE_ERROR - If

     • BZ_STREAM_END has not been signalled or

     • b was opened with BZ2_bzWriteOpen

   • BZ_OK - otherwise

2. This function may only be called once BZ2_bzRead has signalled BZ_STREAM_END but before BZ2_bzReadClose.

Returns:

void

int BZ2_bzRead(int *bzerror, BZFILE *b, void *buf, int len)

Reads up to len (uncompressed) bytes from the compressed file b into the buffer buf.

Parameters	Direction	Description
bzerror	out	It should be consulted first to determine the outcome of the call. If bzerror is BZ_OK, the call completed successfully, and only then should the return value of the function (if any) be consulted.
b	in,out	Refers to the compressed file.
buf	in,out	Buffer into which len (uncompressed) bytes is read into.
len	in	Integer variable indicating length.

Note

1. Possible assignments to bzerror:

   • BZ_PARAM_ERROR - If b is NULL or buf is NULL or len < 0

   • BZ_SEQUENCE_ERROR - If b was opened with BZ2_bzWriteOpen

   • BZ_IO_ERROR - If there is an error reading from the compressed file

   • BZ_UNEXPECTED_EOF - If the compressed file ended before the logical end-of-stream was detected

   • BZ_DATA_ERROR - If a data integrity error was detected in the compressed stream

   • BZ_DATA_ERROR_MAGIC - If the stream does not begin with the requisite header bytes (ie, is not a bzip2 data file). This is really a special case of BZ_DATA_ERROR.

   • BZ_MEM_ERROR - If available memory is insufficient.

   • BZ_STREAM_END - If the logical end of stream was detected.

   • BZ_OK - otherwise.

2. If the read was successful, bzerror is set to BZ_OK and the number of bytes read is returned. If the logical end-of-stream was detected, bzerror will be set to BZ_STREAM_END, and the number of bytes read is returned. All other bzerror values denote an error.

3. BZ2_bzRead will supply len bytes, unless the logical stream end is detected or an error occurs. Because of this, it is possible to detect the stream end by observing when the number of bytes returned is less than the number requested. Nevertheless, this is regarded as inadvisable; you should instead check bzerror after every call and watch out for BZ_STREAM_END.

4. Internally, BZ2_bzRead copies data from the compressed file in chunks of size BZ_MAX_UNUSED bytes before decompressing it. If the file contains more bytes than strictly needed to reach the logical end-of-stream, BZ2_bzRead will almost certainly read some of the trailing data before signalling BZ_SEQUENCE_END. To collect the read but unused data onceBZ_SEQUENCE_END has appeared, call BZ2_bzReadGetUnused immediately before BZ2_bzReadClose.

Returns:

Result	Description
Success	number of bytes read , if bzerror is BZ_OK or BZ_STREAM_END
Fail	undefined

BZFILE *BZ2_bzWriteOpen(int *bzerror, FILE *f, int blockSize100k, int verbosity, int workFactor)

Prepare to write compressed data to file handle f.

Parameters	Direction	Description
bzerror	out	It should be consulted first to determine the outcome of the call. If bzerror is BZ_OK, the call completed successfully, and only then should the return value of the function (if any) be consulted.
f	in	Refers to a file which has been opened for writing, and for which the error indicator (ferror(f)) is not set.
blockSize100k	in	Specifies the block size to be used for compression. It should be a value between 1 and 9 inclusive, and the actual block size used is 100000 x this figure.
verbosity	in	A number between 0 and 4 inclusive. 0 is silent, and greater numbers give increasingly verbose monitoring/debugging output.
workFactor	in	Controls how the compression phase behaves when presented with worst case, highly repetitive, input data.

Note

1. Possible assignments to bzerror:

   • BZ_CONFIG_ERROR - If the library has been mis-compiled

   • BZ_PARAM_ERROR - If

     • f is NULL or

     • blockSize100k < 1 or blockSize100k > 9

   • BZ_IO_ERROR - If ferror(f) is nonzero

   • BZ_MEM_ERROR - If available memory is insufficient

   • BZ_OK - otherwise

2. All required memory is allocated at this stage, so if the call completes successfully, BZ_MEM_ERROR cannot be signalled by a subsequent call to BZ2_bzWrite.

Returns:

Result	Description
Success	Pointer to an abstract BZFILE, if bzerror is BZ_OK
Fail	NULL

void BZ2_bzWrite(int *bzerror, BZFILE *b, void *buf, int len)

Absorbs len bytes from the buffer buf, eventually to be compressed and written to the file.

Parameters	Direction	Description
bzerror	out	It should be consulted first to determine the outcome of the call. If bzerror is BZ_OK, the call completed successfully, and only then should the return value of the function (if any) be consulted.
b	in,out	Refers to the file into which compressed data will be written.
buf	in	Buffer that consists the data to be compressed.
len	in	Integer variable indicating length.

Note

1. Possible assignments to bzerror:

   • BZ_PARAM_ERROR - If b is NULL or buf is NULL or len < 0

   • BZ_SEQUENCE_ERROR - If b was opened with BZ2_bzReadOpen

   • BZ_IO_ERROR - If there is an error writing the compressed file.

   • BZ_OK - otherwise

Returns:

void

void BZ2_bzWriteClose(int *bzerror, BZFILE *b, int abandon, unsigned int *nbytes_in, unsigned int *nbytes_out)

Compresses and flushes to the compressed file all data so far supplied by BZ2_bzWrite.

Parameters	Direction	Description
bzerror	out	It should be consulted first to determine the outcome of the call. If bzerror is BZ_OK, the call completed successfully, and only then should the return value of the function (if any) be consulted.
b	in,out	Refers to the file into which compressed data will be written.
abandon	in	In case of no error, in order to attempt to complete the compression operation, or to fflush the compressed file, pass a nonzero value to abandon.
nbytes_in	in,out	If nbytes_in is non-null, *nbytes_in will be set to be the total volume of uncompressed data handled.
nbytes_out	in,out	If nbytes_out is non-null, *nbytes_out will be set to the total volume of compressed data written.

Note

1. Possible assignments to bzerror:

   • BZ_SEQUENCE_ERROR - If b was opened with BZ2_bzReadOpen

   • BZ_IO_ERROR - If there is an error writing the compressed file

   • BZ_OK - otherwise

2. The logical end-of-stream markers are also written, so subsequent calls to BZ2_bzWrite are illegal. All memory associated with the compressed file b is released. fflush is called on the compressed file, but it is not fclose’d.

3. If BZ2_bzWriteClose is called to clean up after an error, the only action is to release the memory. The library records the error codes issued by previous calls, so this situation will be detected automatically.

   There is no attempt to complete the compression operation, nor to

   fflush the compressed file. You can force this behaviour to happen even in the case of no error, by passing a nonzero value to abandon.

Returns:

void

void BZ2_bzWriteClose64(int *bzerror, BZFILE *b, int abandon, unsigned int *nbytes_in_lo32, unsigned int *nbytes_in_hi32, unsigned int *nbytes_out_lo32, unsigned int *nbytes_out_hi32)

Compresses and flushes to the compressed file all data so far supplied by BZ2_bzWrite.

Note

For compatibility with older versions of the library, BZ2_bzWriteClose() only yields the lower 32 bits of these counts. Use BZ2_bzWriteClose64() if you want the full 64 bit counts. These two functions are otherwise absolutely identical.

Utility functions

int BZ2_bzBuffToBuffCompress(char *dest, unsigned int *destLen, char *source, unsigned int sourceLen, int blockSize100k, int verbosity, int workFactor)

Attempts to compress the data in source into the destination buffer, dest.

Parameters	Direction	Description
dest	out	Destination buffer, compressed data is kept here, memory should be allocated already.
destLen	in,out	Size of buffer dest (which must be already allocated).
source	in	Source buffer, the data to be compressed is copied/or pointed here.
sourceLen	in	Size of buffer source.
blockSize100k	in	Specifies the block size to be used for compression. It should be a value between 1 and 9 inclusive, and the actual block size used is 100000 x this figure.
verbosity	in	A number between 0 and 4 inclusive. 0 is silent, and greater numbers give increasingly verbose monitoring/debugging output.
workFactor	in	Controls how the compression phase behaves when presented with worst case, highly repetitive, input data.

Note

1. If the destination buffer is big enough, *destLen is set to the size of the compressed data, and BZ_OK is returned. If the compressed data won’t fit, *destLen is unchanged, and BZ_OUTBUFF_FULL is returned.

2. To guarantee that the compressed data will fit in its buffer, allocate an output buffer of size 1% larger than the uncompressed data, plus six hundred extra bytes.

3. blockSize100k = 9 gives the best compression but takes most memory.

4. If compression runs into difficulties caused by repetitive data, the library switches from the standard sorting algorithm to a fallback algorithm . The fallback is slower than the standard algorithm by perhaps a factor of three, but always behaves reasonably, no matter how bad the input.

5. Lower values of workFactor reduce the amount of effort the standard algorithm will expend before resorting to the fallback. Set this parameter carefully;

   • too low, and many inputs will be handled by the fallback algorithm and so compress rather slowly,

   • too high, and your average-to-worst case compression times can become very large.

   • The default value of 30

     gives reasonable behaviour over a wide range of circumstances.

     Allowable values range from

     0 to 250 inclusive. 0 is a special case, equivalent to using the default value of 30.

6. Compression is a one-shot event, done with a single call to this function. The resulting compressed data is a complete bzip2 format data stream. There is no mechanism for making additional calls to provide extra input data. If you want that kind of mechanism, use the low-level interface.

Returns:

Result	Description
Success	BZ_OK
Fail	BZ_CONFIG_ERROR - If the library has been mis-compiled
	BZ_PARAM_ERROR If dest is NULL or destLen is NULL or blockSize100k < 1 or blockSize100k > 9 or verbosity < 0 or verbosity > 4 or workFactor < 0 or workFactor > 250
	BZ_MEM_ERROR - If available memory is insufficient
	BZ_OUTBUFF_FULL - If the size of the compressed data exceeds *destLen

int BZ2_bzBuffToBuffDecompress(char *dest, unsigned int *destLen, char *source, unsigned int sourceLen, int small, int verbosity)

Attempts to decompress the data in source into the destination buffer, dest.

Parameters	Direction	Description
dest	out	This is the destination buffer, the data is decompressed to this buffer.
destLen	in,out	Size of buffer dest (which must be already allocated).
source	in	Source buffer, the data to be decompressed is pointed here.
sourceLen	in	Size of buffer source.
small	in	If small is nonzero , the library will use an alternative decompression algorithm which uses less memory but at the cost of decompressing more slowly.
verbosity	in	A number between 0 and 4 inclusive. 0 is silent, and greater numbers give increasingly verbose monitoring/debugging output.

Note

1. If the destination buffer is big enough, *destLen is set to the size of the uncompressed data, and BZ_OK is returned. If the uncompressed data won’t fit, *destLen is unchanged, and BZ_OUTBUFF_FULL is returned.

2. source is assumed to hold a complete bzip2 format data stream. BZ2_bzBuffToBuffDecompress tries to decompress the entirety of the stream into the output buffer.

3. BZ2_bzBuffToBuffDecompress will not write data at or beyond dest[*destLen], even in case of buffer overflow.

Returns:

Result	Description
Success	BZ_OK
Fail	BZ_CONFIG_ERROR - If the library has been mis-compiled
	BZ_PARAM_ERROR if dest is NULL or destLen is NULL or small != 0 && small != 1 or verbosity < 0 or verbosity > 4
	BZ_MEM_ERROR - If available memory is insufficient.
	BZ_OUTBUFF_FULL - If the size of the uncompressed data exceeds *destLen
	BZ_DATA_ERROR - If a data integrity error was detected in the compressed data
	BZ_DATA_ERROR_MAGIC - If the compressed data doesn’t begin with the right magic bytes
	BZ_UNEXPECTED_EOF - If the compressed data ends unexpectedly

struct bz_stream

#include <bzlib.h>

Note

The fields of bz_stream comprise the entirety of the user-visible data.

Public Members

unsigned int avail_in

Indicates the number of bytes the library may read.

unsigned int avail_out

Indicates the available output space.

void *(*bzalloc)(void*, int, int)

Custom memory allocator. The call bzalloc ( opaque, n, m ) is expected to return a pointer p to n * m bytes of memory

void (*bzfree)(void*, void*)

bzfree ( opaque, p ) is expected to free the memory allocated using bzalloc.

char *next_in

Points to the data to be compressed when called during compression,

whereas when called during decompression, it points to compressed data.

char *next_out

Points to a buffer in which the compressed data is to be placed when called during compression,

whereas when called during decompression, it points to a buffer in which the uncompressed output is to be placed

void *opaque

The value opaque is passed to as the first argument to all calls to bzalloc and bzfree, but is otherwise ignored by the library.

void *state

A pointer, pointing to the private data structures.

unsigned int total_in_hi32

Used to store upper 32 bits of the total number of input bytes processed.

unsigned int total_in_lo32

Used to store lower 32 bits of the total number of input bytes processed.

unsigned int total_out_hi32

Used to store upper 32 bits of the total number of output bytes processed.

unsigned int total_out_lo32

Used to store lower 32 bits of the total number of output bytes processed.