manual.texi

bzip2是一个免费的

         if the compressed file ended before the logical end-of-stream was detected
      @code{BZ_DATA_ERROR} 
         if a data integrity error was detected in the compressed stream
      @code{BZ_DATA_ERROR_MAGIC}
         if the stream does not begin with the requisite header bytes (ie, is not 
         a @code{bzip2} data file).  This is really a special case of @code{BZ_DATA_ERROR}.
      @code{BZ_MEM_ERROR} 
         if insufficient memory was available
      @code{BZ_STREAM_END} 
         if the logical end of stream was detected.
      @code{BZ_OK}
         otherwise.
@end display

Possible return values:
@display
      number of bytes read
         if @code{bzerror} is @code{BZ_OK} or @code{BZ_STREAM_END}
      undefined
         otherwise
@end display

Allowable next actions:
@display
      collect data from @code{buf}, then @code{BZ2_bzRead} or @code{BZ2_bzReadClose}
         if @code{bzerror} is @code{BZ_OK} 
      collect data from @code{buf}, then @code{BZ2_bzReadClose} or @code{BZ2_bzReadGetUnused} 
         if @code{bzerror} is @code{BZ_SEQUENCE_END}   
      @code{BZ2_bzReadClose} 
         otherwise
@end display



@subsection @code{BZ2_bzReadGetUnused}
@example
   void BZ2_bzReadGetUnused ( int* bzerror, BZFILE *b, 
                              void** unused, int* nUnused );
@end example
Returns data which was read from the compressed file but was not needed
to get to the logical end-of-stream.  @code{*unused} is set to the address
of the data, and @code{*nUnused} to the number of bytes.  @code{*nUnused} will
be set to a value between @code{0} and @code{BZ_MAX_UNUSED} inclusive.

This function may only be called once @code{BZ2_bzRead} has signalled 
@code{BZ_STREAM_END} but before @code{BZ2_bzReadClose}.

Possible assignments to @code{bzerror}:
@display
      @code{BZ_PARAM_ERROR} 
         if @code{b} is @code{NULL} 
         or @code{unused} is @code{NULL} or @code{nUnused} is @code{NULL}
      @code{BZ_SEQUENCE_ERROR} 
         if @code{BZ_STREAM_END} has not been signalled
         or if @code{b} was opened with @code{BZ2_bzWriteOpen}
     @code{BZ_OK}
         otherwise
@end display

Allowable next actions:
@display 
      @code{BZ2_bzReadClose}
@end display


@subsection @code{BZ2_bzReadClose}
@example
   void BZ2_bzReadClose ( int *bzerror, BZFILE *b );
@end example
Releases all memory pertaining to the compressed file @code{b}.  
@code{BZ2_bzReadClose} does not call @code{fclose} on the underlying file
handle, so you should do that yourself if appropriate.
@code{BZ2_bzReadClose} should be called to clean up after all error
situations.

Possible assignments to @code{bzerror}:
@display
      @code{BZ_SEQUENCE_ERROR} 
         if @code{b} was opened with @code{BZ2_bzOpenWrite} 
      @code{BZ_OK} 
         otherwise
@end display

Allowable next actions:
@display
      none
@end display



@subsection @code{BZ2_bzWriteOpen}
@example
   BZFILE *BZ2_bzWriteOpen ( int *bzerror, FILE *f, 
                             int blockSize100k, int verbosity,
                             int workFactor );
@end example
Prepare to write compressed data to file handle @code{f}.  
@code{f} should refer to
a file which has been opened for writing, and for which the error
indicator (@code{ferror(f)})is not set.  

For the meaning of parameters @code{blockSize100k},
@code{verbosity} and @code{workFactor}, see
@* @code{BZ2_bzCompressInit}.

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

Possible assignments to @code{bzerror}:
@display 
      @code{BZ_CONFIG_ERROR}
         if the library has been mis-compiled
      @code{BZ_PARAM_ERROR} 
         if @code{f} is @code{NULL} 
         or @code{blockSize100k < 1} or @code{blockSize100k > 9}
      @code{BZ_IO_ERROR} 
         if @code{ferror(f)} is nonzero
      @code{BZ_MEM_ERROR} 
         if insufficient memory is available
      @code{BZ_OK} 
         otherwise
@end display

Possible return values:
@display
      Pointer to an abstract @code{BZFILE}  
         if @code{bzerror} is @code{BZ_OK}   
      @code{NULL} 
         otherwise
