bzip2

3.2. Error handling

The library is designed to recover cleanly in all situations, including the worst-case situation of decompressing random data. I'm not 100% sure that it can always do this, so you might want to add a signal handler to catch segmentation violations during decompression if you are feeling especially paranoid. I would be interested in hearing more about the robustness of the library to corrupted compressed data.

Version 1.0.3 more robust in this respect than any previous version. Investigations with Valgrind (a tool for detecting problems with memory management) indicate that, at least for the few files I tested, all single-bit errors in the decompressed data are caught properly, with no segmentation faults, no uses of uninitialised data, no out of range reads or writes, and no infinite looping in the decompressor. So it's certainly pretty robust, although I wouldn't claim it to be totally bombproof.

The file bzlib.h contains all definitions needed to use the library. In particular, you should definitely not include bzlib_private.h.

In bzlib.h, the various return values are defined. The following list is not intended as an exhaustive description of the circumstances in which a given value may be returned -- those descriptions are given later. Rather, it is intended to convey the rough meaning of each return value. The first five actions are normal and not intended to denote an error situation.

BZ_OK: The requested action was completed successfully.
BZ_RUN_OK, BZ_FLUSH_OK, BZ_FINISH_OK: In BZ2_bzCompress, the requested flush/finish/nothing-special action was completed successfully.
BZ_STREAM_END: Compression of data was completed, or the logical stream end was detected during decompression.

The following return values indicate an error of some kind.

BZ_CONFIG_ERROR: Indicates that the library has been improperly compiled on your platform -- a major configuration error. Specifically, it means that sizeof(char), sizeof(short) and sizeof(int) are not 1, 2 and 4 respectively, as they should be. Note that the library should still work properly on 64-bit platforms which follow the LP64 programming model -- that is, where sizeof(long) and sizeof(void*) are 8. Under LP64, sizeof(int) is still 4, so libbzip2, which doesn't use the long type, is OK.
BZ_SEQUENCE_ERROR: When using the library, it is important to call the functions in the correct sequence and with data structures (buffers etc) in the correct states. libbzip2 checks as much as it can to ensure this is happening, and returns BZ_SEQUENCE_ERROR if not. Code which complies precisely with the function semantics, as detailed below, should never receive this value; such an event denotes buggy code which you should investigate.
BZ_PARAM_ERROR: Returned when a parameter to a function call is out of range or otherwise manifestly incorrect. As with BZ_SEQUENCE_ERROR, this denotes a bug in the client code. The distinction between BZ_PARAM_ERROR and BZ_SEQUENCE_ERROR is a bit hazy, but still worth making.
BZ_MEM_ERROR: Returned when a request to allocate memory failed. Note that the quantity of memory needed to decompress a stream cannot be determined until the stream's header has been read. So BZ2_bzDecompress and BZ2_bzRead may return BZ_MEM_ERROR even though some of the compressed data has been read. The same is not true for compression; once BZ2_bzCompressInit or BZ2_bzWriteOpen have successfully completed, BZ_MEM_ERROR cannot occur.
BZ_DATA_ERROR: Returned when a data integrity error is detected during decompression. Most importantly, this means when stored and computed CRCs for the data do not match. This value is also returned upon detection of any other anomaly in the compressed data.
BZ_DATA_ERROR_MAGIC: As a special case of BZ_DATA_ERROR, it is sometimes useful to know when the compressed stream does not start with the correct magic bytes ('B' 'Z' 'h').
BZ_IO_ERROR: Returned by BZ2_bzRead and BZ2_bzWrite when there is an error reading or writing in the compressed file, and by BZ2_bzReadOpen and BZ2_bzWriteOpen for attempts to use a file for which the error indicator (viz, ferror(f)) is set. On receipt of BZ_IO_ERROR, the caller should consult errno and/or perror to acquire operating-system specific information about the problem.
BZ_UNEXPECTED_EOF: Returned by BZ2_bzRead when the compressed file finishes before the logical end of stream is detected.
BZ_OUTBUFF_FULL: Returned by BZ2_bzBuffToBuffCompress and BZ2_bzBuffToBuffDecompress to indicate that the output data will not fit into the output buffer provided.