### BZ2_bzCompressInit allowable next actions

Source: https://sourceware.org/bzip2/manual/manual.html

Lists the allowable next actions after BZ2_bzCompressInit. If BZ_OK is returned, the next step is to call BZ2_bzCompress; on error, no specific action is needed.

```text
BZ2_bzCompress
  if BZ_OK is returned
  no specific action needed in case of error
```

--------------------------------

### Insufficient bug report example

Source: https://sourceware.org/bzip2/manual/manual.html

A minimal bug report example that is insufficient because it lacks details. The manual emphasizes that such a report is useless and that facts are required.

```text
bzip2 crashed with segmentation fault on my machine
```

--------------------------------

### BZ2_bzCompressInit return values

Source: https://sourceware.org/bzip2/manual/manual.html

Lists the possible return values from BZ2_bzCompressInit. BZ_CONFIG_ERROR indicates a mis-compiled library, BZ_PARAM_ERROR indicates invalid parameters, BZ_MEM_ERROR indicates insufficient memory, and BZ_OK indicates success.

```text
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 not enough memory is available
BZ_OK 
  otherwise
```

--------------------------------

### BZ2_bzReadOpen allowable next actions

Source: https://sourceware.org/bzip2/manual/manual.html

Lists the allowable next actions after BZ2_bzReadOpen. If bzerror is BZ_OK, you may call BZ2_bzRead; otherwise you should call BZ2_bzClose to clean up. This ensures proper resource management after the open call.

```text
BZ2_bzRead
  if bzerror is BZ_OK
BZ2_bzClose
  otherwise
```

--------------------------------

### BZ2_bzWriteOpen

Source: https://sourceware.org/bzip2/manual/manual.html

Initializes a compressed file handle for writing. Allocates required memory and validates parameters.

```APIDOC
## BZ2_bzWriteOpen

### Description
Prepare to write compressed data to file handle `f`. `f` should refer to a file which has been opened for writing, and for which the error indicator (`ferror(f)`) is not set. For the meaning of parameters `blockSize100k`, `verbosity` and `workFactor`, see `BZ2_bzCompressInit`. 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`.

### Method
Function call

### Endpoint
`BZFILE *BZ2_bzWriteOpen( int *bzerror, FILE *f, int blockSize100k, int verbosity, int workFactor );`

### Parameters
- **bzerror** (int*) - Required - Pointer to an integer that will receive the error code.
- **f** (FILE*) - Required - File handle opened for writing.
- **blockSize100k** (int) - Required - Block size parameter (1-9).
- **verbosity** (int) - Required - Verbosity level.
- **workFactor** (int) - Required - Work factor parameter.

### Request Example
```c
int bzerror;
FILE *f = fopen("output.bz2", "wb");
BZFILE *b = BZ2_bzWriteOpen(&bzerror, f, 9, 0, 30);
```

### Response
#### Success Response (BZ_OK)
- **bzerror** (int) - Set to `BZ_OK`.
- **return** (BZFILE*) - Pointer to an abstract BZFILE.

#### Error Responses
- **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 insufficient memory is available.

#### Response Example
```c
// Example of successful open
BZFILE *b = BZ2_bzWriteOpen(&bzerror, f, 9, 0, 30);
if (bzerror == BZ_OK) {
    // use b for writing
}
```
```

--------------------------------

### BZ2_bzDecompress allowable next actions

Source: https://sourceware.org/bzip2/manual/manual.html

Shows the allowable next actions after BZ2_bzDecompress returns. If BZ_OK is returned, call BZ2_bzDecompress again; otherwise call BZ2_bzDecompressEnd.

```text
BZ2_bzDecompress
  if BZ_OK was returned
BZ2_bzDecompressEnd
  otherwise
```

--------------------------------

### BZ2_bzCompressInit

Source: https://sourceware.org/bzip2/manual/manual.html

Prepares for compression. The `bz_stream` structure holds all data pertaining to the compression activity. A `bz_stream` structure should be allocated and initialised prior to the call.

```APIDOC
## BZ2_bzCompressInit

### Description
Prepares for compression. The `bz_stream` structure holds all data pertaining to the compression activity. A `bz_stream` structure should be allocated and initialised prior to the call.

### Method
C function

### Endpoint
BZ2_bzCompressInit

### Parameters
#### Parameters
- **strm** (bz_stream*) - Required - Pointer to the `bz_stream` structure to be initialised.
- **blockSize100k** (int) - Required - Block size to be used for compression, between 1 and 9 inclusive. Actual block size is 100000 x this figure.
- **verbosity** (int) - Required - Verbosity level between 0 and 4 inclusive. 0 is silent, greater numbers give increasingly verbose output.
- **workFactor** (int) - Required - Controls compression behaviour with repetitive data. Allowable values range from 0 to 250 inclusive. 0 is equivalent to the default value of 30.

### Request Example
```c
bz_stream strm;
strm.bzalloc = NULL;
strm.bzfree = NULL;
strm.opaque = NULL;
int ret = BZ2_bzCompressInit(&strm, 9, 0, 30);
```

### Response
#### Success Response (BZ_OK)
- **BZ_OK** - The function succeeded.

#### Error Responses
- **BZ_CONFIG_ERROR** - The library has been mis-compiled.
- **BZ_PARAM_ERROR** - If `strm` is NULL, or `blockSize` < 1 or > 9, or `verbosity` < 0 or > 4, or `workFactor` < 0 or > 250.
- **BZ_MEM_ERROR** - Not enough memory is available.

#### Response Example
```c
int ret = BZ2_bzCompressInit(&strm, 9, 0, 30);
if (ret == BZ_OK) {
    // success
}
```
```

--------------------------------

### BZ2_bzBuffToBuffCompress return values

Source: https://sourceware.org/bzip2/manual/manual.html

Lists the possible return values for BZ2_bzBuffToBuffCompress. Use these constants to check the outcome of the compression call; BZ_OK indicates success, while the others indicate specific error conditions such as invalid parameters, memory failure, or buffer overflow.

```text
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 insufficient memory is available 
BZ_OUTBUFF_FULL
  if the size of the compressed 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
BZ_OK
  otherwise
```

--------------------------------

### BZ2_bzReadOpen return values

Source: https://sourceware.org/bzip2/manual/manual.html

Shows the possible return values of BZ2_bzReadOpen. A pointer to an abstract BZFILE is returned when bzerror is BZ_OK; otherwise NULL is returned. This indicates whether the open operation succeeded.

```text
Pointer to an abstract BZFILE
  if bzerror is BZ_OK
NULL
  otherwise
```

--------------------------------

### BZ2_bzopen and BZ2_bzdopen declarations

Source: https://sourceware.org/bzip2/manual/manual.html

Declares BZ2_bzopen and BZ2_bzdopen, which open a .bz2 file for reading or writing using either its name or a pre-existing file descriptor. Analogous to fopen and fdopen.

```c
BZFILE * BZ2_bzopen  ( const char *path, const char *mode );
BZFILE * BZ2_bzdopen ( int        fd,    const char *mode );

```

--------------------------------

### BZ2_bzReadOpen function prototype

Source: https://sourceware.org/bzip2/manual/manual.html

Declares the BZ2_bzReadOpen function prototype. Use it to prepare for reading compressed data from a file handle. The function takes a pointer to an error code, a FILE* opened for reading, verbosity and small flags, and optional unused bytes. The small flag requests lower memory usage at the cost of speed. The unused parameter can supply up to BZ_MAX_UNUSED bytes that will be decompressed before reading from the file; pass NULL and 0 if not needed.

```c
typedef void BZFILE;

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

--------------------------------

### BZ2_bzReadOpen

Source: https://sourceware.org/bzip2/manual/manual.html

Prepares to read compressed data from a file handle. It initializes the decompression stream and returns an abstract BZFILE pointer for subsequent read operations.

```APIDOC
## BZ2_bzReadOpen

### Description
Prepares to read compressed data from a file handle. It initializes the decompression stream and returns an abstract BZFILE pointer for subsequent read operations.

### Method
Function call

### Endpoint
BZ2_bzReadOpen

### Parameters
#### Function Parameters
- **bzerror** (int*) - Required - Pointer to an integer that receives the error code after the call.
- **f** (FILE*) - Required - File handle opened for reading, with error indicator not set.
- **verbosity** (int) - Required - Controls the amount of informational output (see BZ2_bzDecompressInit).
- **small** (int) - Required - If 1, uses less memory at the expense of speed.
- **unused** (void*) - Optional - Pointer to bytes to be decompressed before reading from file; pass NULL if not used.
- **nUnused** (int) - Required - Number of bytes in unused; must be 0 if unused is NULL, otherwise between 0 and BZ_MAX_UNUSED.

### Request Example
```c
int bzerror;
FILE *f = fopen("file.bz2", "rb");
BZFILE *bz = BZ2_bzReadOpen(&bzerror, f, 0, 0, NULL, 0);
```

### Response
#### Success Response (BZ_OK)
- **return** (BZFILE*) - Pointer to an abstract BZFILE for reading.

#### Error Responses
- **BZ_CONFIG_ERROR** - Library mis-compiled.
- **BZ_PARAM_ERROR** - Invalid parameters (e.g., f NULL, small not 0/1, unused/nUnused mismatch).
- **BZ_IO_ERROR** - ferror(f) is nonzero.
- **BZ_MEM_ERROR** - Insufficient memory.

#### Response Example
```c
BZFILE *bz = BZ2_bzReadOpen(&bzerror, f, 0, 0, NULL, 0);
if (bzerror == BZ_OK) {
    // proceed with BZ2_bzRead
} else {
    // handle error
}
```

### Allowable Next Actions
- **BZ2_bzRead** - if bzerror is BZ_OK
- **BZ2_bzClose** - otherwise
```

--------------------------------

### BZ2_bzDecompressEnd return values

Source: https://sourceware.org/bzip2/manual/manual.html

Lists the possible return values of BZ2_bzDecompressEnd. BZ_PARAM_ERROR occurs if strm is NULL or strm->s is NULL; otherwise BZ_OK is returned.

```text
BZ_PARAM_ERROR
  if strm is NULL or strm->s is NULL
BZ_OK
  otherwise
```

--------------------------------

### BZ2_bzBuffToBuffCompress: one-shot buffer compression

Source: https://sourceware.org/bzip2/manual/manual.html

Compresses a complete buffer of data into a bzip2 stream in one call. Requires an output buffer large enough to hold the compressed data; allocate 1% larger than the uncompressed data plus 600 extra bytes to guarantee success. Returns BZ_OK on success, BZ_OUTBUFF_FULL if the buffer is too small, or BZ_PARAM_ERROR, BZ_MEM_ERROR, or BZ_CONFIG_ERROR on failure.

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

--------------------------------

### BZ2_bzReadOpen possible bzerror values

Source: https://sourceware.org/bzip2/manual/manual.html

Lists the possible values that bzerror can be set to after a call to BZ2_bzReadOpen. BZ_CONFIG_ERROR indicates a mis-compiled library, BZ_PARAM_ERROR indicates invalid parameters, BZ_IO_ERROR indicates a file error, BZ_MEM_ERROR indicates insufficient memory, and BZ_OK indicates success. Check bzerror before using the return value.

```text
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 insufficient memory is available
BZ_OK
  otherwise.
```

--------------------------------

### Standard bzip2 file writing and reading with BZ2_bzWrite* and BZ2_bzRead*

Source: https://sourceware.org/bzip2/manual/manual.html

Use these two C code blocks together to perform standard bzip2 compression and decompression with the BZ2_bzWrite* and BZ2_bzRead* APIs. The first block writes data to a compressed file using BZ2_bzWriteOpen with block size 9, BZ2_bzWrite, and BZ2_bzWriteClose; the second reads from a compressed file using BZ2_bzReadOpen, BZ2_bzRead, and BZ2_bzReadClose. Both require handling BZ_OK, BZ_IO_ERROR, and BZ_STREAM_END error codes as shown.

