manual.texi

高效率的一种通用压缩/解压程序

so even if @code{bzDecompressInit} succeeds, a subsequent
@code{bzDecompress} could fail with @code{BZ_MEM_ERROR}.

Possible return values:
@display
      @code{BZ_PARAM_ERROR}
         if @code{(small != 0 && small != 1)}
         or @code{(verbosity < 0 || verbosity > 4)}
      @code{BZ_MEM_ERROR}
         if insufficient memory is available
@end display

Allowable next actions:
@display
      @code{bzDecompress}
         if @code{BZ_OK} was returned
      no specific action required in case of error
@end display

 

@subsection @code{bzDecompress}
@example
int bzDecompress ( bz_stream *strm );
@end example
Provides more input and/out output buffer space for the library.  The
caller maintains input and output buffers, and uses @code{bzDecompress}
to transfer data between them.

Before each call to @code{bzDecompress}, @code{next_in} 
should point at the compressed data,
and @code{avail_in} should indicate how many bytes the library
may read.  @code{bzDecompress} updates @code{next_in}, @code{avail_in} 
and @code{total_in}
to reflect the number of bytes it has read.

Similarly, @code{next_out} should point to a buffer in which the uncompressed
output is to be placed, with @code{avail_out} indicating how much output space
is available.  @code{bzCompress} updates @code{next_out},
@code{avail_out} and @code{total_out} to reflect
the number of bytes output.