@end display

Allowable next actions:
@display
      @code{BZ2_bzWrite} 
         if @code{bzerror} is @code{BZ_OK} 
         (you could go directly to @code{BZ2_bzWriteClose}, but this would be pretty pointless)
      @code{BZ2_bzWriteClose} 
         otherwise
@end display



@subsection @code{BZ2_bzWrite}
@example
   void BZ2_bzWrite ( int *bzerror, BZFILE *b, void *buf, int len );
@end example
Absorbs @code{len} bytes from the buffer @code{buf}, eventually to be
compressed and written to the file.

Possible assignments to @code{bzerror}:
@display
      @code{BZ_PARAM_ERROR} 
         if @code{b} is @code{NULL} or @code{buf} is @code{NULL} or @code{len < 0}
      @code{BZ_SEQUENCE_ERROR} 
         if b was opened with @code{BZ2_bzReadOpen}
      @code{BZ_IO_ERROR} 
         if there is an error writing the compressed file.
      @code{BZ_OK} 
         otherwise
@end display




@subsection @code{BZ2_bzWriteClose}
@example
   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 );
@end example

Compresses and flushes to the compressed file all data so far supplied
by @code{BZ2_bzWrite}.  The logical end-of-stream markers are also written, so
subsequent calls to @code{BZ2_bzWrite} are illegal.  All memory associated 
with the compressed file @code{b} is released.  
@code{fflush} is called on the
compressed file, but it is not @code{fclose}'d.

If @code{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 @code{fflush} the compressed file.  You can force this
behaviour to happen even in the case of no error, by passing a nonzero
value to @code{abandon}.

If @code{nbytes_in} is non-null, @code{*nbytes_in} will be set to be the
total volume of uncompressed data handled.  Similarly, @code{nbytes_out}
will be set to the total volume of compressed data written.  For 
compatibility with older versions of the library, @code{BZ2_bzWriteClose}
only yields the lower 32 bits of these counts.  Use
@code{BZ2_bzWriteClose64} if you want the full 64 bit counts.  These
two functions are otherwise absolutely identical.


Possible assignments to @code{bzerror}:
@display
      @code{BZ_SEQUENCE_ERROR} 
         if @code{b} was opened with @code{BZ2_bzReadOpen}
      @code{BZ_IO_ERROR} 
         if there is an error writing the compressed file
      @code{BZ_OK} 
         otherwise
@end display

@subsection Handling embedded compressed data streams

The high-level library facilitates use of
@code{bzip2} data streams which form some part of a surrounding, larger
data stream.
@itemize @bullet
@item For writing, the library takes an open file handle, writes
compressed data to it, @code{fflush}es it but does not @code{fclose} it.
The calling application can write its own data before and after the
compressed data stream, using that same file handle.
@item Reading is more complex, and the facilities are not as general
as they could be since generality is hard to reconcile with efficiency.
@code{BZ2_bzRead} reads from the compressed file in blocks of size
@code{BZ_MAX_UNUSED} bytes, and in doing so probably will overshoot
the logical end of compressed stream.
To recover this data once decompression has
ended, call @code{BZ2_bzReadGetUnused} after the last call of @code{BZ2_bzRead}
(the one returning @code{BZ_STREAM_END}) but before calling
@code{BZ2_bzReadClose}.
@end itemize

This mechanism makes it easy to decompress multiple @code{bzip2}
streams placed end-to-end.  As the end of one stream, when @code{BZ2_bzRead}
returns @code{BZ_STREAM_END}, call @code{BZ2_bzReadGetUnused} to collect the
unused data (copy it into your own buffer somewhere).  
That data forms the start of the next compressed stream.
To start uncompressing that next stream, call @code{BZ2_bzReadOpen} again,
feeding in the unused data via the @code{unused}/@code{nUnused}
parameters.
Keep doing this until @code{BZ_STREAM_END} return coincides with the
physical end of file (@code{feof(f)}).  In this situation
@code{BZ2_bzReadGetUnused}
will of course return no data.

This should give some feel for how the high-level interface can be used.
If you require extra flexibility, you'll have to bite the bullet and get
to grips with the low-level interface.

@subsection Standard file-reading/writing code
Here's how you'd write data to a compressed file:
@example @code
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 */
@}
@end example
And to read from a compressed file:
@example
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 );
@}
@end example



@section Utility functions
@subsection @code{BZ2_bzBuffTo