<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.16 $ -->
 <reference id="ref.bzip2">
  <title>Bzip2 Compression Functions</title>
  <titleabbrev>Bzip2</titleabbrev>
  <partintro>
   <para>
    This module uses the functions of the <ulink
    url="&url.bzip2;">bzip2</ulink> library by Julian Seward to
    transparently read and write bzip2 (.bz2) compressed files.
   </para>
   <para>
    Bzip2 support in PHP is not enabled by default.  You will need to
    use the <link linkend="install.configure.with-bz2">--with-bz2</link> configuration
    option when compiling PHP to enable bzip2 support. This module
    requires bzip2/libbzip2 version &gt;= 1.0.x.
   </para>

   <sect1 id="bzip2-example">
    <title>Small code example</title>
    <para>
     This example opens a temporary file and writes a test string to
     it, then prints out the contents of the file.
    </para>
    <example>
     <title>Small bzip2 Example</title>
     <programlisting role="php">
<![CDATA[
<?php

$filename = "/tmp/testfile.bz2";
$str = "This is a test string.\n";

// open file for writing
$bz = bzopen($filename, "w");

// write string to file
bzwrite($bz, $str);

// close file
bzclose($bz);

// open file for reading
$bz = bzopen($filename, "r");

// read 10 characters
print bzread($bz, 10);

// output until end of the file (or the next 1024 char) and close it.  
print bzread($bz);

bzclose($bz);

?>
]]>
     </programlisting>
    </example>
   </sect1>
  </partintro>


  <refentry id="function.bzclose">
   <refnamediv>
    <refname>bzclose</refname>
    <refpurpose>Close a bzip2 file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>bzclose</methodname>
      <methodparam><type>int</type><parameter>bz</parameter></methodparam>
     </methodsynopsis>
    <para>
     Closes the bzip2 file referenced by the pointer <parameter>bz</parameter>.
    </para>
    <para>
     Returns &true; on success and &false; on failure.
    </para>
    <para>
     The file pointer must be valid, and must point to a file
     successfully opened by <function>bzopen</function>.
    </para>
    <para>
     See also <function>bzopen</function>.
    </para>
   </refsect1>
  </refentry>

  
  <refentry id="function.bzcompress">
   <refnamediv>
    <refname>bzcompress</refname>
    <refpurpose>Compress a string into bzip2 encoded data</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>bzcompress</methodname>
      <methodparam><type>string</type><parameter>source</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>blocksize</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>workfactor</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>bzcompress</function> compresses the
     <parameter>source</parameter> string and returns it as bzip2
     encoded data.
    </para>
    <para>
     The optional parameter <parameter>blocksize</parameter> specifies
     the blocksize used during compression and should be a number from
     1 to 9 with 9 giving the best compression, but using more
     resources to do so. <parameter>blocksize</parameter> defaults to
     4.
    </para>
    <para>
     The optional parameter <parameter>workfactor</parameter> controls
     how the compression phase behaves when presented with worst case,
     highly repetitive, input data.  The value can be between 0 and
     250 with 0 being a special case and 30 being the default
     value. Regardless of the <parameter>workfactor</parameter>, the
     generated output is the same.
    </para>
    <para>
     <example>
      <title><function>bzcompress</function> Example</title>
      <programlisting role="php">
<![CDATA[
<?php
$str = "sample data";
$bzstr = bzcompress($str, 9);
print( $bzstr );
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     See also <function>bzdecompress</function>.
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.bzdecompress">
   <refnamediv>
    <refname>bzdecompress</refname>
    <refpurpose>Decompresses bzip2 encoded data</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>bzdecompress</methodname>
      <methodparam><type>string</type><parameter>source</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>small</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>bzdecompress</function> decompresses the
     <parameter>source</parameter> string containing bzip2 encoded
     data and returns it.  If the optional parameter
     <parameter>small</parameter> is &true;, an alternative
     decompression algorithm will be used which uses less memory (the
     maximum memory requirement drops to around 2300K) but works at
     roughly half the speed.  See the <ulink url="&url.bzip2;">bzip2
     documentation</ulink> for more information about this feature.
    </para>
    <para>
     <example>
      <title><function>bzdecompress</function></title>
      <programlisting role="php">
<![CDATA[
<?php
$start_str = "This is not an honest face?";
$bzstr = bzcompress($start_str);

print( "Compressed String: " );
print( $bzstr );
print( "\n<br>\n" );

$str = bzdecompress($bzstr);
print( "Decompressed String: " );
print( $str );
print( "\n<br>\n" );
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     See also <function>bzcompress</function>.
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.bzerrno">
   <refnamediv>
    <refname>bzerrno</refname>
    <refpurpose>Returns a bzip2 error number</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>bzerrno</methodname>
      <methodparam><type>int</type><parameter>bz</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the error number of any bzip2 error returned by the file
     pointer <parameter>bz</parameter>.
    </para>
    <para>
     See also <function>bzerror</function> and <function>bzerrstr</function>.
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.bzerror">
   <refnamediv>
    <refname>bzerror</refname>
    <refpurpose>Returns the bzip2 error number and error string in an array</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>bzerror</methodname>
      <methodparam><type>int</type><parameter>bz</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the error number and error string, in an associative array,
     of any bzip2 error returned by the file pointer
     <parameter>bz</parameter>.
    </para>
    <para>
     <example>
      <title><function>bzerror</function> Example</title>
      <programlisting role="php">
<![CDATA[
<?php
$error = bzerror($bz);

echo $error["errno"];
echo $error["errstr"];
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     See also <function>bzerrno</function> and <function>bzerrstr</function>.
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.bzerrstr">
   <refnamediv>
    <refname>bzerrstr</refname>
    <refpurpose>Returns a bzip2 error string</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>bzerrstr</methodname>
      <methodparam><type>int</type><parameter>bz</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the error string of any bzip2 error returned by the file
     pointer <parameter>bz</parameter>.
    </para>
    <para>
     See also <function>bzerrno</function> and <function>bzerror</function>.
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.bzflush">
   <refnamediv>
    <refname>bzflush</refname>
    <refpurpose>Force a write of all buffered data</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>bzflush</methodname>
      <methodparam><type>int</type><parameter>bz</parameter></methodparam>
     </methodsynopsis>
    <para>
     Forces a write of all buffered bzip2 data for the file pointer
     <parameter>bz</parameter>.
    </para>
    <para>
     &return.success;
    </para>
    <para>
     See also <function>bzread</function> and <function>bzwrite</function>.
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.bzopen">
   <refnamediv>
    <refname>bzopen</refname>
    <refpurpose>Open a bzip2 compressed file</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>bzopen</methodname>
      <methodparam><type>string</type><parameter>filename</parameter></methodparam>
      <methodparam><type>string</type><parameter>mode</parameter></methodparam>
     </methodsynopsis>
    <para>
     Opens a bzip2 (.bz2) file for reading or writing.
     <parameter>filename</parameter> is the name of the file to
     open. <parameter>mode</parameter> is similar to the
     <function>fopen</function> function (`r' for read, `w' for write, etc.).
    </para>
    <para>
     If the open fails, the function returns &false;, otherwise it
     returns a pointer to the newly opened file.
    </para>
    <para>
     <example>
      <title><function>bzopen</function> Example</title>
      <programlisting role="php">
<![CDATA[
<?php
$bz = bzopen("/tmp/foo.bz2", "r");
$decompressed_file = bzread($bz, filesize("/tmp/foo.bz2"));
bzclose($bz);

print( "The contents of /tmp/foo.bz2 are: " );
print( "\n<br>\n" );
print( $decompressed_file );
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     See also <function>bzclose</function>.
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.bzread">
   <refnamediv>
    <refname>bzread</refname>
    <refpurpose>Binary safe bzip2 file read</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>bzread</methodname>
      <methodparam><type>int</type><parameter>bz</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>bzread</function> reads up to
     <parameter>length</parameter> bytes from the bzip2 file pointer
     referenced by <parameter>bz</parameter>.  Reading stops when
     <parameter>length</parameter> (uncompressed) bytes have been read
     or EOF is reached, whichever comes first.  If the optional
     parameter <parameter>length</parameter> is not specified,
     <function>bzread</function> will read 1024 (uncompressed) bytes
     at a time.
    </para>
    <para>
     <example>
      <title><function>bzread</function> Example</title>
      <programlisting role="php">
<![CDATA[
<?php
$bz = bzopen("/tmp/foo.bz2", "r");
$str = bzread($bz, 2048);
print( $str );
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     See also <function>bzwrite</function> and <function>bzopen</function>.
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.bzwrite">
   <refnamediv>
    <refname>bzwrite</refname>
    <refpurpose>Binary safe bzip2 file write</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>bzwrite</methodname>
      <methodparam><type>int</type><parameter>bz</parameter></methodparam>
      <methodparam><type>string</type><parameter>data</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>bzwrite</function> writes the contents of the string
     <parameter>data</parameter> to the bzip2 file stream pointed to
     by <parameter>bz</parameter>. If the optional
     <parameter>length</parameter> argument is given, writing will stop
     after length (uncompressed) bytes have been written or the end of
     string is reached, whichever comes first.
    </para>
    <para>
     <example>
      <title><function>bzwrite</function> Example</title>
      <programlisting role="php">
<![CDATA[
<?php
$str = "uncompressed data";
$bz = bzopen("/tmp/foo.bz2", "w");
bzwrite($bz, $str, strlen($str));
bzclose($bz);
?>
]]>
      </programlisting> 
     </example>
    </para>
    <para>
     See also <function>bzread</function> and <function>bzopen</function>.
    </para>
   </refsect1>
  </refentry>


 </reference>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->