/StormLib/stormlib/bzip2/manual.xml

http://ghostcb.googlecode.com/ · XML · 2964 lines · 2402 code · 561 blank · 1 comment · 0 complexity · 7a003c59ef2f36322fcb36ab195f3f70 MD5 · raw file

Large files are truncated click here to view the full file

  1. <?xml version="1.0"?> <!-- -*- sgml -*- -->
  2. <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  3. "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
  4. <!-- various strings, dates etc. common to all docs -->
  5. <!ENTITY % common-ents SYSTEM "entities.xml"> %common-ents;
  6. ]>
  7. <book lang="en" id="userman" xreflabel="bzip2 Manual">
  8. <bookinfo>
  9. <title>bzip2 and libbzip2, version 1.0.5</title>
  10. <subtitle>A program and library for data compression</subtitle>
  11. <copyright>
  12. <year>&bz-lifespan;</year>
  13. <holder>Julian Seward</holder>
  14. </copyright>
  15. <releaseinfo>Version &bz-version; of &bz-date;</releaseinfo>
  16. <authorgroup>
  17. <author>
  18. <firstname>Julian</firstname>
  19. <surname>Seward</surname>
  20. <affiliation>
  21. <orgname>&bz-url;</orgname>
  22. </affiliation>
  23. </author>
  24. </authorgroup>
  25. <legalnotice>
  26. <para>This program, <computeroutput>bzip2</computeroutput>, the
  27. associated library <computeroutput>libbzip2</computeroutput>, and
  28. all documentation, are copyright &copy; &bz-lifespan; Julian Seward.
  29. All rights reserved.</para>
  30. <para>Redistribution and use in source and binary forms, with
  31. or without modification, are permitted provided that the
  32. following conditions are met:</para>
  33. <itemizedlist mark='bullet'>
  34. <listitem><para>Redistributions of source code must retain the
  35. above copyright notice, this list of conditions and the
  36. following disclaimer.</para></listitem>
  37. <listitem><para>The origin of this software must not be
  38. misrepresented; you must not claim that you wrote the original
  39. software. If you use this software in a product, an
  40. acknowledgment in the product documentation would be
  41. appreciated but is not required.</para></listitem>
  42. <listitem><para>Altered source versions must be plainly marked
  43. as such, and must not be misrepresented as being the original
  44. software.</para></listitem>
  45. <listitem><para>The name of the author may not be used to
  46. endorse or promote products derived from this software without
  47. specific prior written permission.</para></listitem>
  48. </itemizedlist>
  49. <para>THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY
  50. EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  51. THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  52. PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  53. AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  54. EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
  55. TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  56. DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  57. ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  58. LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  59. IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  60. THE POSSIBILITY OF SUCH DAMAGE.</para>
  61. <para>PATENTS: To the best of my knowledge,
  62. <computeroutput>bzip2</computeroutput> and
  63. <computeroutput>libbzip2</computeroutput> do not use any patented
  64. algorithms. However, I do not have the resources to carry
  65. out a patent search. Therefore I cannot give any guarantee of
  66. the above statement.
  67. </para>
  68. </legalnotice>
  69. </bookinfo>
  70. <chapter id="intro" xreflabel="Introduction">
  71. <title>Introduction</title>
  72. <para><computeroutput>bzip2</computeroutput> compresses files
  73. using the Burrows-Wheeler block-sorting text compression
  74. algorithm, and Huffman coding. Compression is generally
  75. considerably better than that achieved by more conventional
  76. LZ77/LZ78-based compressors, and approaches the performance of
  77. the PPM family of statistical compressors.</para>
  78. <para><computeroutput>bzip2</computeroutput> is built on top of
  79. <computeroutput>libbzip2</computeroutput>, a flexible library for
  80. handling compressed data in the
  81. <computeroutput>bzip2</computeroutput> format. This manual
  82. describes both how to use the program and how to work with the
  83. library interface. Most of the manual is devoted to this
  84. library, not the program, which is good news if your interest is
  85. only in the program.</para>
  86. <itemizedlist mark='bullet'>
  87. <listitem><para><xref linkend="using"/> describes how to use
  88. <computeroutput>bzip2</computeroutput>; this is the only part
  89. you need to read if you just want to know how to operate the
  90. program.</para></listitem>
  91. <listitem><para><xref linkend="libprog"/> describes the
  92. programming interfaces in detail, and</para></listitem>
  93. <listitem><para><xref linkend="misc"/> records some
  94. miscellaneous notes which I thought ought to be recorded
  95. somewhere.</para></listitem>
  96. </itemizedlist>
  97. </chapter>
  98. <chapter id="using" xreflabel="How to use bzip2">
  99. <title>How to use bzip2</title>
  100. <para>This chapter contains a copy of the
  101. <computeroutput>bzip2</computeroutput> man page, and nothing
  102. else.</para>
  103. <sect1 id="name" xreflabel="NAME">
  104. <title>NAME</title>
  105. <itemizedlist mark='bullet'>
  106. <listitem><para><computeroutput>bzip2</computeroutput>,
  107. <computeroutput>bunzip2</computeroutput> - a block-sorting file
  108. compressor, v1.0.4</para></listitem>
  109. <listitem><para><computeroutput>bzcat</computeroutput> -
  110. decompresses files to stdout</para></listitem>
  111. <listitem><para><computeroutput>bzip2recover</computeroutput> -
  112. recovers data from damaged bzip2 files</para></listitem>
  113. </itemizedlist>
  114. </sect1>
  115. <sect1 id="synopsis" xreflabel="SYNOPSIS">
  116. <title>SYNOPSIS</title>
  117. <itemizedlist mark='bullet'>
  118. <listitem><para><computeroutput>bzip2</computeroutput> [
  119. -cdfkqstvzVL123456789 ] [ filenames ... ]</para></listitem>
  120. <listitem><para><computeroutput>bunzip2</computeroutput> [
  121. -fkvsVL ] [ filenames ... ]</para></listitem>
  122. <listitem><para><computeroutput>bzcat</computeroutput> [ -s ] [
  123. filenames ... ]</para></listitem>
  124. <listitem><para><computeroutput>bzip2recover</computeroutput>
  125. filename</para></listitem>
  126. </itemizedlist>
  127. </sect1>
  128. <sect1 id="description" xreflabel="DESCRIPTION">
  129. <title>DESCRIPTION</title>
  130. <para><computeroutput>bzip2</computeroutput> compresses files
  131. using the Burrows-Wheeler block sorting text compression
  132. algorithm, and Huffman coding. Compression is generally
  133. considerably better than that achieved by more conventional
  134. LZ77/LZ78-based compressors, and approaches the performance of
  135. the PPM family of statistical compressors.</para>
  136. <para>The command-line options are deliberately very similar to
  137. those of GNU <computeroutput>gzip</computeroutput>, but they are
  138. not identical.</para>
  139. <para><computeroutput>bzip2</computeroutput> expects a list of
  140. file names to accompany the command-line flags. Each file is
  141. replaced by a compressed version of itself, with the name
  142. <computeroutput>original_name.bz2</computeroutput>. Each
  143. compressed file has the same modification date, permissions, and,
  144. when possible, ownership as the corresponding original, so that
  145. these properties can be correctly restored at decompression time.
  146. File name handling is naive in the sense that there is no
  147. mechanism for preserving original file names, permissions,
  148. ownerships or dates in filesystems which lack these concepts, or
  149. have serious file name length restrictions, such as
  150. MS-DOS.</para>
  151. <para><computeroutput>bzip2</computeroutput> and
  152. <computeroutput>bunzip2</computeroutput> will by default not
  153. overwrite existing files. If you want this to happen, specify
  154. the <computeroutput>-f</computeroutput> flag.</para>
  155. <para>If no file names are specified,
  156. <computeroutput>bzip2</computeroutput> compresses from standard
  157. input to standard output. In this case,
  158. <computeroutput>bzip2</computeroutput> will decline to write
  159. compressed output to a terminal, as this would be entirely
  160. incomprehensible and therefore pointless.</para>
  161. <para><computeroutput>bunzip2</computeroutput> (or
  162. <computeroutput>bzip2 -d</computeroutput>) decompresses all
  163. specified files. Files which were not created by
  164. <computeroutput>bzip2</computeroutput> will be detected and
  165. ignored, and a warning issued.
  166. <computeroutput>bzip2</computeroutput> attempts to guess the
  167. filename for the decompressed file from that of the compressed
  168. file as follows:</para>
  169. <itemizedlist mark='bullet'>
  170. <listitem><para><computeroutput>filename.bz2 </computeroutput>
  171. becomes
  172. <computeroutput>filename</computeroutput></para></listitem>
  173. <listitem><para><computeroutput>filename.bz </computeroutput>
  174. becomes
  175. <computeroutput>filename</computeroutput></para></listitem>
  176. <listitem><para><computeroutput>filename.tbz2</computeroutput>
  177. becomes
  178. <computeroutput>filename.tar</computeroutput></para></listitem>
  179. <listitem><para><computeroutput>filename.tbz </computeroutput>
  180. becomes
  181. <computeroutput>filename.tar</computeroutput></para></listitem>
  182. <listitem><para><computeroutput>anyothername </computeroutput>
  183. becomes
  184. <computeroutput>anyothername.out</computeroutput></para></listitem>
  185. </itemizedlist>
  186. <para>If the file does not end in one of the recognised endings,
  187. <computeroutput>.bz2</computeroutput>,
  188. <computeroutput>.bz</computeroutput>,
  189. <computeroutput>.tbz2</computeroutput> or
  190. <computeroutput>.tbz</computeroutput>,
  191. <computeroutput>bzip2</computeroutput> complains that it cannot
  192. guess the name of the original file, and uses the original name
  193. with <computeroutput>.out</computeroutput> appended.</para>
  194. <para>As with compression, supplying no filenames causes
  195. decompression from standard input to standard output.</para>
  196. <para><computeroutput>bunzip2</computeroutput> will correctly
  197. decompress a file which is the concatenation of two or more
  198. compressed files. The result is the concatenation of the
  199. corresponding uncompressed files. Integrity testing
  200. (<computeroutput>-t</computeroutput>) of concatenated compressed
  201. files is also supported.</para>
  202. <para>You can also compress or decompress files to the standard
  203. output by giving the <computeroutput>-c</computeroutput> flag.
  204. Multiple files may be compressed and decompressed like this. The
  205. resulting outputs are fed sequentially to stdout. Compression of
  206. multiple files in this manner generates a stream containing
  207. multiple compressed file representations. Such a stream can be
  208. decompressed correctly only by
  209. <computeroutput>bzip2</computeroutput> version 0.9.0 or later.
  210. Earlier versions of <computeroutput>bzip2</computeroutput> will
  211. stop after decompressing the first file in the stream.</para>
  212. <para><computeroutput>bzcat</computeroutput> (or
  213. <computeroutput>bzip2 -dc</computeroutput>) decompresses all
  214. specified files to the standard output.</para>
  215. <para><computeroutput>bzip2</computeroutput> will read arguments
  216. from the environment variables
  217. <computeroutput>BZIP2</computeroutput> and
  218. <computeroutput>BZIP</computeroutput>, in that order, and will
  219. process them before any arguments read from the command line.
  220. This gives a convenient way to supply default arguments.</para>
  221. <para>Compression is always performed, even if the compressed
  222. file is slightly larger than the original. Files of less than
  223. about one hundred bytes tend to get larger, since the compression
  224. mechanism has a constant overhead in the region of 50 bytes.
  225. Random data (including the output of most file compressors) is
  226. coded at about 8.05 bits per byte, giving an expansion of around
  227. 0.5%.</para>
  228. <para>As a self-check for your protection,
  229. <computeroutput>bzip2</computeroutput> uses 32-bit CRCs to make
  230. sure that the decompressed version of a file is identical to the
  231. original. This guards against corruption of the compressed data,
  232. and against undetected bugs in
  233. <computeroutput>bzip2</computeroutput> (hopefully very unlikely).
  234. The chances of data corruption going undetected is microscopic,
  235. about one chance in four billion for each file processed. Be
  236. aware, though, that the check occurs upon decompression, so it
  237. can only tell you that something is wrong. It can't help you
  238. recover the original uncompressed data. You can use
  239. <computeroutput>bzip2recover</computeroutput> to try to recover
  240. data from damaged files.</para>
  241. <para>Return values: 0 for a normal exit, 1 for environmental
  242. problems (file not found, invalid flags, I/O errors, etc.), 2
  243. to indicate a corrupt compressed file, 3 for an internal
  244. consistency error (eg, bug) which caused
  245. <computeroutput>bzip2</computeroutput> to panic.</para>
  246. </sect1>
  247. <sect1 id="options" xreflabel="OPTIONS">
  248. <title>OPTIONS</title>
  249. <variablelist>
  250. <varlistentry>
  251. <term><computeroutput>-c --stdout</computeroutput></term>
  252. <listitem><para>Compress or decompress to standard
  253. output.</para></listitem>
  254. </varlistentry>
  255. <varlistentry>
  256. <term><computeroutput>-d --decompress</computeroutput></term>
  257. <listitem><para>Force decompression.
  258. <computeroutput>bzip2</computeroutput>,
  259. <computeroutput>bunzip2</computeroutput> and
  260. <computeroutput>bzcat</computeroutput> are really the same
  261. program, and the decision about what actions to take is done on
  262. the basis of which name is used. This flag overrides that
  263. mechanism, and forces bzip2 to decompress.</para></listitem>
  264. </varlistentry>
  265. <varlistentry>
  266. <term><computeroutput>-z --compress</computeroutput></term>
  267. <listitem><para>The complement to
  268. <computeroutput>-d</computeroutput>: forces compression,
  269. regardless of the invokation name.</para></listitem>
  270. </varlistentry>
  271. <varlistentry>
  272. <term><computeroutput>-t --test</computeroutput></term>
  273. <listitem><para>Check integrity of the specified file(s), but
  274. don't decompress them. This really performs a trial
  275. decompression and throws away the result.</para></listitem>
  276. </varlistentry>
  277. <varlistentry>
  278. <term><computeroutput>-f --force</computeroutput></term>
  279. <listitem><para>Force overwrite of output files. Normally,
  280. <computeroutput>bzip2</computeroutput> will not overwrite
  281. existing output files. Also forces
  282. <computeroutput>bzip2</computeroutput> to break hard links to
  283. files, which it otherwise wouldn't do.</para>
  284. <para><computeroutput>bzip2</computeroutput> normally declines
  285. to decompress files which don't have the correct magic header
  286. bytes. If forced (<computeroutput>-f</computeroutput>),
  287. however, it will pass such files through unmodified. This is
  288. how GNU <computeroutput>gzip</computeroutput> behaves.</para>
  289. </listitem>
  290. </varlistentry>
  291. <varlistentry>
  292. <term><computeroutput>-k --keep</computeroutput></term>
  293. <listitem><para>Keep (don't delete) input files during
  294. compression or decompression.</para></listitem>
  295. </varlistentry>
  296. <varlistentry>
  297. <term><computeroutput>-s --small</computeroutput></term>
  298. <listitem><para>Reduce memory usage, for compression,
  299. decompression and testing. Files are decompressed and tested
  300. using a modified algorithm which only requires 2.5 bytes per
  301. block byte. This means any file can be decompressed in 2300k
  302. of memory, albeit at about half the normal speed.</para>
  303. <para>During compression, <computeroutput>-s</computeroutput>
  304. selects a block size of 200k, which limits memory use to around
  305. the same figure, at the expense of your compression ratio. In
  306. short, if your machine is low on memory (8 megabytes or less),
  307. use <computeroutput>-s</computeroutput> for everything. See
  308. <xref linkend="memory-management"/> below.</para></listitem>
  309. </varlistentry>
  310. <varlistentry>
  311. <term><computeroutput>-q --quiet</computeroutput></term>
  312. <listitem><para>Suppress non-essential warning messages.
  313. Messages pertaining to I/O errors and other critical events
  314. will not be suppressed.</para></listitem>
  315. </varlistentry>
  316. <varlistentry>
  317. <term><computeroutput>-v --verbose</computeroutput></term>
  318. <listitem><para>Verbose mode -- show the compression ratio for
  319. each file processed. Further
  320. <computeroutput>-v</computeroutput>'s increase the verbosity
  321. level, spewing out lots of information which is primarily of
  322. interest for diagnostic purposes.</para></listitem>
  323. </varlistentry>
  324. <varlistentry>
  325. <term><computeroutput>-L --license -V --version</computeroutput></term>
  326. <listitem><para>Display the software version, license terms and
  327. conditions.</para></listitem>
  328. </varlistentry>
  329. <varlistentry>
  330. <term><computeroutput>-1</computeroutput> (or
  331. <computeroutput>--fast</computeroutput>) to
  332. <computeroutput>-9</computeroutput> (or
  333. <computeroutput>-best</computeroutput>)</term>
  334. <listitem><para>Set the block size to 100 k, 200 k ... 900 k
  335. when compressing. Has no effect when decompressing. See <xref
  336. linkend="memory-management" /> below. The
  337. <computeroutput>--fast</computeroutput> and
  338. <computeroutput>--best</computeroutput> aliases are primarily
  339. for GNU <computeroutput>gzip</computeroutput> compatibility.
  340. In particular, <computeroutput>--fast</computeroutput> doesn't
  341. make things significantly faster. And
  342. <computeroutput>--best</computeroutput> merely selects the
  343. default behaviour.</para></listitem>
  344. </varlistentry>
  345. <varlistentry>
  346. <term><computeroutput>--</computeroutput></term>
  347. <listitem><para>Treats all subsequent arguments as file names,
  348. even if they start with a dash. This is so you can handle
  349. files with names beginning with a dash, for example:
  350. <computeroutput>bzip2 --
  351. -myfilename</computeroutput>.</para></listitem>
  352. </varlistentry>
  353. <varlistentry>
  354. <term><computeroutput>--repetitive-fast</computeroutput></term>
  355. <term><computeroutput>--repetitive-best</computeroutput></term>
  356. <listitem><para>These flags are redundant in versions 0.9.5 and
  357. above. They provided some coarse control over the behaviour of
  358. the sorting algorithm in earlier versions, which was sometimes
  359. useful. 0.9.5 and above have an improved algorithm which
  360. renders these flags irrelevant.</para></listitem>
  361. </varlistentry>
  362. </variablelist>
  363. </sect1>
  364. <sect1 id="memory-management" xreflabel="MEMORY MANAGEMENT">
  365. <title>MEMORY MANAGEMENT</title>
  366. <para><computeroutput>bzip2</computeroutput> compresses large
  367. files in blocks. The block size affects both the compression
  368. ratio achieved, and the amount of memory needed for compression
  369. and decompression. The flags <computeroutput>-1</computeroutput>
  370. through <computeroutput>-9</computeroutput> specify the block
  371. size to be 100,000 bytes through 900,000 bytes (the default)
  372. respectively. At decompression time, the block size used for
  373. compression is read from the header of the compressed file, and
  374. <computeroutput>bunzip2</computeroutput> then allocates itself
  375. just enough memory to decompress the file. Since block sizes are
  376. stored in compressed files, it follows that the flags
  377. <computeroutput>-1</computeroutput> to
  378. <computeroutput>-9</computeroutput> are irrelevant to and so
  379. ignored during decompression.</para>
  380. <para>Compression and decompression requirements, in bytes, can be
  381. estimated as:</para>
  382. <programlisting>
  383. Compression: 400k + ( 8 x block size )
  384. Decompression: 100k + ( 4 x block size ), or
  385. 100k + ( 2.5 x block size )
  386. </programlisting>
  387. <para>Larger block sizes give rapidly diminishing marginal
  388. returns. Most of the compression comes from the first two or
  389. three hundred k of block size, a fact worth bearing in mind when
  390. using <computeroutput>bzip2</computeroutput> on small machines.
  391. It is also important to appreciate that the decompression memory
  392. requirement is set at compression time by the choice of block
  393. size.</para>
  394. <para>For files compressed with the default 900k block size,
  395. <computeroutput>bunzip2</computeroutput> will require about 3700
  396. kbytes to decompress. To support decompression of any file on a
  397. 4 megabyte machine, <computeroutput>bunzip2</computeroutput> has
  398. an option to decompress using approximately half this amount of
  399. memory, about 2300 kbytes. Decompression speed is also halved,
  400. so you should use this option only where necessary. The relevant
  401. flag is <computeroutput>-s</computeroutput>.</para>
  402. <para>In general, try and use the largest block size memory
  403. constraints allow, since that maximises the compression achieved.
  404. Compression and decompression speed are virtually unaffected by
  405. block size.</para>
  406. <para>Another significant point applies to files which fit in a
  407. single block -- that means most files you'd encounter using a
  408. large block size. The amount of real memory touched is
  409. proportional to the size of the file, since the file is smaller
  410. than a block. For example, compressing a file 20,000 bytes long
  411. with the flag <computeroutput>-9</computeroutput> will cause the
  412. compressor to allocate around 7600k of memory, but only touch
  413. 400k + 20000 * 8 = 560 kbytes of it. Similarly, the decompressor
  414. will allocate 3700k but only touch 100k + 20000 * 4 = 180
  415. kbytes.</para>
  416. <para>Here is a table which summarises the maximum memory usage
  417. for different block sizes. Also recorded is the total compressed
  418. size for 14 files of the Calgary Text Compression Corpus
  419. totalling 3,141,622 bytes. This column gives some feel for how
  420. compression varies with block size. These figures tend to
  421. understate the advantage of larger block sizes for larger files,
  422. since the Corpus is dominated by smaller files.</para>
  423. <programlisting>
  424. Compress Decompress Decompress Corpus
  425. Flag usage usage -s usage Size
  426. -1 1200k 500k 350k 914704
  427. -2 2000k 900k 600k 877703
  428. -3 2800k 1300k 850k 860338
  429. -4 3600k 1700k 1100k 846899
  430. -5 4400k 2100k 1350k 845160
  431. -6 5200k 2500k 1600k 838626
  432. -7 6100k 2900k 1850k 834096
  433. -8 6800k 3300k 2100k 828642
  434. -9 7600k 3700k 2350k 828642
  435. </programlisting>
  436. </sect1>
  437. <sect1 id="recovering" xreflabel="RECOVERING DATA FROM DAMAGED FILES">
  438. <title>RECOVERING DATA FROM DAMAGED FILES</title>
  439. <para><computeroutput>bzip2</computeroutput> compresses files in
  440. blocks, usually 900kbytes long. Each block is handled
  441. independently. If a media or transmission error causes a
  442. multi-block <computeroutput>.bz2</computeroutput> file to become
  443. damaged, it may be possible to recover data from the undamaged
  444. blocks in the file.</para>
  445. <para>The compressed representation of each block is delimited by
  446. a 48-bit pattern, which makes it possible to find the block
  447. boundaries with reasonable certainty. Each block also carries
  448. its own 32-bit CRC, so damaged blocks can be distinguished from
  449. undamaged ones.</para>
  450. <para><computeroutput>bzip2recover</computeroutput> is a simple
  451. program whose purpose is to search for blocks in
  452. <computeroutput>.bz2</computeroutput> files, and write each block
  453. out into its own <computeroutput>.bz2</computeroutput> file. You
  454. can then use <computeroutput>bzip2 -t</computeroutput> to test
  455. the integrity of the resulting files, and decompress those which
  456. are undamaged.</para>
  457. <para><computeroutput>bzip2recover</computeroutput> takes a
  458. single argument, the name of the damaged file, and writes a
  459. number of files <computeroutput>rec0001file.bz2</computeroutput>,
  460. <computeroutput>rec0002file.bz2</computeroutput>, etc, containing
  461. the extracted blocks. The output filenames are designed so that
  462. the use of wildcards in subsequent processing -- for example,
  463. <computeroutput>bzip2 -dc rec*file.bz2 &#62;
  464. recovered_data</computeroutput> -- lists the files in the correct
  465. order.</para>
  466. <para><computeroutput>bzip2recover</computeroutput> should be of
  467. most use dealing with large <computeroutput>.bz2</computeroutput>
  468. files, as these will contain many blocks. It is clearly futile
  469. to use it on damaged single-block files, since a damaged block
  470. cannot be recovered. If you wish to minimise any potential data
  471. loss through media or transmission errors, you might consider
  472. compressing with a smaller block size.</para>
  473. </sect1>
  474. <sect1 id="performance" xreflabel="PERFORMANCE NOTES">
  475. <title>PERFORMANCE NOTES</title>
  476. <para>The sorting phase of compression gathers together similar
  477. strings in the file. Because of this, files containing very long
  478. runs of repeated symbols, like "aabaabaabaab ..." (repeated
  479. several hundred times) may compress more slowly than normal.
  480. Versions 0.9.5 and above fare much better than previous versions
  481. in this respect. The ratio between worst-case and average-case
  482. compression time is in the region of 10:1. For previous
  483. versions, this figure was more like 100:1. You can use the
  484. <computeroutput>-vvvv</computeroutput> option to monitor progress
  485. in great detail, if you want.</para>
  486. <para>Decompression speed is unaffected by these
  487. phenomena.</para>
  488. <para><computeroutput>bzip2</computeroutput> usually allocates
  489. several megabytes of memory to operate in, and then charges all
  490. over it in a fairly random fashion. This means that performance,
  491. both for compressing and decompressing, is largely determined by
  492. the speed at which your machine can service cache misses.
  493. Because of this, small changes to the code to reduce the miss
  494. rate have been observed to give disproportionately large
  495. performance improvements. I imagine
  496. <computeroutput>bzip2</computeroutput> will perform best on
  497. machines with very large caches.</para>
  498. </sect1>
  499. <sect1 id="caveats" xreflabel="CAVEATS">
  500. <title>CAVEATS</title>
  501. <para>I/O error messages are not as helpful as they could be.
  502. <computeroutput>bzip2</computeroutput> tries hard to detect I/O
  503. errors and exit cleanly, but the details of what the problem is
  504. sometimes seem rather misleading.</para>
  505. <para>This manual page pertains to version &bz-version; of
  506. <computeroutput>bzip2</computeroutput>. Compressed data created by
  507. this version is entirely forwards and backwards compatible with the
  508. previous public releases, versions 0.1pl2, 0.9.0 and 0.9.5, 1.0.0,
  509. 1.0.1, 1.0.2 and 1.0.3, but with the following exception: 0.9.0 and
  510. above can correctly decompress multiple concatenated compressed files.
  511. 0.1pl2 cannot do this; it will stop after decompressing just the first
  512. file in the stream.</para>
  513. <para><computeroutput>bzip2recover</computeroutput> versions
  514. prior to 1.0.2 used 32-bit integers to represent bit positions in
  515. compressed files, so it could not handle compressed files more
  516. than 512 megabytes long. Versions 1.0.2 and above use 64-bit ints
  517. on some platforms which support them (GNU supported targets, and
  518. Windows). To establish whether or not
  519. <computeroutput>bzip2recover</computeroutput> was built with such
  520. a limitation, run it without arguments. In any event you can
  521. build yourself an unlimited version if you can recompile it with
  522. <computeroutput>MaybeUInt64</computeroutput> set to be an
  523. unsigned 64-bit integer.</para>
  524. </sect1>
  525. <sect1 id="author" xreflabel="AUTHOR">
  526. <title>AUTHOR</title>
  527. <para>Julian Seward,
  528. <computeroutput>&bz-email;</computeroutput></para>
  529. <para>The ideas embodied in
  530. <computeroutput>bzip2</computeroutput> are due to (at least) the
  531. following people: Michael Burrows and David Wheeler (for the
  532. block sorting transformation), David Wheeler (again, for the
  533. Huffman coder), Peter Fenwick (for the structured coding model in
  534. the original <computeroutput>bzip</computeroutput>, and many
  535. refinements), and Alistair Moffat, Radford Neal and Ian Witten
  536. (for the arithmetic coder in the original
  537. <computeroutput>bzip</computeroutput>). I am much indebted for
  538. their help, support and advice. See the manual in the source
  539. distribution for pointers to sources of documentation. Christian
  540. von Roques encouraged me to look for faster sorting algorithms,
  541. so as to speed up compression. Bela Lubkin encouraged me to
  542. improve the worst-case compression performance.
  543. Donna Robinson XMLised the documentation.
  544. Many people sent
  545. patches, helped with portability problems, lent machines, gave
  546. advice and were generally helpful.</para>
  547. </sect1>
  548. </chapter>
  549. <chapter id="libprog" xreflabel="Programming with libbzip2">
  550. <title>
  551. Programming with <computeroutput>libbzip2</computeroutput>
  552. </title>
  553. <para>This chapter describes the programming interface to
  554. <computeroutput>libbzip2</computeroutput>.</para>
  555. <para>For general background information, particularly about
  556. memory use and performance aspects, you'd be well advised to read
  557. <xref linkend="using"/> as well.</para>
  558. <sect1 id="top-level" xreflabel="Top-level structure">
  559. <title>Top-level structure</title>
  560. <para><computeroutput>libbzip2</computeroutput> is a flexible
  561. library for compressing and decompressing data in the
  562. <computeroutput>bzip2</computeroutput> data format. Although
  563. packaged as a single entity, it helps to regard the library as
  564. three separate parts: the low level interface, and the high level
  565. interface, and some utility functions.</para>
  566. <para>The structure of
  567. <computeroutput>libbzip2</computeroutput>'s interfaces is similar
  568. to that of Jean-loup Gailly's and Mark Adler's excellent
  569. <computeroutput>zlib</computeroutput> library.</para>
  570. <para>All externally visible symbols have names beginning
  571. <computeroutput>BZ2_</computeroutput>. This is new in version
  572. 1.0. The intention is to minimise pollution of the namespaces of
  573. library clients.</para>
  574. <para>To use any part of the library, you need to
  575. <computeroutput>#include &lt;bzlib.h&gt;</computeroutput>
  576. into your sources.</para>
  577. <sect2 id="ll-summary" xreflabel="Low-level summary">
  578. <title>Low-level summary</title>
  579. <para>This interface provides services for compressing and
  580. decompressing data in memory. There's no provision for dealing
  581. with files, streams or any other I/O mechanisms, just straight
  582. memory-to-memory work. In fact, this part of the library can be
  583. compiled without inclusion of
  584. <computeroutput>stdio.h</computeroutput>, which may be helpful
  585. for embedded applications.</para>
  586. <para>The low-level part of the library has no global variables
  587. and is therefore thread-safe.</para>
  588. <para>Six routines make up the low level interface:
  589. <computeroutput>BZ2_bzCompressInit</computeroutput>,
  590. <computeroutput>BZ2_bzCompress</computeroutput>, and
  591. <computeroutput>BZ2_bzCompressEnd</computeroutput> for
  592. compression, and a corresponding trio
  593. <computeroutput>BZ2_bzDecompressInit</computeroutput>,
  594. <computeroutput>BZ2_bzDecompress</computeroutput> and
  595. <computeroutput>BZ2_bzDecompressEnd</computeroutput> for
  596. decompression. The <computeroutput>*Init</computeroutput>
  597. functions allocate memory for compression/decompression and do
  598. other initialisations, whilst the
  599. <computeroutput>*End</computeroutput> functions close down
  600. operations and release memory.</para>
  601. <para>The real work is done by
  602. <computeroutput>BZ2_bzCompress</computeroutput> and
  603. <computeroutput>BZ2_bzDecompress</computeroutput>. These
  604. compress and decompress data from a user-supplied input buffer to
  605. a user-supplied output buffer. These buffers can be any size;
  606. arbitrary quantities of data are handled by making repeated calls
  607. to these functions. This is a flexible mechanism allowing a
  608. consumer-pull style of activity, or producer-push, or a mixture
  609. of both.</para>
  610. </sect2>
  611. <sect2 id="hl-summary" xreflabel="High-level summary">
  612. <title>High-level summary</title>
  613. <para>This interface provides some handy wrappers around the
  614. low-level interface to facilitate reading and writing
  615. <computeroutput>bzip2</computeroutput> format files
  616. (<computeroutput>.bz2</computeroutput> files). The routines
  617. provide hooks to facilitate reading files in which the
  618. <computeroutput>bzip2</computeroutput> data stream is embedded
  619. within some larger-scale file structure, or where there are
  620. multiple <computeroutput>bzip2</computeroutput> data streams
  621. concatenated end-to-end.</para>
  622. <para>For reading files,
  623. <computeroutput>BZ2_bzReadOpen</computeroutput>,
  624. <computeroutput>BZ2_bzRead</computeroutput>,
  625. <computeroutput>BZ2_bzReadClose</computeroutput> and
  626. <computeroutput>BZ2_bzReadGetUnused</computeroutput> are
  627. supplied. For writing files,
  628. <computeroutput>BZ2_bzWriteOpen</computeroutput>,
  629. <computeroutput>BZ2_bzWrite</computeroutput> and
  630. <computeroutput>BZ2_bzWriteFinish</computeroutput> are
  631. available.</para>
  632. <para>As with the low-level library, no global variables are used
  633. so the library is per se thread-safe. However, if I/O errors
  634. occur whilst reading or writing the underlying compressed files,
  635. you may have to consult <computeroutput>errno</computeroutput> to
  636. determine the cause of the error. In that case, you'd need a C
  637. library which correctly supports
  638. <computeroutput>errno</computeroutput> in a multithreaded
  639. environment.</para>
  640. <para>To make the library a little simpler and more portable,
  641. <computeroutput>BZ2_bzReadOpen</computeroutput> and
  642. <computeroutput>BZ2_bzWriteOpen</computeroutput> require you to
  643. pass them file handles (<computeroutput>FILE*</computeroutput>s)
  644. which have previously been opened for reading or writing
  645. respectively. That avoids portability problems associated with
  646. file operations and file attributes, whilst not being much of an
  647. imposition on the programmer.</para>
  648. </sect2>
  649. <sect2 id="util-fns-summary" xreflabel="Utility functions summary">
  650. <title>Utility functions summary</title>
  651. <para>For very simple needs,
  652. <computeroutput>BZ2_bzBuffToBuffCompress</computeroutput> and
  653. <computeroutput>BZ2_bzBuffToBuffDecompress</computeroutput> are
  654. provided. These compress data in memory from one buffer to
  655. another buffer in a single function call. You should assess
  656. whether these functions fulfill your memory-to-memory
  657. compression/decompression requirements before investing effort in
  658. understanding the more general but more complex low-level
  659. interface.</para>
  660. <para>Yoshioka Tsuneo
  661. (<computeroutput>tsuneo@rr.iij4u.or.jp</computeroutput>) has
  662. contributed some functions to give better
  663. <computeroutput>zlib</computeroutput> compatibility. These
  664. functions are <computeroutput>BZ2_bzopen</computeroutput>,
  665. <computeroutput>BZ2_bzread</computeroutput>,
  666. <computeroutput>BZ2_bzwrite</computeroutput>,
  667. <computeroutput>BZ2_bzflush</computeroutput>,
  668. <computeroutput>BZ2_bzclose</computeroutput>,
  669. <computeroutput>BZ2_bzerror</computeroutput> and
  670. <computeroutput>BZ2_bzlibVersion</computeroutput>. You may find
  671. these functions more convenient for simple file reading and
  672. writing, than those in the high-level interface. These functions
  673. are not (yet) officially part of the library, and are minimally
  674. documented here. If they break, you get to keep all the pieces.
  675. I hope to document them properly when time permits.</para>
  676. <para>Yoshioka also contributed modifications to allow the
  677. library to be built as a Windows DLL.</para>
  678. </sect2>
  679. </sect1>
  680. <sect1 id="err-handling" xreflabel="Error handling">
  681. <title>Error handling</title>
  682. <para>The library is designed to recover cleanly in all
  683. situations, including the worst-case situation of decompressing
  684. random data. I'm not 100% sure that it can always do this, so
  685. you might want to add a signal handler to catch segmentation
  686. violations during decompression if you are feeling especially
  687. paranoid. I would be interested in hearing more about the
  688. robustness of the library to corrupted compressed data.</para>
  689. <para>Version 1.0.3 more robust in this respect than any
  690. previous version. Investigations with Valgrind (a tool for detecting
  691. problems with memory management) indicate
  692. that, at least for the few files I tested, all single-bit errors
  693. in the decompressed data are caught properly, with no
  694. segmentation faults, no uses of uninitialised data, no out of
  695. range reads or writes, and no infinite looping in the decompressor.
  696. So it's certainly pretty robust, although
  697. I wouldn't claim it to be totally bombproof.</para>
  698. <para>The file <computeroutput>bzlib.h</computeroutput> contains
  699. all definitions needed to use the library. In particular, you
  700. should definitely not include
  701. <computeroutput>bzlib_private.h</computeroutput>.</para>
  702. <para>In <computeroutput>bzlib.h</computeroutput>, the various
  703. return values are defined. The following list is not intended as
  704. an exhaustive description of the circumstances in which a given
  705. value may be returned -- those descriptions are given later.
  706. Rather, it is intended to convey the rough meaning of each return
  707. value. The first five actions are normal and not intended to
  708. denote an error situation.</para>
  709. <variablelist>
  710. <varlistentry>
  711. <term><computeroutput>BZ_OK</computeroutput></term>
  712. <listitem><para>The requested action was completed
  713. successfully.</para></listitem>
  714. </varlistentry>
  715. <varlistentry>
  716. <term><computeroutput>BZ_RUN_OK, BZ_FLUSH_OK,
  717. BZ_FINISH_OK</computeroutput></term>
  718. <listitem><para>In
  719. <computeroutput>BZ2_bzCompress</computeroutput>, the requested
  720. flush/finish/nothing-special action was completed
  721. successfully.</para></listitem>
  722. </varlistentry>
  723. <varlistentry>
  724. <term><computeroutput>BZ_STREAM_END</computeroutput></term>
  725. <listitem><para>Compression of data was completed, or the
  726. logical stream end was detected during
  727. decompression.</para></listitem>
  728. </varlistentry>
  729. </variablelist>
  730. <para>The following return values indicate an error of some
  731. kind.</para>
  732. <variablelist>
  733. <varlistentry>
  734. <term><computeroutput>BZ_CONFIG_ERROR</computeroutput></term>
  735. <listitem><para>Indicates that the library has been improperly
  736. compiled on your platform -- a major configuration error.
  737. Specifically, it means that
  738. <computeroutput>sizeof(char)</computeroutput>,
  739. <computeroutput>sizeof(short)</computeroutput> and
  740. <computeroutput>sizeof(int)</computeroutput> are not 1, 2 and
  741. 4 respectively, as they should be. Note that the library
  742. should still work properly on 64-bit platforms which follow
  743. the LP64 programming model -- that is, where
  744. <computeroutput>sizeof(long)</computeroutput> and
  745. <computeroutput>sizeof(void*)</computeroutput> are 8. Under
  746. LP64, <computeroutput>sizeof(int)</computeroutput> is still 4,
  747. so <computeroutput>libbzip2</computeroutput>, which doesn't
  748. use the <computeroutput>long</computeroutput> type, is
  749. OK.</para></listitem>
  750. </varlistentry>
  751. <varlistentry>
  752. <term><computeroutput>BZ_SEQUENCE_ERROR</computeroutput></term>
  753. <listitem><para>When using the library, it is important to call
  754. the functions in the correct sequence and with data structures
  755. (buffers etc) in the correct states.
  756. <computeroutput>libbzip2</computeroutput> checks as much as it
  757. can to ensure this is happening, and returns
  758. <computeroutput>BZ_SEQUENCE_ERROR</computeroutput> if not.
  759. Code which complies precisely with the function semantics, as
  760. detailed below, should never receive this value; such an event
  761. denotes buggy code which you should
  762. investigate.</para></listitem>
  763. </varlistentry>
  764. <varlistentry>
  765. <term><computeroutput>BZ_PARAM_ERROR</computeroutput></term>
  766. <listitem><para>Returned when a parameter to a function call is
  767. out of range or otherwise manifestly incorrect. As with
  768. <computeroutput>BZ_SEQUENCE_ERROR</computeroutput>, this
  769. denotes a bug in the client code. The distinction between
  770. <computeroutput>BZ_PARAM_ERROR</computeroutput> and
  771. <computeroutput>BZ_SEQUENCE_ERROR</computeroutput> is a bit
  772. hazy, but still worth making.</para></listitem>
  773. </varlistentry>
  774. <varlistentry>
  775. <term><computeroutput>BZ_MEM_ERROR</computeroutput></term>
  776. <listitem><para>Returned when a request to allocate memory
  777. failed. Note that the quantity of memory needed to decompress
  778. a stream cannot be determined until the stream's header has
  779. been read. So
  780. <computeroutput>BZ2_bzDecompress</computeroutput> and
  781. <computeroutput>BZ2_bzRead</computeroutput> may return
  782. <computeroutput>BZ_MEM_ERROR</computeroutput> even though some
  783. of the compressed data has been read. The same is not true
  784. for compression; once
  785. <computeroutput>BZ2_bzCompressInit</computeroutput> or
  786. <computeroutput>BZ2_bzWriteOpen</computeroutput> have
  787. successfully completed,
  788. <computeroutput>BZ_MEM_ERROR</computeroutput> cannot
  789. occur.</para></listitem>
  790. </varlistentry>
  791. <varlistentry>
  792. <term><computeroutput>BZ_DATA_ERROR</computeroutput></term>
  793. <listitem><para>Returned when a data integrity error is
  794. detected during decompression. Most importantly, this means
  795. when stored and computed CRCs for the data do not match. This
  796. value is also returned upon detection of any other anomaly in
  797. the compressed data.</para></listitem>
  798. </varlistentry>
  799. <varlistentry>
  800. <term><computeroutput>BZ_DATA_ERROR_MAGIC</computeroutput></term>
  801. <listitem><para>As a special case of
  802. <computeroutput>BZ_DATA_ERROR</computeroutput>, it is
  803. sometimes useful to know when the compressed stream does not
  804. start with the correct magic bytes (<computeroutput>'B' 'Z'
  805. 'h'</computeroutput>).</para></listitem>
  806. </varlistentry>
  807. <varlistentry>
  808. <term><computeroutput>BZ_IO_ERROR</computeroutput></term>
  809. <listitem><para>Returned by
  810. <computeroutput>BZ2_bzRead</computeroutput> and
  811. <computeroutput>BZ2_bzWrite</computeroutput> when there is an
  812. error reading or writing in the compressed file, and by
  813. <computeroutput>BZ2_bzReadOpen</computeroutput> and
  814. <computeroutput>BZ2_bzWriteOpen</computeroutput> for attempts
  815. to use a file for which the error indicator (viz,
  816. <computeroutput>ferror(f)</computeroutput>) is set. On
  817. receipt of <computeroutput>BZ_IO_ERROR</computeroutput>, the
  818. caller should consult <computeroutput>errno</computeroutput>
  819. and/or <computeroutput>perror</computeroutput> to acquire
  820. operating-system specific information about the
  821. problem.</para></listitem>
  822. </varlistentry>
  823. <varlistentry>
  824. <term><computeroutput>BZ_UNEXPECTED_EOF</computeroutput></term>
  825. <listitem><para>Returned by
  826. <computeroutput>BZ2_bzRead</computeroutput> when the
  827. compressed file finishes before the logical end of stream is
  828. detected.</para></listitem>
  829. </varlistentry>
  830. <varlistentry>
  831. <term><computeroutput>BZ_OUTBUFF_FULL</computeroutput></term>
  832. <listitem><para>Returned by
  833. <computeroutput>BZ2_bzBuffToBuffCompress</computeroutput> and
  834. <computeroutput>BZ2_bzBuffToBuffDecompress</computeroutput> to
  835. indicate that the output data will not fit into the output
  836. buffer provided.</para></listitem>
  837. </varlistentry>
  838. </variablelist>
  839. </sect1>
  840. <sect1 id="low-level" xreflabel=">Low-level interface">
  841. <title>Low-level interface</title>
  842. <sect2 id="bzcompress-init" xreflabel="BZ2_bzCompressInit">
  843. <title><computeroutput>BZ2_bzCompressInit</computeroutput></title>
  844. <programlisting>
  845. typedef struct {
  846. char *next_in;
  847. unsigned int avail_in;
  848. unsigned int total_in_lo32;
  849. unsigned int total_in_hi32;
  850. char *next_out;
  851. unsigned int avail_out;
  852. unsigned int total_out_lo32;
  853. unsigned int total_out_hi32;
  854. void *state;
  855. void *(*bzalloc)(void *,int,int);
  856. void (*bzfree)(void *,void *);
  857. void *opaque;
  858. } bz_stream;
  859. int BZ2_bzCompressInit ( bz_stream *strm,
  860. int blockSize100k,
  861. int verbosity,
  862. int workFactor );
  863. </programlisting>
  864. <para>Prepares for compression. The
  865. <computeroutput>bz_stream</computeroutput> structure holds all
  866. data pertaining to the compression activity. A
  867. <computeroutput>bz_stream</computeroutput> structure should be
  868. allocated and initialised prior to the call. The fields of
  869. <computeroutput>bz_stream</computeroutput> comprise the entirety
  870. of the user-visible data. <computeroutput>state</computeroutput>
  871. is a pointer to the private data structures required for
  872. compression.</para>
  873. <para>Custom memory allocators are supported, via fields
  874. <computeroutput>bzalloc</computeroutput>,
  875. <computeroutput>bzfree</computeroutput>, and
  876. <computeroutput>opaque</computeroutput>. The value
  877. <computeroutput>opaque</computeroutput> is passed to as the first
  878. argument to all calls to <computeroutput>bzalloc</computeroutput>
  879. and <computeroutput>bzfree</computeroutput>, but is otherwise
  880. ignored by the library. The call <computeroutput>bzalloc (
  881. opaque, n, m )</computeroutput> is expected to return a pointer
  882. <computeroutput>p</computeroutput> to <computeroutput>n *
  883. m</computeroutput> bytes of memory, and <computeroutput>bzfree (
  884. opaque, p )</computeroutput> should free that memory.</para>
  885. <para>If you don't want to use a custom memory allocator, set
  886. <computeroutput>bzalloc</computeroutput>,
  887. <computeroutput>bzfree</computeroutput> and
  888. <computeroutput>opaque</computeroutput> to
  889. <computeroutput>NULL</computeroutput>, and the library will then
  890. use the standard <computeroutput>malloc</computeroutput> /
  891. <computeroutput>free</computeroutput> routines.</para>
  892. <para>Before calling
  893. <computeroutput>BZ2_bzCompressInit</computeroutput>, fields
  894. <computeroutput>bzalloc</computeroutput>,
  895. <computeroutput>bzfree</computeroutput> and
  896. <computeroutput>opaque</computeroutput> should be filled
  897. appropriately, as just described. Upon return, the internal
  898. state will have been allocated and initialised, and
  899. <computeroutput>total_in_lo32</computeroutput>,
  900. <computeroutput>total_in_hi32</computeroutput>,
  901. <computeroutput>total_out_lo32</computeroutput> and
  902. <computeroutput>total_out_hi32</computeroutput> will have been
  903. set to zero. These four fields are used by the library to inform
  904. the caller of the total amount of data passed into and out of the
  905. library, respectively. You should not try to change them. As of
  906. version 1.0, 64-bit counts are maintained, even on 32-bit
  907. platforms, using the <computeroutput>_hi32</computeroutput>
  908. fields to store the upper 32 bits of the count. So, for example,
  909. the total amount of data in is <computeroutput>(total_in_hi32
  910. &#60;&#60; 32) + total_in_lo32</computeroutput>.</para>
  911. <para>Parameter <computeroutput>blockSize100k</computeroutput>
  912. specifies the block size to be used for compression. It should
  913. be a value between 1 and 9 inclusive, and the actual block size
  914. used is 100000 x this figure. 9 gives the best compression but
  915. takes most memory.</para>
  916. <para>Parameter <computeroutput>verbosity</computeroutput> should
  917. be set to a number between 0 and 4 inclusive. 0 is silent, and
  918. greater numbers give increasingly verbose monitoring/debugging
  919. output. If the library has been compiled with
  920. <computeroutput>-DBZ_NO_STDIO</computeroutput>, no such output
  921. will appear for any verbosity setting.</para>
  922. <para>Parameter <computeroutput>workFactor</computeroutput>
  923. controls how the compression phase behaves when presented with
  924. worst case, highly repetitive, input data. If compression runs
  925. into difficulties caused by repetitive data, the library switches
  926. from the standard sorting algorithm to a fallback algorithm. The
  927. fallback is slower than the standard algorithm by perhaps a
  928. factor of three, but always behaves reasonably, no matter how bad
  929. the input.</para>
  930. <para>Lower values of <computeroutput>workFactor</computeroutput>
  931. reduce the amount of effort the standard algorithm will expend
  932. before resorting to the fallback. You should set this parameter
  933. carefully; too low, and many inputs will be handled by the
  934. fallback algorithm and so compress rather slowly, too high, and
  935. your average-to-worst case compression times can become very
  936. large. The default value of 30 gives reasonable behaviour over a
  937. wide range of circumstances.</para>
  938. <para>Allowable values range from 0 to 250 inclusive. 0 is a
  939. special case, equivalent to using the default value of 30.</para>
  940. <para>Note that the compressed output generated is the same
  941. regardless of whether or not the fallback algorithm is
  942. used.</para>
  943. <para>Be aware also that this parameter may disappear entirely in
  944. future versions of the library. In principle it should be
  945. possible to devise a good way to automatically choose which
  946. algorithm to use. Such a mechanism would render the parameter
  947. obsolete.</para>
  948. <para>Possible return values:</para>
  949. <programlisting>
  950. BZ_CONFIG_ERROR
  951. if the library has been mis-compiled
  952. BZ_PARAM_ERROR
  953. if strm is NULL
  954. or blockSize < 1 or blockSize > 9
  955. or verbosity < 0 or verbosity > 4
  956. or workFactor < 0 or workFactor > 250
  957. BZ_MEM_ERROR
  958. if not enough memory is available
  959. BZ_OK
  960. otherwise
  961. </programlisting>
  962. <para>Allowable next actions:</para>
  963. <programlisting>
  964. BZ2_bzCompress
  965. if BZ_OK is returned
  966. no specific action needed in case of error
  967. </programlisting>
  968. </sect2>
  969. <sect2 id="bzCompress" xreflabel="BZ2_bzCompress">
  970. <title><computeroutput>BZ2_bzCompress</computeroutput></title>
  971. <programlisting>
  972. int BZ2_bzCompress ( bz_stream *strm, int action );
  973. </programlisting>
  974. <para>Provides more input and/or output buffer space for the
  975. library. The caller maintains input and output buffers, and
  976. calls <computeroutput>BZ2_bzCompress</computeroutput> to transfer
  977. data between them.</para>
  978. <para>Before each call to
  979. <computeroutput>BZ2_bzCompress</computeroutput>,
  980. <computeroutput>next_in</computeroutput> should point at the data
  981. to be compressed, and <computeroutput>avail_in</computeroutput>
  982. should indicate how many bytes the library may read.
  983. <computeroutput>BZ2_bzCompress</computeroutput> updates
  984. <computeroutput>next_in</computeroutput>,
  985. <computeroutput>avail_in</computeroutput> and
  986. <computeroutput>total_in</computeroutput> to reflect the number
  987. of bytes it has read.</para>
  988. <para>Similarly, <computeroutput>next_out</computeroutput> should
  989. point to a buffer in which the compressed data is to be placed,
  990. with <computeroutput>avail_out</computeroutput> indicating how
  991. much output space is available.
  992. <computeroutput>BZ2_bzCompress</computeroutput> updates
  993. <computeroutput>next_out</computeroutput>,
  994. <computeroutput>avail_out</computeroutput> and
  995. <computeroutput>total_out</computeroutput> to reflect the number
  996. of bytes output.</para>
  997. <para>You may provide and remove as little or as much data as you
  998. like on each call of
  999. <computeroutput>BZ2_bzCompress</computeroutput>. In the limit,
  1000. it is acceptable to supply and remove data one byte at a time,
  1001. although this would be terribly inefficient. You should always
  1002. ensure that at least one byte of output space is available at
  1003. each call.</para>
  1004. <para>A second purpose of
  1005. <computeroutput>BZ2_bzCompress</computeroutput> is to request a
  1006. change of mode of the compressed stream.</para>
  1007. <para>Conceptually, a compressed stream can be in one of four
  1008. states: IDLE, RUNNING, FLUSHING and FINISHING. Before
  1009. initialisation
  1010. (<computeroutput>BZ2_bzCompressInit</computeroutput>) and after
  1011. termination (<computeroutput>BZ2_bzCompressEnd</computeroutput>),
  1012. a stream is regarded as IDLE.</para>
  1013. <para>Upon initialisation
  1014. (<computeroutput>BZ2_bzCompressInit</computeroutput>), the stream
  1015. is placed in the RUNNING state. Subsequent calls to
  1016. <computeroutput>BZ2_bzCo