What is checked, and when¶

Block CRCs, before the block's bytes¶

Every block's CRC is checked before any of that block's bytes are returned. A block whose CRC does not match returns none of its bytes: the error comes instead. The bytes returned before an error are exactly the stream's up to the bad block.

Stream CRCs, at the stream's end¶

Each stream's combined CRC is checked at the stream's end. The bytes of a stream's blocks are returned as each block is verified, before the stream's own CRC has been read. So a streaming caller has the whole stream verified only once a read reaches its end without an error: until then, what it has read is provisional.

In Python, BZ2Reader.verified turns true only when a read returns the end with every block's and stream's CRC matched.

Where an error was found¶

An error says where decoding failed: in Rust Error { kind, block, bit }, in Python the DecodeError message. That is which block, and the bit it starts at. A damaged bit can be found later than where it lies, since the input is only known to be wrong once something it encodes fails a check.

The error kinds (ErrorKind):

• the input: Empty, NotBz2, Truncated, TrailingData;
• each of libbzip2's block checks: BadBlockMagic, BadOrigPtr, NoSymbols, BadGroups, BadSelectors, BadSelector, BadCodeLength, BadHuffmanCode, SelectorOverrun, RunTooLong, BlockTooLong, RunUnfinished;
• BlockCrc and StreamCrc, with the stored and computed values;
• this decoder's refusals: Randomised, BlockTooLarge;
• Io (from a BzReader's source), RangeOvershoot, Cancelled, and Internal (a caught panic: a bug).

What is decoded, and what is refused¶

The format is libbzip2 1.0.8's, with every check it makes: bzip2 1.0 and later output. Four choices differ from it, and each has its own error: