manual.xml.svn-base

絲路server源碼 Silk Road server source

<?xml version="1.0"?> <!-- -*- sgml -*- -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[

<!-- various strings, dates etc. common to all docs -->
<!ENTITY % common-ents SYSTEM "entities.xml"> %common-ents;
]>

<book lang="en" id="userman" xreflabel="bzip2 Manual">

 <bookinfo>
  <title>bzip2 and libbzip2, version 1.0.3</title>
  <subtitle>A program and library for data compression</subtitle>
  <copyright>
   <year>&bz-lifespan;</year>
   <holder>Julian Seward</holder>
  </copyright>
  <releaseinfo>Version &bz-version; of &bz-date;</releaseinfo>

  <authorgroup>
   <author>
    <firstname>Julian</firstname>
    <surname>Seward</surname>
    <affiliation>
     <orgname>&bz-url;</orgname>
    </affiliation>
   </author>
  </authorgroup>

  <legalnotice>

  <para>This program, <computeroutput>bzip2</computeroutput>, the
  associated library <computeroutput>libbzip2</computeroutput>, and
  all documentation, are copyright &copy; &bz-lifespan; Julian Seward.
  All rights reserved.</para>

  <para>Redistribution and use in source and binary forms, with
  or without modification, are permitted provided that the
  following conditions are met:</para>

  <itemizedlist mark='bullet'>

   <listitem><para>Redistributions of source code must retain the
   above copyright notice, this list of conditions and the
   following disclaimer.</para></listitem>

   <listitem><para>The origin of this software must not be
   misrepresented; you must not claim that you wrote the original
   software.  If you use this software in a product, an
   acknowledgment in the product documentation would be
   appreciated but is not required.</para></listitem>

   <listitem><para>Altered source versions must be plainly marked
   as such, and must not be misrepresented as being the original
   software.</para></listitem>

   <listitem><para>The name of the author may not be used to
   endorse or promote products derived from this software without
   specific prior written permission.</para></listitem>

  </itemizedlist>

  <para>THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY
  EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
  TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  THE POSSIBILITY OF SUCH DAMAGE.</para>

 <para>PATENTS: To the best of my knowledge,
 <computeroutput>bzip2</computeroutput> and
 <computeroutput>libbzip2</computeroutput> do not use any patented
 algorithms.  However, I do not have the resources to carry
 out a patent search.  Therefore I cannot give any guarantee of
 the above statement.
 </para>

</legalnotice>

</bookinfo>



<chapter id="intro" xreflabel="Introduction">
<title>Introduction</title>

<para><computeroutput>bzip2</computeroutput> compresses files
using the Burrows-Wheeler block-sorting text compression
algorithm, and Huffman coding.  Compression is generally
considerably better than that achieved by more conventional
LZ77/LZ78-based compressors, and approaches the performance of
the PPM family of statistical compressors.</para>

<para><computeroutput>bzip2</computeroutput> is built on top of
<computeroutput>libbzip2</computeroutput>, a flexible library for
handling compressed data in the
<computeroutput>bzip2</computeroutput> format.  This manual
describes both how to use the program and how to work with the
library interface.  Most of the manual is devoted to this
library, not the program, which is good news if your interest is
only in the program.</para>

<itemizedlist mark='bullet'>

 <listitem><para><xref linkend="using"/> describes how to use
 <computeroutput>bzip2</computeroutput>; this is the only part
 you need to read if you just want to know how to operate the
 program.</para></listitem>

 <listitem><para><xref linkend="libprog"/> describes the
 programming interfaces in detail, and</para></listitem>

 <listitem><para><xref linkend="misc"/> records some
 miscellaneous notes which I thought ought to be recorded
 somewhere.</para></listitem>

</itemizedlist>

</chapter>


<chapter id="using" xreflabel="How to use bzip2">
<title>How to use bzip2</title>

<para>This chapter contains a copy of the
<computeroutput>bzip2</computeroutput> man page, and nothing
else.</para>

<sect1 id="name" xreflabel="NAME">
<title>NAME</title>

<itemizedlist mark='bullet'>

 <listitem><para><computeroutput>bzip2</computeroutput>,
  <computeroutput>bunzip2</computeroutput> - a block-sorting file
  compressor, v1.0.3</para></listitem>

 <listitem><para><computeroutput>bzcat</computeroutput> -
   decompresses files to stdout</para></listitem>

 <listitem><para><computeroutput>bzip2recover</computeroutput> -
   recovers data from damaged bzip2 files</para></listitem>

</itemizedlist>

</sect1>


<sect1 id="synopsis" xreflabel="SYNOPSIS">
<title>SYNOPSIS</title>

<itemizedlist mark='bullet'>

 <listitem><para><computeroutput>bzip2</computeroutput> [
  -cdfkqstvzVL123456789 ] [ filenames ...  ]</para></listitem>

 <listitem><para><computeroutput>bunzip2</computeroutput> [
  -fkvsVL ] [ filenames ...  ]</para></listitem>

 <listitem><para><computeroutput>bzcat</computeroutput> [ -s ] [
  filenames ...  ]</para></listitem>

 <listitem><para><computeroutput>bzip2recover</computeroutput>
  filename</para></listitem>

</itemizedlist>

</sect1>


<sect1 id="description" xreflabel="DESCRIPTION">
<title>DESCRIPTION</title>

<para><computeroutput>bzip2</computeroutput> compresses files
using the Burrows-Wheeler block sorting text compression
algorithm, and Huffman coding.  Compression is generally
considerably better than that achieved by more conventional
LZ77/LZ78-based compressors, and approaches the performance of
the PPM family of statistical compressors.</para>