```c
FILE*   f;
BZFILE* b;
int     nBuf;
char    buf[ /* whatever size you like */ ];
int     bzerror;
int     nWritten;

f = fopen ( "myfile.bz2", "w" );
if ( !f ) {
 /* handle error */
}
b = BZ2_bzWriteOpen( &bzerror, f, 9 );
if (bzerror != BZ_OK) {
 BZ2_bzWriteClose ( b );
 /* handle error */
}

while ( /* condition */ ) {
 /* get data to write into buf, and set nBuf appropriately */
 nWritten = BZ2_bzWrite ( &bzerror, b, buf, nBuf );
 if (bzerror == BZ_IO_ERROR) { 
   BZ2_bzWriteClose ( &bzerror, b );
   /* handle error */
 }
}

BZ2_bzWriteClose( &bzerror, b );
if (bzerror == BZ_IO_ERROR) {
 /* handle error */
}
```

```c
FILE*   f;
BZFILE* b;
int     nBuf;
char    buf[ /* whatever size you like */ ];
int     bzerror;
int     nWritten;

f = fopen ( "myfile.bz2", "r" );
if ( !f ) {
  /* handle error */
}
b = BZ2_bzReadOpen ( &bzerror, f, 0, NULL, 0 );
if ( bzerror != BZ_OK ) {
  BZ2_bzReadClose ( &bzerror, b );
  /* handle error */
}

bzerror = BZ_OK;
while ( bzerror == BZ_OK && /* arbitrary other conditions */) {
  nBuf = BZ2_bzRead ( &bzerror, b, buf, /* size of buf */ );
  if ( bzerror == BZ_OK ) {
    /* do something with buf[0 .. nBuf-1] */
  }
}
if ( bzerror != BZ_STREAM_END ) {
   BZ2_bzReadClose ( &bzerror, b );
   /* handle error */
} else {
   BZ2_bzReadClose ( &bzerror, b );
}
```

--------------------------------

### BZ2_bzCompressInit: bz_stream structure and function declaration

Source: https://sourceware.org/bzip2/manual/manual.html

Declares the bz_stream structure and the BZ2_bzCompressInit function. The structure holds all user-visible data for compression, including input/output pointers, counts, and optional custom memory allocator callbacks. BZ2_bzCompressInit prepares for compression and initializes the internal state.

```c
typedef struct {
  char *next_in;
  unsigned int avail_in;
  unsigned int total_in_lo32;
  unsigned int total_in_hi32;

  char *next_out;
  unsigned int avail_out;
  unsigned int total_out_lo32;
  unsigned int total_out_hi32;

  void *state;

  void *(*bzalloc)(void *,int,int);
  void (*bzfree)(void *,void *);
  void *opaque;
} bz_stream;

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

--------------------------------

### BZ2_bzWriteClose and BZ2_bzWriteClose64 declarations

Source: https://sourceware.org/bzip2/manual/manual.html

Declares the high-level write-close functions. They compress and flush all data supplied by BZ2_bzWrite, write end-of-stream markers, release memory, and fflush the compressed file without closing it. Passing a nonzero abandon forces cleanup without completing compression. BZ2_bzWriteClose64 provides full 64-bit byte counts; otherwise only lower 32 bits are returned. Possible bzerror values are BZ_SEQUENCE_ERROR (if b was opened with BZ2_bzReadOpen), BZ_IO_ERROR (on write error), and BZ_OK otherwise.

```c
void BZ2_bzWriteClose( int *bzerror, BZFILE* f,
                       int abandon,
                       unsigned int* nbytes_in,
                       unsigned int* nbytes_out );

void BZ2_bzWriteClose64( int *bzerror, BZFILE* f,
                         int abandon,
                         unsigned int* nbytes_in_lo32,
                         unsigned int* nbytes_in_hi32,
                         unsigned int* nbytes_out_lo32,
                         unsigned int* nbytes_out_hi32 );
