manual.texi

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

       -s --small
              Reduce memory usage, for compression, decompression
              and  testing.   Files  are  decompressed and tested
              using a modified algorithm which only requires  2.5
              bytes  per  block byte.  This means any file can be
              decompressed in 2300k of memory,  albeit  at  about
              half the normal speed.

              During  compression,  -s  selects  a  block size of
              200k, which limits memory use to  around  the  same
              figure,  at  the expense of your compression ratio.
              In short, if your  machine  is  low  on  memory  (8
              megabytes  or  less),  use  -s for everything.  See
              MEMORY MANAGEMENT above.

       -v --verbose
              Verbose mode -- show the compression ratio for each
              file  processed.   Further  -v's  increase the ver-
              bosity level, spewing out lots of information which
              is primarily of interest for diagnostic purposes.

       -L --license -V --version
              Display  the  software  version,  license terms and
              conditions.

       -1 to -9
              Set the block size to 100 k, 200 k ..  900  k  when
              compressing.   Has  no  effect  when decompressing.
              See MEMORY MANAGEMENT above.

       --repetitive-fast
              bzip2 injects some small  pseudo-random  variations
              into  very  repetitive  blocks  to limit worst-case
              performance during compression.   If  sorting  runs
              into  difficulties,  the  block  is randomised, and
              sorting is restarted.  Very roughly, bzip2 persists
              for  three  times  as  long as a well-behaved input
              would take before resorting to randomisation.  This
              flag makes it give up much sooner.

       --repetitive-best
              Opposite  of  --repetitive-fast;  try  a lot harder
              before resorting to randomisation.


RECOVERING DATA FROM DAMAGED FILES
       bzip2 compresses files in blocks, usually 900kbytes  long.
       Each block is handled independently.  If a media or trans-
       mission error causes a multi-block  .bz2  file  to  become
       damaged,  it  may  be  possible  to  recover data from the
       undamaged blocks in the file.

       The compressed representation of each block  is  delimited
       by  a  48-bit pattern, which makes it possible to find the
       block boundaries with reasonable  certainty.   Each  block
       also  carries its own 32-bit CRC, so damaged blocks can be
       distinguished from undamaged ones.

       bzip2recover is a  simple  program  whose  purpose  is  to
       search  for blocks in .bz2 files, and write each block out
       into its own .bz2 file.  You can then use bzip2 -t to test
       the integrity of the resulting files, and decompress those
       which are undamaged.

       bzip2recover takes a single argument, the name of the dam-
       aged file, and writes a number of files "rec0001file.bz2",
       "rec0002file.bz2", etc, containing the  extracted  blocks.
       The  output  filenames  are  designed  so  that the use of
       wildcards in subsequent processing -- for example,  "bzip2
       -dc  rec*file.bz2  > recovered_data" -- lists the files in
       the "right" order.

       bzip2recover should be of most use dealing with large .bz2
       files,  as  these will contain many blocks.  It is clearly
       futile to use it on damaged single-block  files,  since  a
       damaged  block  cannot  be recovered.  If you wish to min-
       imise any potential data loss through media  or  transmis-
       sion errors, you might consider compressing with a smaller
       block size.


PERFORMANCE NOTES
       The sorting phase of compression gathers together  similar
       strings  in  the  file.  Because of this, files containing
       very long runs of  repeated  symbols,  like  "aabaabaabaab
       ..."   (repeated   several  hundred  times)  may  compress
       extraordinarily slowly.  You can use the -vvvvv option  to
       monitor progress in great detail, if you want.  Decompres-
       sion speed is unaffected.

       Such pathological cases seem rare in  practice,  appearing
       mostly in artificially-constructed test files, and in low-
       level disk images.  It may be inadvisable to use bzip2  to
       compress  the  latter.   If you do get a file which causes
       severe slowness in compression, try making the block  size
       as small as possible, with flag -1.

       bzip2  usually  allocates  several  megabytes of memory to
       operate in, and then charges all over it in a fairly  ran-
       dom  fashion.   This means that performance, both for com-
       pressing and decompressing, is largely determined  by  the
       speed  at  which  your  machine  can service cache misses.
       Because of this, small changes to the code to  reduce  the
       miss  rate  have  been observed to give disproportionately
       large performance improvements.  I imagine bzip2 will per-
       form best on machines with very large caches.


CAVEATS
       I/O  error  messages  are not as helpful as they could be.
       Bzip2 tries hard to detect I/O errors  and  exit  cleanly,
       but  the  details  of  what  the problem is sometimes seem
       rather misleading.

       This manual page pertains to version 0.9.0 of bzip2.  Com-
       pressed  data created by this version is entirely forwards
       and backwards compatible with the previous public release,
       version  0.1pl2,  but  with the following exception: 0.9.0
       can correctly decompress multiple concatenated  compressed
       files.   0.1pl2  cannot do this; it will stop after decom-
       pressing just the first file in the stream.

       Wildcard expansion for Windows 95 and NT is flaky.

       bzip2recover uses 32-bit integers to represent  bit  posi-
       tions  in compressed files, so it cannot handle compressed
       files more than 512 megabytes long.  This could easily  be
       fixed.


AUTHOR
       Julian Seward, jseward@@acm.org.

       The ideas embodied in bzip2 are due to (at least) the fol-
       lowing people: Michael Burrows and David Wheeler (for  the
       block  sorting  transformation), David Wheeler (again, for
       the Huffman coder), Peter Fenwick (for the structured cod-
       ing model in the original bzip, and many refinements), and
       Alistair Moffat, Radford Neal  and  Ian  Witten  (for  the
       arithmetic  coder  in  the  original  bzip).   I  am  much
       indebted for their help, support and advice.  See the man-
       ual  in the source distribution for pointers to sources of
       documentation.  Christian von Roques encouraged me to look
       for  faster sorting algorithms, so as to speed up compres-
       sion.  Bela Lubkin encouraged me to improve the worst-case
       compression performance.  Many people sent patches, helped
       with portability problems, lent machines, gave advice  and
       were generally helpful.