<para>The command-line options are deliberately very similar to
those of GNU <computeroutput>gzip</computeroutput>, but they are
not identical.</para>

<para><computeroutput>bzip2</computeroutput> expects a list of
file names to accompany the command-line flags.  Each file is
replaced by a compressed version of itself, with the name
<computeroutput>original_name.bz2</computeroutput>.  Each
compressed file has the same modification date, permissions, and,
when possible, ownership as the corresponding original, so that
these properties can be correctly restored at decompression time.
File name handling is naive in the sense that there is no
mechanism for preserving original file names, permissions,
ownerships or dates in filesystems which lack these concepts, or
have serious file name length restrictions, such as
MS-DOS.</para>

<para><computeroutput>bzip2</computeroutput> and
<computeroutput>bunzip2</computeroutput> will by default not
overwrite existing files.  If you want this to happen, specify
the <computeroutput>-f</computeroutput> flag.</para>

<para>If no file names are specified,
<computeroutput>bzip2</computeroutput> compresses from standard
input to standard output.  In this case,
<computeroutput>bzip2</computeroutput> will decline to write
compressed output to a terminal, as this would be entirely
incomprehensible and therefore pointless.</para>

<para><computeroutput>bunzip2</computeroutput> (or
<computeroutput>bzip2 -d</computeroutput>) decompresses all
specified files.  Files which were not created by
<computeroutput>bzip2</computeroutput> will be detected and
ignored, and a warning issued.
<computeroutput>bzip2</computeroutput> attempts to guess the
filename for the decompressed file from that of the compressed
file as follows:</para>

<itemizedlist mark='bullet'>

 <listitem><para><computeroutput>filename.bz2 </computeroutput>
  becomes
  <computeroutput>filename</computeroutput></para></listitem>

 <listitem><para><computeroutput>filename.bz </computeroutput>
  becomes
  <computeroutput>filename</computeroutput></para></listitem>

 <listitem><para><computeroutput>filename.tbz2</computeroutput>
  becomes
  <computeroutput>filename.tar</computeroutput></para></listitem>

 <listitem><para><computeroutput>filename.tbz </computeroutput>
  becomes
  <computeroutput>filename.tar</computeroutput></para></listitem>

 <listitem><para><computeroutput>anyothername </computeroutput>
  becomes
  <computeroutput>anyothername.out</computeroutput></para></listitem>

</itemizedlist>

<para>If the file does not end in one of the recognised endings,
<computeroutput>.bz2</computeroutput>,
<computeroutput>.bz</computeroutput>,
<computeroutput>.tbz2</computeroutput> or
<computeroutput>.tbz</computeroutput>,
<computeroutput>bzip2</computeroutput> complains that it cannot
guess the name of the original file, and uses the original name
with <computeroutput>.out</computeroutput> appended.</para>

<para>As with compression, supplying no filenames causes
decompression from standard input to standard output.</para>

<para><computeroutput>bunzip2</computeroutput> will correctly
decompress a file which is the concatenation of two or more
compressed files.  The result is the concatenation of the
corresponding uncompressed files.  Integrity testing
(<computeroutput>-t</computeroutput>) of concatenated compressed
files is also supported.</para>

<para>You can also compress or decompress files to the standard
output by giving the <computeroutput>-c</computeroutput> flag.
Multiple files may be compressed and decompressed like this.  The
resulting outputs are fed sequentially to stdout.  Compression of
multiple files in this manner generates a stream containing
multiple compressed file representations.  Such a stream can be
decompressed correctly only by
<computeroutput>bzip2</computeroutput> version 0.9.0 or later.
Earlier versions of <computeroutput>bzip2</computeroutput> will
stop after decompressing the first file in the stream.</para>

<para><computeroutput>bzcat</computeroutput> (or
<computeroutput>bzip2 -dc</computeroutput>) decompresses all
specified files to the standard output.</para>

<para><computeroutput>bzip2</computeroutput> will read arguments
from the environment variables
<computeroutput>BZIP2</computeroutput> and
<computeroutput>BZIP</computeroutput>, in that order, and will
process them before any arguments read from the command line.
This gives a convenient way to supply default arguments.</para>

<para>Compression is always performed, even if the compressed
file is slightly larger than the original.  Files of less than
about one hundred bytes tend to get larger, since the compression
mechanism has a constant overhead in the region of 50 bytes.
Random data (including the output of most file compressors) is
coded at about 8.05 bits per byte, giving an expansion of around
0.5%.</para>

<para>As a self-check for your protection,
<computeroutput>bzip2</computeroutput> uses 32-bit CRCs to make
sure that the decompressed version of a file is identical to the
original.  This guards against corruption of the compressed data,
and against undetected bugs in
<computeroutput>bzip2</computeroutput> (hopefully very unlikely).
The chances of data corruption going undetected is microscopic,
about one chance in four billion for each file processed.  Be
aware, though, that the check occurs upon decompression, so it
can only tell you that something is wrong.  It can't help you
recover the original uncompressed data.  You can use
<computeroutput>bzip2recover</computeroutput> to try to recover
data from damaged files.</para>

<para>Return values: 0 for a normal exit, 1 for environmental
problems (file not found, invalid flags, I/O errors, etc.), 2
to indicate a corrupt compressed file, 3 for an internal
consistency error (eg, bug) which caused
<computeroutput>bzip2</computeroutput> to panic.</para>

</sect1>


<sect1 id="options" xreflabel="OPTIONS">
<title>OPTIONS</title>

<variablelist>

 <varlistentry>
 <term><computeroutput>-c --stdout</computeroutput></term>
 <listitem><para>Compress or decompress to standard
  output.</para></listitem>
 </varlistentry>

 <varlistentry>
 <term><computeroutput>-d --decompress</computeroutput></term>