```

--------------------------------

### Memory usage estimation formulas

Source: https://sourceware.org/bzip2/manual/manual.html

Formulas for estimating compression and decompression memory requirements in bytes. Compression uses 400k plus 8 times block size; decompression uses 100k plus 4 times block size, or 100k plus 2.5 times block size when using the -s option.

```text
Compression:   400k + ( 8 x block size )

Decompression: 100k + ( 4 x block size ), or
               100k + ( 2.5 x block size )
```

--------------------------------

### BZ2_bzCompress

Source: https://sourceware.org/bzip2/manual/manual.html

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.

```APIDOC
## BZ2_bzCompress

### Description
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.

### Method
C function

### Endpoint
BZ2_bzCompress

### Parameters
#### Parameters
- **strm** (bz_stream*) - Required - Pointer to the `bz_stream` structure.
- **action** (int) - Required - Action to be performed. The action can be `BZ_RUN`, `BZ_FLUSH`, or `BZ_FINISH`.

### Request Example
```c
strm.next_in = input_data;
strm.avail_in = input_size;
strm.next_out = output_buffer;
strm.avail_out = output_size;
int ret = BZ2_bzCompress(&strm, BZ_RUN);
```

### Response
#### Success Response (BZ_OK)
- **BZ_OK** - The function succeeded.

#### Error Responses
- **BZ_SEQUENCE_ERROR** - The function was called in an invalid sequence.
- **BZ_PARAM_ERROR** - If `strm` is NULL or `action` is invalid.

#### Response Example
```c
int ret = BZ2_bzCompress(&strm, BZ_RUN);
if (ret == BZ_OK) {
    // success
}
```
```

--------------------------------

### BZ2_bzWriteClose64

Source: https://sourceware.org/bzip2/manual/manual.html

Compresses and flushes to the compressed file all data so far supplied by BZ2_bzWrite. 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. This variant provides full 64-bit counts.

```APIDOC
## BZ2_bzWriteClose64

### Description
Compresses and flushes to the compressed file all data so far supplied by BZ2_bzWrite. 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. This variant provides full 64-bit counts.

### Method
Function call

### Endpoint
BZ2_bzWriteClose64

### Parameters
- **bzerror** (int*) - Output - Error code
- **f** (BZFILE*) - Input - The BZFILE handle
- **abandon** (int) - Input - If nonzero, forces cleanup without completing compression
- **nbytes_in_lo32** (unsigned int*) - Output - Lower 32 bits of total uncompressed data handled
- **nbytes_in_hi32** (unsigned int*) - Output - Upper 32 bits of total uncompressed data handled
- **nbytes_out_lo32** (unsigned int*) - Output - Lower 32 bits of total compressed data written
- **nbytes_out_hi32** (unsigned int*) - Output - Upper 32 bits of total compressed data written

### Response
#### Error Codes
- **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
```

--------------------------------

### BZ2_bzDecompressEnd allowable next actions

Source: https://sourceware.org/bzip2/manual/manual.html

States that after BZ2_bzDecompressEnd returns, no further actions are allowed on the decompression stream.

```text
  None.
```

--------------------------------

### BZ2_bzread and BZ2_bzwrite declarations

Source: https://sourceware.org/bzip2/manual/manual.html

Declares BZ2_bzread and BZ2_bzwrite, which read/write data from/to a previously opened BZFILE. Analogous to fread and fwrite.

```c
int BZ2_bzread  ( BZFILE* b, void* buf, int len );
int BZ2_bzwrite ( BZFILE* b, void* buf, int len );

```

--------------------------------

### BZ2_bzflush and BZ2_bzclose declarations

Source: https://sourceware.org/bzip2/manual/manual.html

Declares BZ2_bzflush and BZ2_bzclose, which flush/close a BZFILE. BZ2_bzflush doesn't actually do anything. Analogous to fflush and fclose.

```c
int  BZ2_bzflush ( BZFILE* b );
void BZ2_bzclose ( BZFILE* b );

```