/StormLib/stormlib/bzip2/manual.html

http://ghostcb.googlecode.com/ · HTML · 2540 lines · 2509 code · 31 blank · 0 comment · 0 complexity · 9363d211e9b4a49a3f325c1d65e8adec MD5 · raw file

Large files are truncated click here to view the full file

    

  1. <html>
    2. 

  2. <head>
    3. 

  3. <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
    4. 

  4. <title>bzip2 and libbzip2, version 1.0.5</title>
    5. 

  5. <meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
    6. 

  6. <style type="text/css" media="screen">/* Colours:
    7. 

  7. #74240f  dark brown      h1, h2, h3, h4
    8. 

  8. #336699  medium blue     links
    9. 

  9. #339999  turquoise       link hover colour
    10. 

  10. #202020  almost black    general text
    11. 

  11. #761596  purple          md5sum text
    12. 

  12. #626262  dark gray       pre border
    13. 

  13. #eeeeee  very light gray pre background
    14. 

  14. #f2f2f9  very light blue nav table background
    15. 

  15. #3366cc  medium blue     nav table border
    16. 

  16. */
    17. 

  17. 

  18. a, a:link, a:visited, a:active { color: #336699; }
    19. 

  19. a:hover { color: #339999; }
    20. 

  20. 

  21. body { font: 80%/126% sans-serif; }
    22. 

  22. h1, h2, h3, h4 { color: #74240f; }
    23. 

  23. 

  24. dt { color: #336699; font-weight: bold }
    25. 

  25. dd { 
    26. 

  26.  margin-left: 1.5em; 
    27. 

  27.  padding-bottom: 0.8em;
    28. 

  28. }
    29. 

  29. 

  30. /* -- ruler -- */
    31. 

  31. div.hr_blue { 
    32. 

  32.   height:  3px; 
    33. 

  33.   background:#ffffff url("/images/hr_blue.png") repeat-x; }
    34. 

  34. div.hr_blue hr { display:none; }
    35. 

  35. 

  36. /* release styles */
    37. 

  37. #release p { margin-top: 0.4em; }
    38. 

  38. #release .md5sum { color: #761596; }
    39. 

  39. 

  40. 

  41. /* ------ styles for docs|manuals|howto ------ */
    42. 

  42. /* -- lists -- */
    43. 

  43. ul  { 
    44. 

  44.  margin:     0px 4px 16px 16px;
    45. 

  45.  padding:    0px;
    46. 

  46.  list-style: url("/images/li-blue.png"); 
    47. 

  47. }
    48. 

  48. ul li { 
    49. 

  49.  margin-bottom: 10px;
    50. 

  50. }
    51. 

  51. ul ul	{ 
    52. 

  52.  list-style-type:  none; 
    53. 

  53.  list-style-image: none; 
    54. 

  54.  margin-left:      0px; 
    55. 

  55. }
    56. 

  56. 

  57. /* header / footer nav tables */
    58. 

  58. table.nav {
    59. 

  59.  border:     solid 1px #3366cc;
    60. 

  60.  background: #f2f2f9;
    61. 

  61.  background-color: #f2f2f9;
    62. 

  62.  margin-bottom: 0.5em;
    63. 

  63. }
    64. 

  64. /* don't have underlined links in chunked nav menus */
    65. 

  65. table.nav a { text-decoration: none; }
    66. 

  66. table.nav a:hover { text-decoration: underline; }
    67. 

  67. table.nav td { font-size: 85%; }
    68. 

  68. 

  69. code, tt, pre { font-size: 120%; }
    70. 

  70. code, tt { color: #761596; }
    71. 

  71. 

  72. div.literallayout, pre.programlisting, pre.screen {
    73. 

  73.  color:      #000000;
    74. 

  74.  padding:    0.5em;
    75. 

  75.  background: #eeeeee;
    76. 

  76.  border:     1px solid #626262;
    77. 

  77.  background-color: #eeeeee;
    78. 

  78.  margin: 4px 0px 4px 0px; 
    79. 

  79. }
    80. 

  80. </style>
    81. 

  81. </head>
    82. 

  82. <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en">
    83. 

  83. <div class="titlepage">
    84. 

  84. <div>
    85. 

  85. <div><h1 class="title">
    86. 

  86. <a name="userman"></a>bzip2 and libbzip2, version 1.0.5</h1></div>
    87. 

  87. <div><h2 class="subtitle">A program and library for data compression</h2></div>
    88. 

  88. <div><div class="authorgroup"><div class="author">
    89. 

  89. <h3 class="author">
    90. 

  90. <span class="firstname">Julian</span> <span class="surname">Seward</span>
    91. 

  91. </h3>
    92. 

  92. <div class="affiliation"><span class="orgname">http://www.bzip.org<br></span></div>
    93. 

  93. </div></div></div>
    94. 

  94. <div><p class="releaseinfo">Version 1.0.5 of 10 December 2007</p></div>
    95. 

  95. <div><p class="copyright">Copyright Š 1996-2007 Julian Seward</p></div>
    96. 

  96. <div><div class="legalnotice">
    97. 

  97. <a name="id2499833"></a><p>This program, <code class="computeroutput">bzip2</code>, the
    98. 

  98.   associated library <code class="computeroutput">libbzip2</code>, and
    99. 

  99.   all documentation, are copyright Š 1996-2007 Julian Seward.
    100. 

  100.   All rights reserved.</p>
    101. 

  101. <p>Redistribution and use in source and binary forms, with
    102. 

  102.   or without modification, are permitted provided that the
    103. 

  103.   following conditions are met:</p>
    104. 

  104. <div class="itemizedlist"><ul type="bullet">
    105. 

  105. <li style="list-style-type: disc"><p>Redistributions of source code must retain the
    106. 

  106.    above copyright notice, this list of conditions and the
    107. 

  107.    following disclaimer.</p></li>
    108. 

  108. <li style="list-style-type: disc"><p>The origin of this software must not be
    109. 

  109.    misrepresented; you must not claim that you wrote the original
    110. 

  110.    software.  If you use this software in a product, an
    111. 

  111.    acknowledgment in the product documentation would be
    112. 

  112.    appreciated but is not required.</p></li>
    113. 

  113. <li style="list-style-type: disc"><p>Altered source versions must be plainly marked
    114. 

  114.    as such, and must not be misrepresented as being the original
    115. 

  115.    software.</p></li>
    116. 

  116. <li style="list-style-type: disc"><p>The name of the author may not be used to
    117. 

  117.    endorse or promote products derived from this software without
    118. 

  118.    specific prior written permission.</p></li>
    119. 

  119. </ul></div>
    120. 

  120. <p>THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY
    121. 

  121.   EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    122. 

  122.   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
    123. 

  123.   PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
    124. 

  124.   AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    125. 

  125.   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
    126. 

  126.   TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
    127. 

  127.   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
    128. 

  128.   ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
    129. 

  129.   LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
    130. 

  130.   IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
    131. 

  131.   THE POSSIBILITY OF SUCH DAMAGE.</p>
    132. 

  132. <p>PATENTS: To the best of my knowledge,
    133. 

  133.  <code class="computeroutput">bzip2</code> and
    134. 

  134.  <code class="computeroutput">libbzip2</code> do not use any patented
    135. 

  135.  algorithms.  However, I do not have the resources to carry
    136. 

  136.  out a patent search.  Therefore I cannot give any guarantee of
    137. 

  137.  the above statement.
    138. 

  138.  </p>
    139. 

  139. </div></div>
    140. 

  140. </div>
    141. 

  141. <hr>
    142. 

  142. </div>
    143. 

  143. <div class="toc">
    144. 

  144. <p><b>Table of Contents</b></p>
    145. 

  145. <dl>
    146. 

  146. <dt><span class="chapter"><a href="#intro">1. Introduction</a></span></dt>
    147. 

  147. <dt><span class="chapter"><a href="#using">2. How to use bzip2</a></span></dt>
    148. 

  148. <dd><dl>
    149. 

  149. <dt><span class="sect1"><a href="#name">2.1. NAME</a></span></dt>
    150. 

  150. <dt><span class="sect1"><a href="#synopsis">2.2. SYNOPSIS</a></span></dt>
    151. 

  151. <dt><span class="sect1"><a href="#description">2.3. DESCRIPTION</a></span></dt>
    152. 

  152. <dt><span class="sect1"><a href="#options">2.4. OPTIONS</a></span></dt>
    153. 

  153. <dt><span class="sect1"><a href="#memory-management">2.5. MEMORY MANAGEMENT</a></span></dt>
    154. 

  154. <dt><span class="sect1"><a href="#recovering">2.6. RECOVERING DATA FROM DAMAGED FILES</a></span></dt>
    155. 

  155. <dt><span class="sect1"><a href="#performance">2.7. PERFORMANCE NOTES</a></span></dt>
    156. 

  156. <dt><span class="sect1"><a href="#caveats">2.8. CAVEATS</a></span></dt>
    157. 

  157. <dt><span class="sect1"><a href="#author">2.9. AUTHOR</a></span></dt>
    158. 

  158. </dl></dd>
    159. 

  159. <dt><span class="chapter"><a href="#libprog">3. 
    160. 

  160. Programming with <code class="computeroutput">libbzip2</code>
    161. 

  161. </a></span></dt>
    162. 

  162. <dd><dl>
    163. 

  163. <dt><span class="sect1"><a href="#top-level">3.1. Top-level structure</a></span></dt>
    164. 

  164. <dd><dl>
    165. 

  165. <dt><span class="sect2"><a href="#ll-summary">3.1.1. Low-level summary</a></span></dt>
    166. 

  166. <dt><span class="sect2"><a href="#hl-summary">3.1.2. High-level summary</a></span></dt>
    167. 

  167. <dt><span class="sect2"><a href="#util-fns-summary">3.1.3. Utility functions summary</a></span></dt>
    168. 

  168. </dl></dd>
    169. 

  169. <dt><span class="sect1"><a href="#err-handling">3.2. Error handling</a></span></dt>
    170. 

  170. <dt><span class="sect1"><a href="#low-level">3.3. Low-level interface</a></span></dt>
    171. 

  171. <dd><dl>
    172. 

  172. <dt><span class="sect2"><a href="#bzcompress-init">3.3.1. <code class="computeroutput">BZ2_bzCompressInit</code></a></span></dt>
    173. 

  173. <dt><span class="sect2"><a href="#bzCompress">3.3.2. <code class="computeroutput">BZ2_bzCompress</code></a></span></dt>
    174. 

  174. <dt><span class="sect2"><a href="#bzCompress-end">3.3.3. <code class="computeroutput">BZ2_bzCompressEnd</code></a></span></dt>
    175. 

  175. <dt><span class="sect2"><a href="#bzDecompress-init">3.3.4. <code class="computeroutput">BZ2_bzDecompressInit</code></a></span></dt>
    176. 

  176. <dt><span class="sect2"><a href="#bzDecompress">3.3.5. <code class="computeroutput">BZ2_bzDecompress</code></a></span></dt>
    177. 

  177. <dt><span class="sect2"><a href="#bzDecompress-end">3.3.6. <code class="computeroutput">BZ2_bzDecompressEnd</code></a></span></dt>
    178. 

  178. </dl></dd>
    179. 

  179. <dt><span class="sect1"><a href="#hl-interface">3.4. High-level interface</a></span></dt>
    180. 

  180. <dd><dl>
    181. 

  181. <dt><span class="sect2"><a href="#bzreadopen">3.4.1. <code class="computeroutput">BZ2_bzReadOpen</code></a></span></dt>
    182. 

  182. <dt><span class="sect2"><a href="#bzread">3.4.2. <code class="computeroutput">BZ2_bzRead</code></a></span></dt>
    183. 

  183. <dt><span class="sect2"><a href="#bzreadgetunused">3.4.3. <code class="computeroutput">BZ2_bzReadGetUnused</code></a></span></dt>
    184. 

  184. <dt><span class="sect2"><a href="#bzreadclose">3.4.4. <code class="computeroutput">BZ2_bzReadClose</code></a></span></dt>
    185. 

  185. <dt><span class="sect2"><a href="#bzwriteopen">3.4.5. <code class="computeroutput">BZ2_bzWriteOpen</code></a></span></dt>
    186. 

  186. <dt><span class="sect2"><a href="#bzwrite">3.4.6. <code class="computeroutput">BZ2_bzWrite</code></a></span></dt>
    187. 

  187. <dt><span class="sect2"><a href="#bzwriteclose">3.4.7. <code class="computeroutput">BZ2_bzWriteClose</code></a></span></dt>
    188. 

  188. <dt><span class="sect2"><a href="#embed">3.4.8. Handling embedded compressed data streams</a></span></dt>
    189. 

  189. <dt><span class="sect2"><a href="#std-rdwr">3.4.9. Standard file-reading/writing code</a></span></dt>
    190. 

  190. </dl></dd>
    191. 

  191. <dt><span class="sect1"><a href="#util-fns">3.5. Utility functions</a></span></dt>
    192. 

  192. <dd><dl>
    193. 

  193. <dt><span class="sect2"><a href="#bzbufftobuffcompress">3.5.1. <code class="computeroutput">BZ2_bzBuffToBuffCompress</code></a></span></dt>
    194. 

  194. <dt><span class="sect2"><a href="#bzbufftobuffdecompress">3.5.2. <code class="computeroutput">BZ2_bzBuffToBuffDecompress</code></a></span></dt>
    195. 

  195. </dl></dd>
    196. 

  196. <dt><span class="sect1"><a href="#zlib-compat">3.6. <code class="computeroutput">zlib</code> compatibility functions</a></span></dt>
    197. 

  197. <dt><span class="sect1"><a href="#stdio-free">3.7. Using the library in a <code class="computeroutput">stdio</code>-free environment</a></span></dt>
    198. 

  198. <dd><dl>
    199. 

  199. <dt><span class="sect2"><a href="#stdio-bye">3.7.1. Getting rid of <code class="computeroutput">stdio</code></a></span></dt>
    200. 

  200. <dt><span class="sect2"><a href="#critical-error">3.7.2. Critical error handling</a></span></dt>
    201. 

  201. </dl></dd>
    202. 

  202. <dt><span class="sect1"><a href="#win-dll">3.8. Making a Windows DLL</a></span></dt>
    203. 

  203. </dl></dd>
    204. 

  204. <dt><span class="chapter"><a href="#misc">4. Miscellanea</a></span></dt>
    205. 

  205. <dd><dl>
    206. 

  206. <dt><span class="sect1"><a href="#limits">4.1. Limitations of the compressed file format</a></span></dt>
    207. 

  207. <dt><span class="sect1"><a href="#port-issues">4.2. Portability issues</a></span></dt>
    208. 

  208. <dt><span class="sect1"><a href="#bugs">4.3. Reporting bugs</a></span></dt>
    209. 

  209. <dt><span class="sect1"><a href="#package">4.4. Did you get the right package?</a></span></dt>
    210. 

  210. <dt><span class="sect1"><a href="#reading">4.5. Further Reading</a></span></dt>
    211. 

  211. </dl></dd>
    212. 

  212. </dl>
    213. 

  213. </div>
    214. 

  214. <div class="chapter" lang="en">
    215. 

  215. <div class="titlepage"><div><div><h2 class="title">
    216. 

  216. <a name="intro"></a>1. Introduction</h2></div></div></div>
    217. 

  217. <p><code class="computeroutput">bzip2</code> compresses files
    218. 

  218. using the Burrows-Wheeler block-sorting text compression
    219. 

  219. algorithm, and Huffman coding.  Compression is generally
    220. 

  220. considerably better than that achieved by more conventional
    221. 

  221. LZ77/LZ78-based compressors, and approaches the performance of
    222. 

  222. the PPM family of statistical compressors.</p>
    223. 

  223. <p><code class="computeroutput">bzip2</code> is built on top of
    224. 

  224. <code class="computeroutput">libbzip2</code>, a flexible library for
    225. 

  225. handling compressed data in the
    226. 

  226. <code class="computeroutput">bzip2</code> format.  This manual
    227. 

  227. describes both how to use the program and how to work with the
    228. 

  228. library interface.  Most of the manual is devoted to this
    229. 

  229. library, not the program, which is good news if your interest is
    230. 

  230. only in the program.</p>
    231. 

  231. <div class="itemizedlist"><ul type="bullet">
    232. 

  232. <li style="list-style-type: disc"><p><a href="#using">How to use bzip2</a> describes how to use
    233. 

  233.  <code class="computeroutput">bzip2</code>; this is the only part
    234. 

  234.  you need to read if you just want to know how to operate the
    235. 

  235.  program.</p></li>
    236. 

  236. <li style="list-style-type: disc"><p><a href="#libprog">Programming with libbzip2</a> describes the
    237. 

  237.  programming interfaces in detail, and</p></li>
    238. 

  238. <li style="list-style-type: disc"><p><a href="#misc">Miscellanea</a> records some
    239. 

  239.  miscellaneous notes which I thought ought to be recorded
    240. 

  240.  somewhere.</p></li>
    241. 

  241. </ul></div>
    242. 

  242. </div>
    243. 

  243. <div class="chapter" lang="en">
    244. 

  244. <div class="titlepage"><div><div><h2 class="title">
    245. 

  245. <a name="using"></a>2. How to use bzip2</h2></div></div></div>
    246. 

  246. <div class="toc">
    247. 

  247. <p><b>Table of Contents</b></p>
    248. 

  248. <dl>
    249. 

  249. <dt><span class="sect1"><a href="#name">2.1. NAME</a></span></dt>
    250. 

  250. <dt><span class="sect1"><a href="#synopsis">2.2. SYNOPSIS</a></span></dt>
    251. 

  251. <dt><span class="sect1"><a href="#description">2.3. DESCRIPTION</a></span></dt>
    252. 

  252. <dt><span class="sect1"><a href="#options">2.4. OPTIONS</a></span></dt>
    253. 

  253. <dt><span class="sect1"><a href="#memory-management">2.5. MEMORY MANAGEMENT</a></span></dt>
    254. 

  254. <dt><span class="sect1"><a href="#recovering">2.6. RECOVERING DATA FROM DAMAGED FILES</a></span></dt>
    255. 

  255. <dt><span class="sect1"><a href="#performance">2.7. PERFORMANCE NOTES</a></span></dt>
    256. 

  256. <dt><span class="sect1"><a href="#caveats">2.8. CAVEATS</a></span></dt>
    257. 

  257. <dt><span class="sect1"><a href="#author">2.9. AUTHOR</a></span></dt>
    258. 

  258. </dl>
    259. 

  259. </div>
    260. 

  260. <p>This chapter contains a copy of the
    261. 

  261. <code class="computeroutput">bzip2</code> man page, and nothing
    262. 

  262. else.</p>
    263. 

  263. <div class="sect1" lang="en">
    264. 

  264. <div class="titlepage"><div><div><h2 class="title" style="clear: both">
    265. 

  265. <a name="name"></a>2.1. NAME</h2></div></div></div>
    266. 

  266. <div class="itemizedlist"><ul type="bullet">
    267. 

  267. <li style="list-style-type: disc"><p><code class="computeroutput">bzip2</code>,
    268. 

  268.   <code class="computeroutput">bunzip2</code> - a block-sorting file
    269. 

  269.   compressor, v1.0.4</p></li>
    270. 

  270. <li style="list-style-type: disc"><p><code class="computeroutput">bzcat</code> -
    271. 

  271.    decompresses files to stdout</p></li>
    272. 

  272. <li style="list-style-type: disc"><p><code class="computeroutput">bzip2recover</code> -
    273. 

  273.    recovers data from damaged bzip2 files</p></li>
    274. 

  274. </ul></div>
    275. 

  275. </div>
    276. 

  276. <div class="sect1" lang="en">
    277. 

  277. <div class="titlepage"><div><div><h2 class="title" style="clear: both">
    278. 

  278. <a name="synopsis"></a>2.2. SYNOPSIS</h2></div></div></div>
    279. 

  279. <div class="itemizedlist"><ul type="bullet">
    280. 

  280. <li style="list-style-type: disc"><p><code class="computeroutput">bzip2</code> [
    281. 

  281.   -cdfkqstvzVL123456789 ] [ filenames ...  ]</p></li>
    282. 

  282. <li style="list-style-type: disc"><p><code class="computeroutput">bunzip2</code> [
    283. 

  283.   -fkvsVL ] [ filenames ...  ]</p></li>
    284. 

  284. <li style="list-style-type: disc"><p><code class="computeroutput">bzcat</code> [ -s ] [
    285. 

  285.   filenames ...  ]</p></li>
    286. 

  286. <li style="list-style-type: disc"><p><code class="computeroutput">bzip2recover</code>
    287. 

  287.   filename</p></li>
    288. 

  288. </ul></div>
    289. 

  289. </div>
    290. 

  290. <div class="sect1" lang="en">
    291. 

  291. <div class="titlepage"><div><div><h2 class="title" style="clear: both">
    292. 

  292. <a name="description"></a>2.3. DESCRIPTION</h2></div></div></div>
    293. 

  293. <p><code class="computeroutput">bzip2</code> compresses files
    294. 

  294. using the Burrows-Wheeler block sorting text compression
    295. 

  295. algorithm, and Huffman coding.  Compression is generally
    296. 

  296. considerably better than that achieved by more conventional
    297. 

  297. LZ77/LZ78-based compressors, and approaches the performance of
    298. 

  298. the PPM family of statistical compressors.</p>
    299. 

  299. <p>The command-line options are deliberately very similar to
    300. 

  300. those of GNU <code class="computeroutput">gzip</code>, but they are
    301. 

  301. not identical.</p>
    302. 

  302. <p><code class="computeroutput">bzip2</code> expects a list of
    303. 

  303. file names to accompany the command-line flags.  Each file is
    304. 

  304. replaced by a compressed version of itself, with the name
    305. 

  305. <code class="computeroutput">original_name.bz2</code>.  Each
    306. 

  306. compressed file has the same modification date, permissions, and,
    307. 

  307. when possible, ownership as the corresponding original, so that
    308. 

  308. these properties can be correctly restored at decompression time.
    309. 

  309. File name handling is naive in the sense that there is no
    310. 

  310. mechanism for preserving original file names, permissions,
    311. 

  311. ownerships or dates in filesystems which lack these concepts, or
    312. 

  312. have serious file name length restrictions, such as
    313. 

  313. MS-DOS.</p>
    314. 

  314. <p><code class="computeroutput">bzip2</code> and
    315. 

  315. <code class="computeroutput">bunzip2</code> will by default not
    316. 

  316. overwrite existing files.  If you want this to happen, specify
    317. 

  317. the <code class="computeroutput">-f</code> flag.</p>
    318. 

  318. <p>If no file names are specified,
    319. 

  319. <code class="computeroutput">bzip2</code> compresses from standard
    320. 

  320. input to standard output.  In this case,
    321. 

  321. <code class="computeroutput">bzip2</code> will decline to write
    322. 

  322. compressed output to a terminal, as this would be entirely
    323. 

  323. incomprehensible and therefore pointless.</p>
    324. 

  324. <p><code class="computeroutput">bunzip2</code> (or
    325. 

  325. <code class="computeroutput">bzip2 -d</code>) decompresses all
    326. 

  326. specified files.  Files which were not created by
    327. 

  327. <code class="computeroutput">bzip2</code> will be detected and
    328. 

  328. ignored, and a warning issued.
    329. 

  329. <code class="computeroutput">bzip2</code> attempts to guess the
    330. 

  330. filename for the decompressed file from that of the compressed
    331. 

  331. file as follows:</p>
    332. 

  332. <div class="itemizedlist"><ul type="bullet">
    333. 

  333. <li style="list-style-type: disc"><p><code class="computeroutput">filename.bz2 </code>
    334. 

  334.   becomes
    335. 

  335.   <code class="computeroutput">filename</code></p></li>
    336. 

  336. <li style="list-style-type: disc"><p><code class="computeroutput">filename.bz </code>
    337. 

  337.   becomes
    338. 

  338.   <code class="computeroutput">filename</code></p></li>
    339. 

  339. <li style="list-style-type: disc"><p><code class="computeroutput">filename.tbz2</code>
    340. 

  340.   becomes
    341. 

  341.   <code class="computeroutput">filename.tar</code></p></li>
    342. 

  342. <li style="list-style-type: disc"><p><code class="computeroutput">filename.tbz </code>
    343. 

  343.   becomes
    344. 

  344.   <code class="computeroutput">filename.tar</code></p></li>
    345. 

  345. <li style="list-style-type: disc"><p><code class="computeroutput">anyothername </code>
    346. 

  346.   becomes
    347. 

  347.   <code class="computeroutput">anyothername.out</code></p></li>
    348. 

  348. </ul></div>
    349. 

  349. <p>If the file does not end in one of the recognised endings,
    350. 

  350. <code class="computeroutput">.bz2</code>,
    351. 

  351. <code class="computeroutput">.bz</code>,
    352. 

  352. <code class="computeroutput">.tbz2</code> or
    353. 

  353. <code class="computeroutput">.tbz</code>,
    354. 

  354. <code class="computeroutput">bzip2</code> complains that it cannot
    355. 

  355. guess the name of the original file, and uses the original name
    356. 

  356. with <code class="computeroutput">.out</code> appended.</p>
    357. 

  357. <p>As with compression, supplying no filenames causes
    358. 

  358. decompression from standard input to standard output.</p>
    359. 

  359. <p><code class="computeroutput">bunzip2</code> will correctly
    360. 

  360. decompress a file which is the concatenation of two or more
    361. 

  361. compressed files.  The result is the concatenation of the
    362. 

  362. corresponding uncompressed files.  Integrity testing
    363. 

  363. (<code class="computeroutput">-t</code>) of concatenated compressed
    364. 

  364. files is also supported.</p>
    365. 

  365. <p>You can also compress or decompress files to the standard
    366. 

  366. output by giving the <code class="computeroutput">-c</code> flag.
    367. 

  367. Multiple files may be compressed and decompressed like this.  The
    368. 

  368. resulting outputs are fed sequentially to stdout.  Compression of
    369. 

  369. multiple files in this manner generates a stream containing
    370. 

  370. multiple compressed file representations.  Such a stream can be
    371. 

  371. decompressed correctly only by
    372. 

  372. <code class="computeroutput">bzip2</code> version 0.9.0 or later.
    373. 

  373. Earlier versions of <code class="computeroutput">bzip2</code> will
    374. 

  374. stop after decompressing the first file in the stream.</p>
    375. 

  375. <p><code class="computeroutput">bzcat</code> (or
    376. 

  376. <code class="computeroutput">bzip2 -dc</code>) decompresses all
    377. 

  377. specified files to the standard output.</p>
    378. 

  378. <p><code class="computeroutput">bzip2</code> will read arguments
    379. 

  379. from the environment variables
    380. 

  380. <code class="computeroutput">BZIP2</code> and
    381. 

  381. <code class="computeroutput">BZIP</code>, in that order, and will
    382. 

  382. process them before any arguments read from the command line.
    383. 

  383. This gives a convenient way to supply default arguments.</p>
    384. 

  384. <p>Compression is always performed, even if the compressed
    385. 

  385. file is slightly larger than the original.  Files of less than
    386. 

  386. about one hundred bytes tend to get larger, since the compression
    387. 

  387. mechanism has a constant overhead in the region of 50 bytes.
    388. 

  388. Random data (including the output of most file compressors) is
    389. 

  389. coded at about 8.05 bits per byte, giving an expansion of around
    390. 

  390. 0.5%.</p>
    391. 

  391. <p>As a self-check for your protection,
    392. 

  392. <code class="computeroutput">bzip2</code> uses 32-bit CRCs to make
    393. 

  393. sure that the decompressed version of a file is identical to the
    394. 

  394. original.  This guards against corruption of the compressed data,
    395. 

  395. and against undetected bugs in
    396. 

  396. <code class="computeroutput">bzip2</code> (hopefully very unlikely).
    397. 

  397. The chances of data corruption going undetected is microscopic,
    398. 

  398. about one chance in four billion for each file processed.  Be
    399. 

  399. aware, though, that the check occurs upon decompression, so it
    400. 

  400. can only tell you that something is wrong.  It can't help you
    401. 

  401. recover the original uncompressed data.  You can use
    402. 

  402. <code class="computeroutput">bzip2recover</code> to try to recover
    403. 

  403. data from damaged files.</p>
    404. 

  404. <p>Return values: 0 for a normal exit, 1 for environmental
    405. 

  405. problems (file not found, invalid flags, I/O errors, etc.), 2
    406. 

  406. to indicate a corrupt compressed file, 3 for an internal
    407. 

  407. consistency error (eg, bug) which caused
    408. 

  408. <code class="computeroutput">bzip2</code> to panic.</p>
    409. 

  409. </div>
    410. 

  410. <div class="sect1" lang="en">
    411. 

  411. <div class="titlepage"><div><div><h2 class="title" style="clear: both">
    412. 

  412. <a name="options"></a>2.4. OPTIONS</h2></div></div></div>
    413. 

  413. <div class="variablelist"><dl>
    414. 

  414. <dt><span class="term"><code class="computeroutput">-c --stdout</code></span></dt>
    415. 

  415. <dd><p>Compress or decompress to standard
    416. 

  416.   output.</p></dd>
    417. 

  417. <dt><span class="term"><code class="computeroutput">-d --decompress</code></span></dt>
    418. 

  418. <dd><p>Force decompression.
    419. 

  419.   <code class="computeroutput">bzip2</code>,
    420. 

  420.   <code class="computeroutput">bunzip2</code> and
    421. 

  421.   <code class="computeroutput">bzcat</code> are really the same
    422. 

  422.   program, and the decision about what actions to take is done on
    423. 

  423.   the basis of which name is used.  This flag overrides that
    424. 

  424.   mechanism, and forces bzip2 to decompress.</p></dd>
    425. 

  425. <dt><span class="term"><code class="computeroutput">-z --compress</code></span></dt>
    426. 

  426. <dd><p>The complement to
    427. 

  427.   <code class="computeroutput">-d</code>: forces compression,
    428. 

  428.   regardless of the invokation name.</p></dd>
    429. 

  429. <dt><span class="term"><code class="computeroutput">-t --test</code></span></dt>
    430. 

  430. <dd><p>Check integrity of the specified file(s), but
    431. 

  431.   don't decompress them.  This really performs a trial
    432. 

  432.   decompression and throws away the result.</p></dd>
    433. 

  433. <dt><span class="term"><code class="computeroutput">-f --force</code></span></dt>
    434. 

  434. <dd>
    435. 

  435. <p>Force overwrite of output files.  Normally,
    436. 

  436.   <code class="computeroutput">bzip2</code> will not overwrite
    437. 

  437.   existing output files.  Also forces
    438. 

  438.   <code class="computeroutput">bzip2</code> to break hard links to
    439. 

  439.   files, which it otherwise wouldn't do.</p>
    440. 

  440. <p><code class="computeroutput">bzip2</code> normally declines
    441. 

  441.   to decompress files which don't have the correct magic header
    442. 

  442.   bytes. If forced (<code class="computeroutput">-f</code>),
    443. 

  443.   however, it will pass such files through unmodified. This is
    444. 

  444.   how GNU <code class="computeroutput">gzip</code> behaves.</p>
    445. 

  445. </dd>
    446. 

  446. <dt><span class="term"><code class="computeroutput">-k --keep</code></span></dt>
    447. 

  447. <dd><p>Keep (don't delete) input files during
    448. 

  448.   compression or decompression.</p></dd>
    449. 

  449. <dt><span class="term"><code class="computeroutput">-s --small</code></span></dt>
    450. 

  450. <dd>
    451. 

  451. <p>Reduce memory usage, for compression,
    452. 

  452.   decompression and testing.  Files are decompressed and tested
    453. 

  453.   using a modified algorithm which only requires 2.5 bytes per
    454. 

  454.   block byte.  This means any file can be decompressed in 2300k
    455. 

  455.   of memory, albeit at about half the normal speed.</p>
    456. 

  456. <p>During compression, <code class="computeroutput">-s</code>
    457. 

  457.   selects a block size of 200k, which limits memory use to around
    458. 

  458.   the same figure, at the expense of your compression ratio.  In
    459. 

  459.   short, if your machine is low on memory (8 megabytes or less),
    460. 

  460.   use <code class="computeroutput">-s</code> for everything.  See
    461. 

  461.   <a href="#memory-management">MEMORY MANAGEMENT</a> below.</p>
    462. 

  462. </dd>
    463. 

  463. <dt><span class="term"><code class="computeroutput">-q --quiet</code></span></dt>
    464. 

  464. <dd><p>Suppress non-essential warning messages.
    465. 

  465.   Messages pertaining to I/O errors and other critical events
    466. 

  466.   will not be suppressed.</p></dd>
    467. 

  467. <dt><span class="term"><code class="computeroutput">-v --verbose</code></span></dt>
    468. 

  468. <dd><p>Verbose mode -- show the compression ratio for
    469. 

  469.   each file processed.  Further
    470. 

  470.   <code class="computeroutput">-v</code>'s increase the verbosity
    471. 

  471.   level, spewing out lots of information which is primarily of
    472. 

  472.   interest for diagnostic purposes.</p></dd>
    473. 

  473. <dt><span class="term"><code class="computeroutput">-L --license -V --version</code></span></dt>
    474. 

  474. <dd><p>Display the software version, license terms and
    475. 

  475.   conditions.</p></dd>
    476. 

  476. <dt><span class="term"><code class="computeroutput">-1</code> (or
    477. 

  477.  <code class="computeroutput">--fast</code>) to
    478. 

  478.  <code class="computeroutput">-9</code> (or
    479. 

  479.  <code class="computeroutput">-best</code>)</span></dt>
    480. 

  480. <dd><p>Set the block size to 100 k, 200 k ...  900 k
    481. 

  481.   when compressing.  Has no effect when decompressing.  See <a href="#memory-management">MEMORY MANAGEMENT</a> below.  The
    482. 

  482.   <code class="computeroutput">--fast</code> and
    483. 

  483.   <code class="computeroutput">--best</code> aliases are primarily
    484. 

  484.   for GNU <code class="computeroutput">gzip</code> compatibility.
    485. 

  485.   In particular, <code class="computeroutput">--fast</code> doesn't
    486. 

  486.   make things significantly faster.  And
    487. 

  487.   <code class="computeroutput">--best</code> merely selects the
    488. 

  488.   default behaviour.</p></dd>
    489. 

  489. <dt><span class="term"><code class="computeroutput">--</code></span></dt>
    490. 

  490. <dd><p>Treats all subsequent arguments as file names,
    491. 

  491.   even if they start with a dash.  This is so you can handle
    492. 

  492.   files with names beginning with a dash, for example:
    493. 

  493.   <code class="computeroutput">bzip2 --
    494. 

  494.   -myfilename</code>.</p></dd>
    495. 

  495. <dt>
    496. 

  496. <span class="term"><code class="computeroutput">--repetitive-fast</code>, </span><span class="term"><code class="computeroutput">--repetitive-best</code></span>
    497. 

  497. </dt>
    498. 

  498. <dd><p>These flags are redundant in versions 0.9.5 and
    499. 

  499.   above.  They provided some coarse control over the behaviour of
    500. 

  500.   the sorting algorithm in earlier versions, which was sometimes
    501. 

  501.   useful.  0.9.5 and above have an improved algorithm which
    502. 

  502.   renders these flags irrelevant.</p></dd>
    503. 

  503. </dl></div>
    504. 

  504. </div>
    505. 

  505. <div class="sect1" lang="en">
    506. 

  506. <div class="titlepage"><div><div><h2 class="title" style="clear: both">
    507. 

  507. <a name="memory-management"></a>2.5. MEMORY MANAGEMENT</h2></div></div></div>
    508. 

  508. <p><code class="computeroutput">bzip2</code> compresses large
    509. 

  509. files in blocks.  The block size affects both the compression
    510. 

  510. ratio achieved, and the amount of memory needed for compression
    511. 

  511. and decompression.  The flags <code class="computeroutput">-1</code>
    512. 

  512. through <code class="computeroutput">-9</code> specify the block
    513. 

  513. size to be 100,000 bytes through 900,000 bytes (the default)
    514. 

  514. respectively.  At decompression time, the block size used for
    515. 

  515. compression is read from the header of the compressed file, and
    516. 

  516. <code class="computeroutput">bunzip2</code> then allocates itself
    517. 

  517. just enough memory to decompress the file.  Since block sizes are
    518. 

  518. stored in compressed files, it follows that the flags
    519. 

  519. <code class="computeroutput">-1</code> to
    520. 

  520. <code class="computeroutput">-9</code> are irrelevant to and so
    521. 

  521. ignored during decompression.</p>
    522. 

  522. <p>Compression and decompression requirements, in bytes, can be
    523. 

  523. estimated as:</p>
    524. 

  524. <pre class="programlisting">Compression:   400k + ( 8 x block size )
    525. 

  525. 

  526. Decompression: 100k + ( 4 x block size ), or
    527. 

  527.                100k + ( 2.5 x block size )</pre>
    528. 

  528. <p>Larger block sizes give rapidly diminishing marginal
    529. 

  529. returns.  Most of the compression comes from the first two or
    530. 

  530. three hundred k of block size, a fact worth bearing in mind when
    531. 

  531. using <code class="computeroutput">bzip2</code> on small machines.
    532. 

  532. It is also important to appreciate that the decompression memory
    533. 

  533. requirement is set at compression time by the choice of block
    534. 

  534. size.</p>
    535. 

  535. <p>For files compressed with the default 900k block size,
    536. 

  536. <code class="computeroutput">bunzip2</code> will require about 3700
    537. 

  537. kbytes to decompress.  To support decompression of any file on a
    538. 

  538. 4 megabyte machine, <code class="computeroutput">bunzip2</code> has
    539. 

  539. an option to decompress using approximately half this amount of
    540. 

  540. memory, about 2300 kbytes.  Decompression speed is also halved,
    541. 

  541. so you should use this option only where necessary.  The relevant
    542. 

  542. flag is <code class="computeroutput">-s</code>.</p>
    543. 

  543. <p>In general, try and use the largest block size memory
    544. 

  544. constraints allow, since that maximises the compression achieved.
    545. 

  545. Compression and decompression speed are virtually unaffected by
    546. 

  546. block size.</p>
    547. 

  547. <p>Another significant point applies to files which fit in a
    548. 

  548. single block -- that means most files you'd encounter using a
    549. 

  549. large block size.  The amount of real memory touched is
    550. 

  550. proportional to the size of the file, since the file is smaller
    551. 

  551. than a block.  For example, compressing a file 20,000 bytes long
    552. 

  552. with the flag <code class="computeroutput">-9</code> will cause the
    553. 

  553. compressor to allocate around 7600k of memory, but only touch
    554. 

  554. 400k + 20000 * 8 = 560 kbytes of it.  Similarly, the decompressor
    555. 

  555. will allocate 3700k but only touch 100k + 20000 * 4 = 180
    556. 

  556. kbytes.</p>
    557. 

  557. <p>Here is a table which summarises the maximum memory usage
    558. 

  558. for different block sizes.  Also recorded is the total compressed
    559. 

  559. size for 14 files of the Calgary Text Compression Corpus
    560. 

  560. totalling 3,141,622 bytes.  This column gives some feel for how
    561. 

  561. compression varies with block size.  These figures tend to
    562. 

  562. understate the advantage of larger block sizes for larger files,
    563. 

  563. since the Corpus is dominated by smaller files.</p>
    564. 

  564. <pre class="programlisting">        Compress   Decompress   Decompress   Corpus
    565. 

  565. Flag     usage      usage       -s usage     Size
    566. 

  566. 

  567.  -1      1200k       500k         350k      914704
    568. 

  568.  -2      2000k       900k         600k      877703
    569. 

  569.  -3      2800k      1300k         850k      860338
    570. 

  570.  -4      3600k      1700k        1100k      846899
    571. 

  571.  -5      4400k      2100k        1350k      845160
    572. 

  572.  -6      5200k      2500k        1600k      838626
    573. 

  573.  -7      6100k      2900k        1850k      834096
    574. 

  574.  -8      6800k      3300k        2100k      828642
    575. 

  575.  -9      7600k      3700k        2350k      828642</pre>
    576. 

  576. </div>
    577. 

  577. <div class="sect1" lang="en">
    578. 

  578. <div class="titlepage"><div><div><h2 class="title" style="clear: both">
    579. 

  579. <a name="recovering"></a>2.6. RECOVERING DATA FROM DAMAGED FILES</h2></div></div></div>
    580. 

  580. <p><code class="computeroutput">bzip2</code> compresses files in
    581. 

  581. blocks, usually 900kbytes long.  Each block is handled
    582. 

  582. independently.  If a media or transmission error causes a
    583. 

  583. multi-block <code class="computeroutput">.bz2</code> file to become
    584. 

  584. damaged, it may be possible to recover data from the undamaged
    585. 

  585. blocks in the file.</p>
    586. 

  586. <p>The compressed representation of each block is delimited by
    587. 

  587. a 48-bit pattern, which makes it possible to find the block
    588. 

  588. boundaries with reasonable certainty.  Each block also carries
    589. 

  589. its own 32-bit CRC, so damaged blocks can be distinguished from
    590. 

  590. undamaged ones.</p>
    591. 

  591. <p><code class="computeroutput">bzip2recover</code> is a simple
    592. 

  592. program whose purpose is to search for blocks in
    593. 

  593. <code class="computeroutput">.bz2</code> files, and write each block
    594. 

  594. out into its own <code class="computeroutput">.bz2</code> file.  You
    595. 

  595. can then use <code class="computeroutput">bzip2 -t</code> to test
    596. 

  596. the integrity of the resulting files, and decompress those which
    597. 

  597. are undamaged.</p>
    598. 

  598. <p><code class="computeroutput">bzip2recover</code> takes a
    599. 

  599. single argument, the name of the damaged file, and writes a
    600. 

  600. number of files <code class="computeroutput">rec0001file.bz2</code>,
    601. 

  601. <code class="computeroutput">rec0002file.bz2</code>, etc, containing
    602. 

  602. the extracted blocks.  The output filenames are designed so that
    603. 

  603. the use of wildcards in subsequent processing -- for example,
    604. 

  604. <code class="computeroutput">bzip2 -dc rec*file.bz2 &gt;
    605. 

  605. recovered_data</code> -- lists the files in the correct
    606. 

  606. order.</p>
    607. 

  607. <p><code class="computeroutput">bzip2recover</code> should be of
    608. 

  608. most use dealing with large <code class="computeroutput">.bz2</code>
    609. 

  609. files, as these will contain many blocks.  It is clearly futile
    610. 

  610. to use it on damaged single-block files, since a damaged block
    611. 

  611. cannot be recovered.  If you wish to minimise any potential data
    612. 

  612. loss through media or transmission errors, you might consider
    613. 

  613. compressing with a smaller block size.</p>
    614. 

  614. </div>
    615. 

  615. <div class="sect1" lang="en">
    616. 

  616. <div class="titlepage"><div><div><h2 class="title" style="clear: both">
    617. 

  617. <a name="performance"></a>2.7. PERFORMANCE NOTES</h2></div></div></div>
    618. 

  618. <p>The sorting phase of compression gathers together similar
    619. 

  619. strings in the file.  Because of this, files containing very long
    620. 

  620. runs of repeated symbols, like "aabaabaabaab ..."  (repeated
    621. 

  621. several hundred times) may compress more slowly than normal.
    622. 

  622. Versions 0.9.5 and above fare much better than previous versions
    623. 

  623. in this respect.  The ratio between worst-case and average-case
    624. 

  624. compression time is in the region of 10:1.  For previous
    625. 

  625. versions, this figure was more like 100:1.  You can use the
    626. 

  626. <code class="computeroutput">-vvvv</code> option to monitor progress
    627. 

  627. in great detail, if you want.</p>
    628. 

  628. <p>Decompression speed is unaffected by these
    629. 

  629. phenomena.</p>
    630. 

  630. <p><code class="computeroutput">bzip2</code> usually allocates
    631. 

  631. several megabytes of memory to operate in, and then charges all
    632. 

  632. over it in a fairly random fashion.  This means that performance,
    633. 

  633. both for compressing and decompressing, is largely determined by
    634. 

  634. the speed at which your machine can service cache misses.
    635. 

  635. Because of this, small changes to the code to reduce the miss
    636. 

  636. rate have been observed to give disproportionately large
    637. 

  637. performance improvements.  I imagine
    638. 

  638. <code class="computeroutput">bzip2</code> will perform best on
    639. 

  639. machines with very large caches.</p>
    640. 

  640. </div>
    641. 

  641. <div class="sect1" lang="en">
    642. 

  642. <div class="titlepage"><div><div><h2 class="title" style="clear: both">
    643. 

  643. <a name="caveats"></a>2.8. CAVEATS</h2></div></div></div>
    644. 

  644. <p>I/O error messages are not as helpful as they could be.
    645. 

  645. <code class="computeroutput">bzip2</code> tries hard to detect I/O
    646. 

  646. errors and exit cleanly, but the details of what the problem is
    647. 

  647. sometimes seem rather misleading.</p>
    648. 

  648. <p>This manual page pertains to version 1.0.5 of
    649. 

  649. <code class="computeroutput">bzip2</code>.  Compressed data created by
    650. 

  650. this version is entirely forwards and backwards compatible with the
    651. 

  651. previous public releases, versions 0.1pl2, 0.9.0 and 0.9.5, 1.0.0,
    652. 

  652. 1.0.1, 1.0.2 and 1.0.3, but with the following exception: 0.9.0 and
    653. 

  653. above can correctly decompress multiple concatenated compressed files.
    654. 

  654. 0.1pl2 cannot do this; it will stop after decompressing just the first
    655. 

  655. file in the stream.</p>
    656. 

  656. <p><code class="computeroutput">bzip2recover</code> versions
    657. 

  657. prior to 1.0.2 used 32-bit integers to represent bit positions in
    658. 

  658. compressed files, so it could not handle compressed files more
    659. 

  659. than 512 megabytes long.  Versions 1.0.2 and above use 64-bit ints
    660. 

  660. on some platforms which support them (GNU supported targets, and
    661. 

  661. Windows). To establish whether or not
    662. 

  662. <code class="computeroutput">bzip2recover</code> was built with such
    663. 

  663. a limitation, run it without arguments. In any event you can
    664. 

  664. build yourself an unlimited version if you can recompile it with
    665. 

  665. <code class="computeroutput">MaybeUInt64</code> set to be an
    666. 

  666. unsigned 64-bit integer.</p>
    667. 

  667. </div>
    668. 

  668. <div class="sect1" lang="en">
    669. 

  669. <div class="titlepage"><div><div><h2 class="title" style="clear: both">
    670. 

  670. <a name="author"></a>2.9. AUTHOR</h2></div></div></div>
    671. 

  671. <p>Julian Seward,
    672. 

  672. <code class="computeroutput">jseward@bzip.org</code></p>
    673. 

  673. <p>The ideas embodied in
    674. 

  674. <code class="computeroutput">bzip2</code> are due to (at least) the
    675. 

  675. following people: Michael Burrows and David Wheeler (for the
    676. 

  676. block sorting transformation), David Wheeler (again, for the
    677. 

  677. Huffman coder), Peter Fenwick (for the structured coding model in
    678. 

  678. the original <code class="computeroutput">bzip</code>, and many
    679. 

  679. refinements), and Alistair Moffat, Radford Neal and Ian Witten
    680. 

  680. (for the arithmetic coder in the original
    681. 

  681. <code class="computeroutput">bzip</code>).  I am much indebted for
    682. 

  682. their help, support and advice.  See the manual in the source
    683. 

  683. distribution for pointers to sources of documentation.  Christian
    684. 

  684. von Roques encouraged me to look for faster sorting algorithms,
    685. 

  685. so as to speed up compression.  Bela Lubkin encouraged me to
    686. 

  686. improve the worst-case compression performance.  
    687. 

  687. Donna Robinson XMLised the documentation.
    688. 

  688. Many people sent
    689. 

  689. patches, helped with portability problems, lent machines, gave
    690. 

  690. advice and were generally helpful.</p>
    691. 

  691. </div>
    692. 

  692. </div>
    693. 

  693. <div class="chapter" lang="en">
    694. 

  694. <div class="titlepage"><div><div><h2 class="title">
    695. 

  695. <a name="libprog"></a>3. 
    696. 

  696. Programming with <code class="computeroutput">libbzip2</code>
    697. 

  697. </h2></div></div></div>
    698. 

  698. <div class="toc">
    699. 

  699. <p><b>Table of Contents</b></p>
    700. 

  700. <dl>
    701. 

  701. <dt><span class="sect1"><a href="#top-level">3.1. Top-level structure</a></span></dt>
    702. 

  702. <dd><dl>
    703. 

  703. <dt><span class="sect2"><a href="#ll-summary">3.1.1. Low-level summary</a></span></dt>
    704. 

  704. <dt><span class="sect2"><a href="#hl-summary">3.1.2. High-level summary</a></span></dt>
    705. 

  705. <dt><span class="sect2"><a href="#util-fns-summary">3.1.3. Utility functions summary</a></span></dt>
    706. 

  706. </dl></dd>
    707. 

  707. <dt><span class="sect1"><a href="#err-handling">3.2. Error handling</a></span></dt>
    708. 

  708. <dt><span class="sect1"><a href="#low-level">3.3. Low-level interface</a></span></dt>
    709. 

  709. <dd><dl>
    710. 

  710. <dt><span class="sect2"><a href="#bzcompress-init">3.3.1. <code class="computeroutput">BZ2_bzCompressInit</code></a></span></dt>
    711. 

  711. <dt><span class="sect2"><a href="#bzCompress">3.3.2. <code class="computeroutput">BZ2_bzCompress</code></a></span></dt>
    712. 

  712. <dt><span class="sect2"><a href="#bzCompress-end">3.3.3. <code class="computeroutput">BZ2_bzCompressEnd</code></a></span></dt>
    713. 

  713. <dt><span class="sect2"><a href="#bzDecompress-init">3.3.4. <code class="computeroutput">BZ2_bzDecompressInit</code></a></span></dt>
    714. 

  714. <dt><span class="sect2"><a href="#bzDecompress">3.3.5. <code class="computeroutput">BZ2_bzDecompress</code></a></span></dt>
    715. 

  715. <dt><span class="sect2"><a href="#bzDecompress-end">3.3.6. <code class="computeroutput">BZ2_bzDecompressEnd</code></a></span></dt>
    716. 

  716. </dl></dd>
    717. 

  717. <dt><span class="sect1"><a href="#hl-interface">3.4. High-level interface</a></span></dt>
    718. 

  718. <dd><dl>
    719. 

  719. <dt><span class="sect2"><a href="#bzreadopen">3.4.1. <code class="computeroutput">BZ2_bzReadOpen</code></a></span></dt>
    720. 

  720. <dt><span class="sect2"><a href="#bzread">3.4.2. <code class="computeroutput">BZ2_bzRead</code></a></span></dt>
    721. 

  721. <dt><span class="sect2"><a href="#bzreadgetunused">3.4.3. <code class="computeroutput">BZ2_bzReadGetUnused</code></a></span></dt>
    722. 

  722. <dt><span class="sect2"><a href="#bzreadclose">3.4.4. <code class="computeroutput">BZ2_bzReadClose</code></a></span></dt>
    723. 

  723. <dt><span class="sect2"><a href="#bzwriteopen">3.4.5. <code class="computeroutput">BZ2_bzWriteOpen</code></a></span></dt>
    724. 

  724. <dt><span class="sect2"><a href="#bzwrite">3.4.6. <code class="computeroutput">BZ2_bzWrite</code></a></span></dt>
    725. 

  725. <dt><span class="sect2"><a href="#bzwriteclose">3.4.7. <code class="computeroutput">BZ2_bzWriteClose</code></a></span></dt>
    726. 

  726. <dt><span class="sect2"><a href="#embed">3.4.8. Handling embedded compressed data streams</a></span></dt>
    727. 

  727. <dt><span class="sect2"><a href="#std-rdwr">3.4.9. Standard file-reading/writing code</a></span></dt>
    728. 

  728. </dl></dd>
    729. 

  729. <dt><span class="sect1"><a href="#util-fns">3.5. Utility functions</a></span></dt>
    730. 

  730. <dd><dl>
    731. 

  731. <dt><span class="sect2"><a href="#bzbufftobuffcompress">3.5.1. <code class="computeroutput">BZ2_bzBuffToBuffCompress</code></a></span></dt>
    732. 

  732. <dt><span class="sect2"><a href="#bzbufftobuffdecompress">3.5.2. <code class="computeroutput">BZ2_bzBuffToBuffDecompress</code></a></span></dt>
    733. 

  733. </dl></dd>
    734. 

  734. <dt><span class="sect1"><a href="#zlib-compat">3.6. <code class="computeroutput">zlib</code> compatibility functions</a></span></dt>
    735. 

  735. <dt><span class="sect1"><a href="#stdio-free">3.7. Using the library in a <code class="computeroutput">stdio</code>-free environment</a></span></dt>
    736. 

  736. <dd><dl>
    737. 

  737. <dt><span class="sect2"><a href="#stdio-bye">3.7.1. Getting rid of <code class="computeroutput">stdio</code></a></span></dt>
    738. 

  738. <dt><span class="sect2"><a href="#critical-error">3.7.2. Critical error handling</a></span></dt>
    739. 

  739. </dl></dd>
    740. 

  740. <dt><span class="sect1"><a href="#win-dll">3.8. Making a Windows DLL</a></span></dt>
    741. 

  741. </dl>
    742. 

  742. </div>
    743. 

  743. <p>This chapter describes the programming interface to
    744. 

  744. <code class="computeroutput">libbzip2</code>.</p>
    745. 

  745. <p>For general background information, particularly about
    746. 

  746. memory use and performance aspects, you'd be well advised to read
    747. 

  747. <a href="#using">How to use bzip2</a> as well.</p>
    748. 

  748. <div class="sect1" lang="en">
    749. 

  749. <div class="titlepage"><div><div><h2 class="title" style="clear: both">
    750. 

  750. <a name="top-level"></a>3.1. Top-level structure</h2></div></div></div>
    751. 

  751. <p><code class="computeroutput">libbzip2</code> is a flexible
    752. 

  752. library for compressing and decompressing data in the
    753. 

  753. <code class="computeroutput">bzip2</code> data format.  Although
    754. 

  754. packaged as a single entity, it helps to regard the library as
    755. 

  755. three separate parts: the low level interface, and the high level
    756. 

  756. interface, and some utility functions.</p>
    757. 

  757. <p>The structure of
    758. 

  758. <code class="computeroutput">libbzip2</code>'s interfaces is similar
    759. 

  759. to that of Jean-loup Gailly's and Mark Adler's excellent
    760. 

  760. <code class="computeroutput">zlib</code> library.</p>
    761. 

  761. <p>All externally visible symbols have names beginning
    762. 

  762. <code class="computeroutput">BZ2_</code>.  This is new in version
    763. 

  763. 1.0.  The intention is to minimise pollution of the namespaces of
    764. 

  764. library clients.</p>
    765. 

  765. <p>To use any part of the library, you need to
    766. 

  766. <code class="computeroutput">#include &lt;bzlib.h&gt;</code>
    767. 

  767. into your sources.</p>
    768. 

  768. <div class="sect2" lang="en">
    769. 

  769. <div class="titlepage"><div><div><h3 class="title">
    770. 

  770. <a name="ll-summary"></a>3.1.1. Low-level summary</h3></div></div></div>
    771. 

  771. <p>This interface provides services for compressing and
    772. 

  772. decompressing data in memory.  There's no provision for dealing
    773. 

  773. with files, streams or any other I/O mechanisms, just straight
    774. 

  774. memory-to-memory work.  In fact, this part of the library can be
    775. 

  775. compiled without inclusion of
    776. 

  776. <code class="computeroutput">stdio.h</code>, which may be helpful
    777. 

  777. for embedded applications.</p>
    778. 

  778. <p>The low-level part of the library has no global variables
    779. 

  779. and is therefore thread-safe.</p>
    780. 

  780. <p>Six routines make up the low level interface:
    781. 

  781. <code class="computeroutput">BZ2_bzCompressInit</code>,
    782. 

  782. <code class="computeroutput">BZ2_bzCompress</code>, and
    783. 

  783. <code class="computeroutput">BZ2_bzCompressEnd</code> for
    784. 

  784. compression, and a corresponding trio
    785. 

  785. <code class="computeroutput">BZ2_bzDecompressInit</code>,
    786. 

  786. <code class="computeroutput">BZ2_bzDecompress</code> and
    787. 

  787. <code class="computeroutput">BZ2_bzDecompressEnd</code> for
    788. 

  788. decompression.  The <code class="computeroutput">*Init</code>
    789. 

  789. functions allocate memory for compression/decompression and do
    790. 

  790. other initialisations, whilst the
    791. 

  791. <code class="computeroutput">*End</code> functions close down
    792. 

  792. operations and release memory.</p>
    793. 

  793. <p>The real work is done by
    794. 

  794. <code class="computeroutput">BZ2_bzCompress</code> and
    795. 

  795. <code class="computeroutput">BZ2_bzDecompress</code>.  These
    796. 

  796. compress and decompress data from a user-supplied input buffer to
    797. 

  797. a user-supplied output buffer.  These buffers can be any size;
    798. 

  798. arbitrary quantities of data are handled by making repeated calls
    799. 

  799. to these functions.  This is a flexible mechanism allowing a
    800. 

  800. consumer-pull style of activity, or producer-push, or a mixture
    801. 

  801. of both.</p>
    802. 

  802. </div>
    803. 

  803. <div class="sect2" lang="en">
    804. 

  804. <div class="titlepage"><div><div><h3 class="title">
    805. 

  805. <a name="hl-summary"></a>3.1.2. High-level summary</h3></div></div></div>
    806. 

  806. <p>This interface provides some handy wrappers around the
    807. 

  807. low-level interface to facilitate reading and writing
    808. 

  808. <code class="computeroutput">bzip2</code> format files
    809. 

  809. (<code class="computeroutput">.bz2</code> files).  The routines
    810. 

  810. provide hooks to facilitate reading files in which the
    811. 

  811. <code class="computeroutput">bzip2</code> data stream is embedded
    812. 

  812. within some larger-scale file structure, or where there are
    813. 

  813. multiple <code class="computeroutput">bzip2</code> data streams
    814. 

  814. concatenated end-to-end.</p>
    815. 

  815. <p>For reading files,
    816. 

  816. <code class="computeroutput">BZ2_bzReadOpen</code>,
    817. 

  817. <code class="computeroutput">BZ2_bzRead</code>,
    818. 

  818. <code class="computeroutput">BZ2_bzReadClose</code> and 
    819. 

  819. <code class="computeroutput">BZ2_bzReadGetUnused</code> are
    820. 

  820. supplied.  For writing files,
    821. 

  821. <code class="computeroutput">BZ2_bzWriteOpen</code>,
    822. 

  822. <code class="computeroutput">BZ2_bzWrite</code> and
    823. 

  823. <code class="computeroutput">BZ2_bzWriteFinish</code> are
    824. 

  824. available.</p>
    825. 

  825. <p>As with the low-level library, no global variables are used
    826. 

  826. so the library is per se thread-safe.  However, if I/O errors
    827. 

  827. occur whilst reading or writing the underlying compressed files,
    828. 

  828. you may have to consult <code class="computeroutput">errno</code> to
    829. 

  829. determine the cause of the error.  In that case, you'd need a C
    830. 

  830. library which correctly supports
    831. 

  831. <code class="computeroutput">errno</code> in a multithreaded
    832. 

  832. environment.</p>
    833. 

  833. <p>To make the library a little simpler and more portable,
    834. 

  834. <code class="computeroutput">BZ2_bzReadOpen</code> and
    835. 

  835. <code class="computeroutput">BZ2_bzWriteOpen</code> require you to
    836. 

  836. pass them file handles (<code class="computeroutput">FILE*</code>s)
    837. 

  837. which have previously been opened for reading or writing
    838. 

  838. respectively.  That avoids portability problems associated with
    839. 

  839. file operations and file attributes, whilst not being much of an
    840. 

  840. imposition on the programmer.</p>
    841. 

  841. </div>
    842. 

  842. <div class="sect2" lang="en">
    843. 

  843. <div class="titlepage"><div><div><h3 class="title">
    844. 

  844. <a name="util-fns-summary"></a>3.1.3. Utility functions summary</h3></div></div></div>
    845. 

  845. <p>For very simple needs,
    846. 

  846. <code class="computeroutput">BZ2_bzBuffToBuffCompress</code> and
    847. 

  847. <code class="computeroutput">BZ2_bzBuffToBuffDecompress</code> are
    848. 

  848. provided.  These compress data in memory from one buffer to
    849. 

  849. another buffer in a single function call.  You should assess
    850. 

  850. whether these functions fulfill your memory-to-memory
    851. 

  851. compression/decompression requirements before investing effort in
    852. 

  852. understanding the more general but more complex low-level
    853. 

  853. interface.</p>
    854. 

  854. <p>Yoshioka Tsuneo
    855. 

  855. (<code class="computeroutput">tsuneo@rr.iij4u.or.jp</code>) has
    856. 

  856. contributed some functions to give better
    857. 

  857. <code class="computeroutput">zlib</code> compatibility.  These
    858. 

  858. functions are <code class="computeroutput">BZ2_bzopen</code>,
    859. 

  859. <code class="computeroutput">BZ2_bzread</code>,
    860. 

  860. <code class="computeroutput">BZ2_bzwrite</code>,
    861. 

  861. <code class="computeroutput">BZ2_bzflush</code>,
    862. 

  862. <code class="computeroutput">BZ2_bzclose</code>,
    863. 

  863. <code class="computeroutput">BZ2_bzerror</code> and
    864. 

  864. <code class="computeroutput">BZ2_bzlibVersion</code>.  You may find
    865. 

  865. these functions more convenient for simple file reading and
    866. 

  866. writing, than those in the high-level interface.  These functions
    867. 

  867. are not (yet) officially part of the library, and are minimally
    868. 

  868. documented here.  If they break, you get to keep all the pieces.
    869. 

  869. I hope to document them properly when time permits.</p>
    870. 

  870. <p>Yoshioka also contributed modifications to allow the
    871. 

  871. library to be built as a Windows DLL.</p>
    872. 

  872. </div>
    873. 

  873. </div>
    874. 

  874. <div class="sect1" lang="en">
    875. 

  875. <div class="titlepage"><div><div><h2 class="title" style="clear: both">
    876. 

  876. <a name="err-handling"></a>3.2. Error handling</h2></div></div></div>
    877. 

  877. <p>The library is designed to recover cleanly in all
    878. 

  878. situations, including the worst-case situation of decompressing
    879. 

  879. random data.  I'm not 100% sure that it can always do this, so
    880. 

  880. you might want to add a signal handler to catch segmentation
    881. 

  881. violations during decompression if you are feeling especially
    882. 

  882. paranoid.  I would be interested in hearing more about the
    883. 

  883. robustness of the library to corrupted compressed data.</p>
    884. 

  884. <p>Version 1.0.3 more robust in this respect than any
    885. 

  885. previous version.  Investigations with Valgrind (a tool for detecting
    886. 

  886. problems with memory management) indicate
    887. 

  887. that, at least for the few files I tested, all single-bit errors
    888. 

  888. in the decompressed data are caught properly, with no
    889. 

  889. segmentation faults, no uses of uninitialised data, no out of
    890. 

  890. range reads or writes, and no infinite looping in the decompressor.
    891. 

  891. So it's certainly pretty robust, although
    892. 

  892. I wouldn't claim it to be totally bombproof.</p>
    893. 

  893. <p>The file <code class="computeroutput">bzlib.h</code> contains
    894. 

  894. all definitions needed to use the library.  In particular, you
    895. 

  895. should definitely not include
    896. 

  896. <code class="computeroutput">bzlib_private.h</code>.</p>
    897. 

  897. <p>In <code class="computeroutput">bzlib.h</code>, the various
    898. 

  898. return values are defined.  The following list is not intended as
    899. 

  899. an exhaustive description of the circumstances in which a given
    900. 

  900. value may be returned -- those descriptions are given later.
    901. 

  901. Rather, it is intended to convey the rough meaning of each return
    902. 

  902. value.  The first five actions are normal and not intended to
    903. 

  903. denote an error situation.</p>
    904. 

  904. <div class="variablelist"><dl>
    905. 

  905. <dt><span class="term"><code class="computeroutput">BZ_OK</code></span></dt>
    906. 

  906. <dd><p>The requested action was completed
    907. 

  907.    successfully.</p></dd>
    908. 

  908. <dt><span class="term"><code class="computeroutput">BZ_RUN_OK, BZ_FLUSH_OK,
    909. 

  909.     BZ_FINISH_OK</code></span></dt>
    910. 

  910. <dd><p>In 
    911. 

  911.    <code class="computeroutput">BZ2_bzCompress</code>, the requested
    912. 

  912.    flush/finish/nothing-special action was completed
    913. 

  913.    successfully.</p></dd>
    914. 

  914. <dt><span class="term"><code class="computeroutput">BZ_STREAM_END</code></span></dt>
    915. 

  915. <dd><p>Compression of data was completed, or the
    916. 

  916.    logical stream end was detected during
    917. 

  917.    decompression.</p></dd>
    918. 

  918. </dl></div>
    919. 

  919. <p>The following return values indicate an error of some
    920. 

  920. kind.</p>
    921. 

  921. <div class="variablelist"><dl>
    922. 

  922. <dt><span class="term"><code class="computeroutput">BZ_CONFIG_ERROR</code></span></dt>
    923. 

  923. <dd><p>Indicates that the library has been improperly
    924. 

  924.    compiled on your platform -- a major configuration error.
    925. 

  925.    Specifically, it means that
    926. 

  926.    <code class="computeroutput">sizeof(char)</code>,
    927. 

  927.    <code class="computeroutput">sizeof(short)</code> and
    928. 

  928.    <code class="computeroutput">sizeof(int)</code> are not 1, 2 and
    929. 

  929.    4 respectively, as they should be.  Note that the library
    930. 

  930.    should still work properly on 64-bit platforms which follow
    931. 

  931.    the LP64 programming model -- that is, where
    932. 

  932.    <code class="computeroutput">sizeof(long)</code> and
    933. 

  933.    <code class="computeroutput">sizeof(void*)</code> are 8.  Under
    934. 

  934.    LP64, <code class="computeroutput">sizeof(int)</code> is still 4,
    935. 

  935.    so <code class="computeroutput…
    936.