@end example





@chapter Programming with @code{libbzip2}

This chapter describes the programming interface to @code{libbzip2}.

For general background information, particularly about memory
use and performance aspects, you'd be well advised to read Chapter 2
as well.

@section Top-level structure

@code{libbzip2} is a flexible library for compressing and decompressing
data in the @code{bzip2} data format.  Although packaged as a single
entity, it helps to regard the library as three separate parts: the low
level interface, and the high level interface, and some utility
functions.

The structure of @code{libbzip2}'s interfaces is similar to
that of Jean-loup Gailly's and Mark Adler's excellent @code{zlib} 
library.

@subsection Low-level summary

This interface provides services for compressing and decompressing
data in memory.  There's no provision for dealing with files, streams
or any other I/O mechanisms, just straight memory-to-memory work.
In fact, this part of the library can be compiled without inclusion
of @code{stdio.h}, which may be helpful for embedded applications.

The low-level part of the library has no global variables and
is therefore thread-safe.

Six routines make up the low level interface: 
@code{bzCompressInit}, @code{bzCompress}, and @* @code{bzCompressEnd}
for compression,
and a corresponding trio @code{bzDecompressInit}, @* @code{bzDecompress}
and @code{bzDecompressEnd} for decompression.  
The @code{*Init} functions allocate
memory for compression/decompression and do other
initialisations, whilst the @code{*End} functions close down operations
and release memory.

The real work is done by @code{bzCompress} and @code{bzDecompress}.  
These compress/decompress data from a user-supplied input buffer
to a user-supplied output buffer.  These buffers can be any size;
arbitrary quantities of data are handled by making repeated calls
to these functions.  This is a flexible mechanism allowing a 
consumer-pull style of activity, or producer-push, or a mixture of
both.



@subsection High-level summary

This interface provides some handy wrappers around the low-level
interface to facilitate reading and writing @code{bzip2} format
files (@code{.bz2} files).  The routines provide hooks to facilitate
reading files in which the @code{bzip2} data stream is embedded 
within some larger-scale file structure, or where there are
multiple @code{bzip2} data streams concatenated end-to-end.

For reading files, @code{bzReadOpen}, @code{bzRead}, @code{bzReadClose}
and @code{bzReadGetUnused} are supplied.  For writing files,
@code{bzWriteOpen}, @code{bzWrite} and @code{bzWriteFinish} are
available.

As with the low-level library, no global variables are used
so the library is per se thread-safe.  However, if I/O errors
occur whilst reading or writing the underlying compressed files,
you may have to consult @code{errno} to determine the cause of
the error.  In that case, you'd need a C library which correctly
supports @code{errno} in a multithreaded environment.

To make the library a little simpler and more portable,
@code{bzReadOpen} and @code{bzWriteOpen} require you to pass them file
handles (@code{FILE*}s) which have previously been opened for reading or
writing respectively.  That avoids portability problems associated with
file operations and file attributes, whilst not being much of an
imposition on the programmer.



@subsection Utility functions summary
For very simple needs, @code{bzBuffToBuffCompress} and
@code{bzBuffToBuffDecompress} are provided.  These compress
data in memory from one buffer to another buffer in a single
function call.  You should assess whether these functions
fulfill your memory-to-memory compression/decompression
requirements before investing effort in understanding the more
general but more complex low-level interface.

Yoshioka Tsuneo (@code{QWF00133@@niftyserve.or.jp} /
@code{tsuneo-y@@is.aist-nara.ac.jp}) has contributed some functions to
give better @code{zlib} compatibility.  These functions are
@code{bzopen}, @code{bzread}, @code{bzwrite}, @code{bzflush},
@code{bzclose},
@code{bzerror} and @code{bzlibVersion}.  You may find these functions
more convenient for simple file reading and writing, than those in the
high-level interface.  These functions are not (yet) officially part of
the library, and are not further documented here.  If they break, you
get to keep all the pieces.  I hope to document them properly when time
permits.

Yoshioka also contributed modifications to allow the library to be
built as a Windows DLL.


@section Error handling

The library is designed to recover cleanly in all situations, including
the worst-case situation of decompressing random data.  I'm not 
100% sure that it can always do this, so you might want to add
a signal handler to catch segmentation violations during decompression
if you are feeling especially paranoid.  I would be interested in
hearing more about the robustness of the library to corrupted
compressed data.

The file @code{bzlib.h} contains all definitions needed to use
the library.  In particular, you should definitely not include
@code{bzlib_private.h}.

In @code{bzlib.h}, the various return values are defined.  The following
list is not intended as an exhaustive description of the circumstances 
in which a given value may be returned -- those descriptions are given
later.  Rather, it is intended to convey the rough meaning of each
return value.  The first five actions are normal and not intended to 
denote an error situation.
@table @code
@item BZ_OK
The requested action was completed successfully.
@item BZ_RUN_OK
@itemx BZ_FLUSH_OK
@itemx BZ_FINISH_OK
In @code{bzCompress}, the requested flush/finish/nothing-special action
was completed successfully.
@item BZ_STREAM_END
Compression of data was completed, or the logical stream end was
detected during decompression.
@end table

The following return values indicate an error of some kind.
@table @code
@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{bzDecompress} and
@code{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{bzCompressInit} or @code{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{bzRead} and @code{bzRead} when there is an error
reading or writing in the compressed file, and by @code{bzReadOpen}