You may provide and remove as little or as much data as you like on
each call of @code{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.

Use of @code{bzDecompress} is simpler than @code{bzCompress}.

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

If case of an error return value, you should call @code{bzDecompressEnd}
to clean up and release memory.

Possible return values:
@display
      @code{BZ_PARAM_ERROR}
         if @code{strm} is @code{NULL} or @code{strm->s} is @code{NULL}
         or @code{strm->avail_out < 1}
      @code{BZ_DATA_ERROR}
         if a data integrity error is detected in the compressed stream
      @code{BZ_DATA_ERROR_MAGIC}
         if the compressed stream doesn't begin with the right magic bytes
      @code{BZ_MEM_ERROR}
         if there wasn't enough memory available
      @code{BZ_STREAM_END}
         if the logical end of the data stream was detected and all
         output in has been consumed, eg @code{s->avail_out > 0}
      @code{BZ_OK}
         otherwise
@end display
Allowable next actions:
@display
      @code{bzDecompress}
         if @code{BZ_OK} was returned
      @code{bzDecompressEnd}
         otherwise
@end display


@subsection @code{bzDecompressEnd}
@example
int bzDecompressEnd ( bz_stream *strm );
@end example
Releases all memory associated with a decompression stream.

Possible return values:
@display
      @code{BZ_PARAM_ERROR}
         if @code{strm} is @code{NULL} or @code{strm->s} is @code{NULL}
      @code{BZ_OK}
         otherwise
@end display

Allowable next actions:
@display
      None.
@end display


@section High-level interface

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

@itemize @bullet
@item All of the functions take an @code{int*} first argument,
  @code{bzerror}.
  After each call, @code{bzerror} should be consulted first to determine
  the outcome of the call.  If @code{bzerror} is @code{BZ_OK}, 
  the call completed
  successfully, and only then should the return value of the function
  (if any) be consulted.  If @code{bzerror} is @code{BZ_IO_ERROR}, 
  there was an error
  reading/writing the underlying compressed file, and you should
  then consult @code{errno}/@code{perror} to determine the 
  cause of the difficulty.
  @code{bzerror} may also be set to various other values; precise details are
  given on a per-function basis below.
@item If @code{bzerror} indicates an error 
  (ie, anything except @code{BZ_OK} and @code{BZ_STREAM_END}),
  you should immediately call @code{bzReadClose} (or @code{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 @code{bzReadClose} (@code{bzWriteClose}) is undefined.  
  The implication is that (1) @code{bzerror} should
  be checked after each call, and (2) if @code{bzerror} indicates an error, 
  @code{bzReadClose} (@code{bzWriteClose}) should then be called to clean up.
@item The @code{FILE*} arguments passed to
   @code{bzReadOpen}/@code{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.
@item Memory allocation requests are handled by
  @code{malloc}/@code{free}.  
  At present
  there is no facility for user-defined memory allocators in the file I/O
  functions (could easily be added, though).
@end itemize



@subsection @code{bzReadOpen}
@example
   typedef void BZFILE;

   BZFILE *bzReadOpen ( int *bzerror, FILE *f, 
                        int small, int verbosity,
                        void *unused, int nUnused );
@end example
Prepare to read compressed data from file handle @code{f}.  @code{f}
should refer to a file which has been opened for reading, and for which
the error indicator (@code{ferror(f)})is not set.  If @code{small} is 1,
the library will try to decompress using less memory, at the expense of
speed.

For reasons explained below, @code{bzRead} will decompress the
@code{nUnused} bytes starting at @code{unused}, before starting to read
from the file @code{f}.  At most @code{BZ_MAX_UNUSED} bytes may be
supplied like this.  If this facility is not required, you should pass
@code{NULL} and @code{0} for @code{unused} and n@code{Unused}
respectively.

For the meaning of parameters @code{small} and @code{verbosity},
see @code{bzDecompressInit}.

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
@code{bzReadOpen} returns @code{BZ_OK} but a subsequent call of
@code{bzRead} will return @code{BZ_MEM_ERROR}.

Possible assignments to @code{bzerror}:
@display
      @code{BZ_PARAM_ERROR}
         if @code{f} is @code{NULL} 
         or @code{small} is neither @code{0} nor @code{1}                 
         or @code{(unused == NULL && nUnused != 0)}
         or @code{(unused != NULL && !(0 <= nUnused <= BZ_MAX_UNUSED))}
      @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{bzRead}
         if @code{bzerror} is @code{BZ_OK}   
      @code{bzClose} 
         otherwise
@end display


@subsection @code{bzRead}
@example
   int bzRead ( int *bzerror, BZFILE *b, void *buf, int len );
@end example
Reads up to @code{len} (uncompressed) bytes from the compressed file 
@code{b} into
the buffer @code{buf}.  If the read was successful, 
@code{bzerror} is set to @code{BZ_OK}
and the number of bytes read is returned.  If the logical end-of-stream
was detected, @code{bzerror} will be set to @code{BZ_STREAM_END}, 
and the number
of bytes read is returned.  All other @code{bzerror} values denote an error.

@code{bzRead} will supply @code{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 @code{bzerror} after every call and watch out for
@code{BZ_STREAM_END}.

Internally, @code{bzRead} copies data from the compressed file in chunks
of size @code{BZ_MAX_UNUSED} bytes
before decompressing it.  If the file contains more bytes than strictly
needed to reach the logical end-of-stream, @code{bzRead} will almost certainly
read some of the trailing data before signalling @code{BZ_SEQUENCE_END}.
To collect the read but unused data once @code{BZ_SEQUENCE_END} has 
appeared, call @code{bzReadGetUnused} immediately before @code{bzReadClose}.

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 @code{b} was opened with @code{bzWriteOpen}
      @code{BZ_IO_ERROR} 
         if there is an error reading from the compressed file
      @code{BZ_UNEXPECTED_EOF} 
         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{bzRead} or @code{bzReadClose}
         if @code{bzerror} is @code{BZ_OK} 
      collect data from @code{buf}, then @code{bzReadClose} or @code{bzReadGetUnused} 
         if @code{bzerror} is @code{BZ_SEQUENCE_END}   
      @code{bzReadClose} 
         otherwise
@end display



@subsection @code{bzReadGetUnused}
@example
   void 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{bzRead} has signalled 
@code{BZ_STREAM_END} but before @code{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{bzWriteOpen}
     @code{BZ_OK}
         otherwise
@end display

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


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