manual.texi

bzip2是一个免费的

The following return values indicate an error of some kind.
@table @code
@item BZ_CONFIG_ERROR
Indicates that the library has been improperly compiled on your
platform -- a major configuration error.  Specifically, it means
that @code{sizeof(char)}, @code{sizeof(short)} and @code{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 @code{sizeof(long)}
and @code{sizeof(void*)} are 8.  Under LP64, @code{sizeof(int)} is
still 4, so @code{libbzip2}, which doesn't use the @code{long} type,
is OK.
@item 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.  @code{libbzip2} checks as much as it can to ensure this is
happening, and returns @code{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.
@item BZ_PARAM_ERROR
Returned when a parameter to a function call is out of range 
or otherwise manifestly incorrect.  As with @code{BZ_SEQUENCE_ERROR},
this denotes a bug in the client code.  The distinction between
@code{BZ_PARAM_ERROR} and @code{BZ_SEQUENCE_ERROR} is a bit hazy, but still worth
making.
@item 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 @code{BZ2_bzDecompress} and
@code{BZ2_bzRead} may return @code{BZ_MEM_ERROR} even though some of
the compressed data has been read.  The same is not true for
compression; once @code{BZ2_bzCompressInit} or @code{BZ2_bzWriteOpen} have
successfully completed, @code{BZ_MEM_ERROR} cannot occur.
@item 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.
@item BZ_DATA_ERROR_MAGIC
As a special case of @code{BZ_DATA_ERROR}, it is sometimes useful to
know when the compressed stream does not start with the correct
magic bytes (@code{'B' 'Z' 'h'}).  
@item BZ_IO_ERROR
Returned by @code{BZ2_bzRead} and @code{BZ2_bzWrite} when there is an error
reading or writing in the compressed file, and by @code{BZ2_bzReadOpen}
and @code{BZ2_bzWriteOpen} for attempts to use a file for which the
error indicator (viz, @code{ferror(f)}) is set.
On receipt of @code{BZ_IO_ERROR}, the caller should consult
@code{errno} and/or @code{perror} to acquire operating-system
specific information about the problem.
@item BZ_UNEXPECTED_EOF
Returned by @code{BZ2_bzRead} when the compressed file finishes
before the logical end of stream is detected.
@item BZ_OUTBUFF_FULL
Returned by @code{BZ2_bzBuffToBuffCompress} and
@code{BZ2_bzBuffToBuffDecompress} to indicate that the output data
will not fit into the output buffer provided.
@end table



@section Low-level interface

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

@end example

Prepares for compression.  The @code{bz_stream} structure
holds all data pertaining to the compression activity.  
A @code{bz_stream} structure should be allocated and initialised
prior to the call.
The fields of @code{bz_stream}
comprise the entirety of the user-visible data.  @code{state}
is a pointer to the private data structures required for compression.

Custom memory allocators are supported, via fields @code{bzalloc}, 
@code{bzfree},
and @code{opaque}.  The value 
@code{opaque} is passed to as the first argument to
all calls to @code{bzalloc} and @code{bzfree}, but is 
otherwise ignored by the library.
The call @code{bzalloc ( opaque, n, m )} is expected to return a 
pointer @code{p} to
@code{n * m} bytes of memory, and @code{bzfree ( opaque, p )} 
should free
that memory.

If you don't want to use a custom memory allocator, set @code{bzalloc}, 
@code{bzfree} and
@code{opaque} to @code{NULL}, 
and the library will then use the standard @code{malloc}/@code{free}
routines.

Before calling @code{BZ2_bzCompressInit}, fields @code{bzalloc}, 
@code{bzfree} and @code{opaque} should
be filled appropriately, as just described.  Upon return, the internal
state will have been allocated and initialised, and @code{total_in_lo32}, 
@code{total_in_hi32}, @code{total_out_lo32} and 
@code{total_out_hi32} will have been set to zero.  
These four fields are used by the library
to inform the caller of the total amount of data passed into and out of
the library, respectively.  You should not try to change them.
As of version 1.0, 64-bit counts are maintained, even on 32-bit
platforms, using the @code{_hi32} fields to store the upper 32 bits
of the count.  So, for example, the total amount of data in
is @code{(total_in_hi32 << 32) + total_in_lo32}.

Parameter @code{blockSize100k} specifies the block size to be used for
compression.  It should be a value between 1 and 9 inclusive, and the
actual block size used is 100000 x this figure.  9 gives the best
compression but takes most memory.

Parameter @code{verbosity} should be set to a number between 0 and 4
inclusive.  0 is silent, and greater numbers give increasingly verbose
monitoring/debugging output.  If the library has been compiled with
@code{-DBZ_NO_STDIO}, no such output will appear for any verbosity
setting.

Parameter @code{workFactor} controls how the compression phase behaves
when presented with worst case, highly repetitive, input data.  If
compression runs into difficulties caused by repetitive data, the
library switches from the standard sorting algorithm to a fallback
algorithm.  The fallback is slower than the standard algorithm by
perhaps a factor of three, but always behaves reasonably, no matter how
bad the input.

Lower values of @code{workFactor} reduce the amount of effort the
standard algorithm will expend before resorting to the fallback.  You
should set this parameter carefully; too low, and many inputs will be
handled by the fallback algorithm and so compress rather slowly, too
high, and your average-to-worst case compression times can become very
large.  The default value of 30 gives reasonable behaviour over a wide
range of circumstances.

Allowable values range from 0 to 250 inclusive.  0 is a special case,
equivalent to using the default value of 30.

Note that the compressed output generated is the same regardless of
whether or not the fallback algorithm is used.

Be aware also that this parameter may disappear entirely in future
versions of the library.  In principle it should be possible to devise a
good way to automatically choose which algorithm to use.  Such a
mechanism would render the parameter obsolete.

Possible return values:
@display
      @code{BZ_CONFIG_ERROR}
         if the library has been mis-compiled
      @code{BZ_PARAM_ERROR} 
         if @code{strm} is @code{NULL} 
         or @code{blockSize} < 1 or @code{blockSize} > 9
         or @code{verbosity} < 0 or @code{verbosity} > 4
         or @code{workFactor} < 0 or @code{workFactor} > 250
      @code{BZ_MEM_ERROR} 
         if not enough memory is available
      @code{BZ_OK} 
         otherwise
@end display
Allowable next actions:
@display
      @code{BZ2_bzCompress} 
         if @code{BZ_OK} is returned
      no specific action needed in case of error
@end display

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

Before each call to @code{BZ2_bzCompress}, @code{next_in} should point at
the data to be compressed, and @code{avail_in} should indicate how many
bytes the library may read.  @code{BZ2_bzCompress} 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
compressed data is to be placed, with @code{avail_out} indicating how
much output space is available.  @code{BZ2_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{BZ2_bzCompress}.  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.

A second purpose of @code{BZ2_bzCompress} is to request a change of mode of the
compressed stream.  

Conceptually, a compressed stream can be in one of four states: IDLE,
RUNNING, FLUSHING and FINISHING.  Before initialisation
(@code{BZ2_bzCompressInit}) and after termination (@code{BZ2_bzCompressEnd}), a
stream is regarded as IDLE.

Upon initialisation (@code{BZ2_bzCompressInit}), the stream is placed in the
RUNNING state.  Subsequent calls to @code{BZ2_bzCompress} should pass
@code{BZ_RUN} as the requested action; other actions are illegal and
will result in @code{BZ_SEQUENCE_ERROR}.

At some point, the calling program will have provided all the input data
it wants to.  It will then want to finish up -- in effect, asking the
library to process any data it might have buffered internally.  In this
state, @code{BZ2_bzCompress} will no longer attempt to read data from
@code{next_in}, but it will want to write data to @code{next_out}.
Because the output buffer supplied by the user can be arbitrarily small,
the finishing-up operation cannot necessarily be done with a single call
of @code{BZ2_bzCompress}.

Instead, the calling program passes @code{BZ_FINISH} as an action to
@code{BZ2_bzCompress}.  This changes the stream's state to FINISHING.  Any
remaining input (ie, @code{next_in[0 .. avail_in-1]}) is compressed and
transferred to the output buffer.  To do this, @code{BZ2_bzCompress} must be
called repeatedly until all the output has been consumed.  At that
point, @code{BZ2_bzCompress} returns @code{BZ_STREAM_END}, and the stream's
state is set back to IDLE.  @code{BZ2_bzCompressEnd} should then be
called.

Just to make sure the calling program does not cheat, the library makes
a note of @code{avail_in} at the time of the first call to
@code{BZ2_bzCompress} which has @code{BZ_FINISH} as an action (ie, at the
time the program has announced its intention to not supply any more
input).  By comparing this value with that of @code{avail_in} over
subsequent calls to @code{BZ2_bzCompress}, the library can detect any
attempts to slip in more data to compress.  Any calls for which this is
detected will return @code{BZ_SEQUENCE_ERROR}.  This indicates a
programming mistake which should be corrected.

Instead of asking to finish, the calling program may ask
@code{BZ2_bzCompress} to take all the remaining input, compress it and
terminate the current (Burrows-Wheeler) compression block.  This could
be useful for error control purposes.  The mechanism is analogous to
that for finishing: call @code{BZ2_bzCompress} with an action of
@code{BZ_FLUSH}, remove output data, and persist with the
@code{BZ_FLUSH} action until the value @code{BZ_RUN} is returned.  As
with finishing, @code{BZ2_bzCompress} detects any attempt to provide more
input data once the flush has begun.

Once the flush is complete, the stream returns to the normal RUNNING
state.

This all sounds pretty complex, but isn't really.  Here's a table
which shows which actions are allowable in each state, what action
will be taken, what the next state is, and what the non-error return
values are.  Note that you can't explicitly ask what state the
stream is in, but nor do you need to -- it can be inferred from the
values returned by @code{BZ2_bzCompress}.
@display
IDLE/@code{any}           
      Illegal.  IDLE state only exists after @code{BZ2_bzCompressEnd} or
      before @code{BZ2_bzCompressInit}.
      Return value = @code{BZ_SEQUENCE_ERROR}

RUNNING/@code{BZ_RUN}     
      Compress from @code{next_in} to @code{next_out} as much as possible.
      Next state = RUNNING
      Return value = @code{BZ_RUN_OK}

RUNNING/@code{BZ_FLUSH}   
      Remember current value of @code{next_in}.  Compress from @code{next_in}
      to @code{next_out} as much as possible, but do not accept any more input.  
      Next state = FLUSHING
      Return value = @code{BZ_FLUSH_OK}

RUNNING/@code{BZ_FINISH}  
      Remember current value of @code{next_in}.  Compress from @code{next_in}
      to @code{next_out} as much as possible, but do not accept any more input.
      Next state = FINISHING
      Return value = @code{BZ_FINISH_OK}

FLUSHING/@code{BZ_FLUSH}  
      Compress from @code{next_in} to @code{next_out} as much as possible, 
      but do not accept any more input.  
      If all the existing input has been used up and all compressed
      output has been removed
         Next state = RUNNING; Return value = @code{BZ_RUN_OK}
      else
         Next state = FLUSHING; Return value = @code{BZ_FLUSH_OK}

FLUSHING/other     
      Illegal.
      Return value = @code{BZ_SEQUENCE_ERROR}

FINISHING/@code{BZ_FINISH}  
      Compress from @code{next_in} to @code{next_out} as much as possible,
      but to not accept any more input.  
      If all the existing input has been used up and all compressed
      output has been removed
         Next state = IDLE; Return value = @code{BZ_STREAM_END}
      else
         Next state = FINISHING; Return value = @code{BZ_FINISHING}

FINISHING/other