php-doc-en/functions/zlib.sgml

 <reference id="ref.zlib">
  <title>Compression functions</title>
  <titleabbrev>Zlib</titleabbrev>
  <partintro>
  <para>
   This module uses the functions of <ulink
   url="&url.zlib;">zlib</ulink> by Jean-loup Gailly and Mark Adler to
   transparently read and write gzip (.gz) compressed files. You have
   to use a zlib version >= 1.0.9 with this module.
  </para>
  <para>
   This module contains versions of most of the <link
   linkend="ref.filesystem">filesystem</link> functions which work
   with gzip-compressed files (and uncompressed files, too, but not
   with sockets).
  </para>

   <sect1 id="zlib-example">
    <title>Small code example</title>
     <para>
      Opens a temporary file and writes a test string to it, then it
      prints out the content of this file twice.
     </para>

    <example>
     <title>Small Zlib example</title>
<programlisting role=php>
&lt;?php
  $filename = tempnam('/tmp', 'zlibtest').'.gz';
  print "&lt;html>\n&lt;head>&lt;/head>\n&lt;body>\n&lt;pre>\n";
  $s = "Only a test, test, test, test, test, test, test, test!\n";
  // open file for writing with maximum compression
  $zp = gzopen($filename, "w9");
  // write string to file
  gzwrite($zp, $s);
  // close file
  gzclose($zp);
  // open file for reading
  $zp = gzopen($filename, "r");
  // read 3 char
  print gzread($zp, 3);
  // output until end of the file and close it.
  gzpassthru($zp);
  print "\n";
  // open file and print content (the 2nd time).
  if (readgzfile($filename) != strlen($s)) {
          echo "Error with zlib functions!";
  }
  unlink($filename);
  print "&lt;pre>\n&lt;/h1>&lt;/body>\n&lt;/html>\n";
?>
</programlisting>
    </example>

  </partintro>

  <refentry id="function.gzclose">
   <refnamediv>
    <refname>gzclose</refname>
    <refpurpose>close an open gz-file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>gzclose</function></funcdef>
     <paramdef>int <parameter>zp</parameter></paramdef>
    </funcsynopsis>
    <para>
     The gz-file pointed to by zp is closed.

    <para>
     Returns true on success and false on failure.

    <para>
     The gz-file pointer must be valid, and must point to a file
     successfully opened by <function>gzopen</function>.

   </refsect1>
  </refentry>


  <refentry id="function.gzeof">
   <refnamediv>
    <refname>gzeof</refname>
    <refpurpose>test for end-of-file on a gz-file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>gzeof</function></funcdef>
     <paramdef>int <parameter>zp</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns true if the gz-file pointer is at EOF or an error occurs;
     otherwise returns false.

    <para>
     The gz-file pointer must be valid, and must point to a file
     successfully opened by <function>gzopen</function>.

   </refsect1>
  </refentry>


  <refentry id="function.gzfile">
   <refnamediv>
    <refname>gzfile</refname> <refpurpose>read entire gz-file into an
    array</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>array <function>gzfile</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
     <paramdef>int <parameter><optional>use_include_path</optional></parameter></paramdef>
    </funcsynopsis>
    <para> Identical to <function>readgzfile</function>, except that gzfile()
     returns the file in an array.

    <para>
     You can use the optional second parameter and set it to "1", if
     you want to search for the file in the <link
     linkend="ini.include-path">include_path</link>, too.

    <para> See also <function>readgzfile</function>, and
     <function>gzopen</function>.
   </refsect1>
  </refentry>


  <refentry id="function.gzgetc">
   <refnamediv>
    <refname>gzgetc</refname>
    <refpurpose>get character from gz-file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>gzgetc</function></funcdef>
     <paramdef>int <parameter>zp</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns a string containing a single (uncompressed) character
     read from the file pointed to by zp.  Returns FALSE on EOF (as
     does <function>gzeof</function>).
    <para>
     The gz-file pointer must be valid, and must point to a file
     successfully opened by <function>gzopen</function>.

    <para> See also
     <function>gzopen</function>, and
     <function>gzgets</function>.

   </refsect1>
  </refentry>


  <refentry id="function.gzgets">
   <refnamediv>
    <refname>gzgets</refname>
    <refpurpose>get line from file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>gzgets</function></funcdef>
     <paramdef>int <parameter>zp</parameter></paramdef>
     <paramdef>int <parameter>length</parameter></paramdef>
    </funcsynopsis>

    <para>
     Returns a (uncompressed) string of up to length - 1 bytes read
     from the file pointed to by fp. Reading ends when length - 1
     bytes have been read, on a newline, or on EOF (whichever comes
     first).

    <para> If an error occurs, returns false.

    <para> The file pointer must be valid, and must point to a file
     successfully opened by <function>gzopen</function>.

    <para> See also <function>gzopen</function>,
     <function>gzgetc</function>, and <function>fgets</function>.

   </refsect1>
  </refentry>


  <refentry id="function.gzgetss">
   <refnamediv>
    <refname>gzgetss</refname>
    <refpurpose>get line from gz-file pointer and strip HTML tags</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>gzgetss</function></funcdef>
     <paramdef>int <parameter>zp</parameter></paramdef>
     <paramdef>int <parameter>length</parameter></paramdef>
     <paramdef>string <parameter><optional>allowable_tags</optional></parameter></paramdef>
    </funcsynopsis>
    <para>
     Identical to <function>gzgets</function>,
     except that gzgetss attempts to strip any HTML and PHP tags from
     the text it reads.
    <para>
     You can use the optional third parameter to specify tags which
     should not be stripped.

    <note>
     <para>
      <parameter>allowable_tags</parameter> was added in PHP 3.0.13, PHP4B3.
    </note>

    <para>
     See also <function>gzgets</function>,
     <function>gzopen</function>, and <function>strip_tags</function>.

   </refsect1>
  </refentry>


  <refentry id="function.gzopen">
   <refnamediv>
    <refname>gzopen</refname>
    <refpurpose>open gz-file</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>gzopen</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
     <paramdef>string <parameter>mode</parameter></paramdef>
     <paramdef>int <parameter><optional>use_include_path</optional></parameter></paramdef>
    </funcsynopsis>
    <para>
     Opens a gzip (.gz) file for reading or writing. The mode
     parameter is as in <function>fopen</function> ("rb" or "wb") but
     can also include a compression level ("wb9") or a strategy: 'f'
     for filtered data as in "wb6f", 'h' for Huffman only compression
     as in "wb1h". (See the description of deflateInit2 in zlib.h for
     more information about the strategy parameter.)

    <para>
     Gzopen can be used to read a file which is not in gzip format; in
     this case <function>gzread</function> will directly read from the
     file without decompression.

    <para>
     Gzopen returns a file pointer to the file opened, after that,
     everything you read from this file descriptor will be
     transparently decompressed and what you write gets compressed.

    <para>
     If the open fails, the function returns false.

    <para>
     You can use the optional third parameter and set it to "1", if
     you want to search for the file in the <link
     linkend="ini.include-path">include_path</link>, too.

    <para><example>
      <title>gzopen() example</title>
      <programlisting>
$fp = gzopen("/tmp/file.gz", "r");
</programlisting></example>

    <para>
     See also <function>gzclose</function>.

   </refsect1>
  </refentry>


  <refentry id="function.gzpassthru">
   <refnamediv>
    <refname>gzpassthru</refname>
    <refpurpose>output all remaining data on a gz-file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>gzpassthru</function></funcdef>
     <paramdef>int <parameter>zp</parameter></paramdef>
    </funcsynopsis>
    <para>
     Reads to EOF on the given gz-file pointer and writes the
     (uncompressed) results to standard output.

    <para>
     If an error occurs, returns false.

    <para>
     The file pointer must be valid, and must point to a file
     successfully opened by <function>gzopen</function>.

    <para>
     The gz-file is closed when <function>gzpassthru</function> is
     done reading it (leaving <parameter>zp</parameter> useless).

   </refsect1>
  </refentry>


  <refentry id="function.gzputs">
   <refnamediv>
    <refname>gzputs</refname>
    <refpurpose>write to a gz-file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>gzputs</function></funcdef>
     <paramdef>int <parameter>zp</parameter></paramdef>
     <paramdef>string <parameter>str</parameter></paramdef>
     <paramdef>int <parameter><optional>length</optional></parameter></paramdef>
    </funcsynopsis>

    <para>
     <function>gzputs</function> is an alias to
     <function>gzwrite</function>, and is identical in every way.

   </refsect1>
  </refentry>


  <refentry id="function.gzread">
   <refnamediv>
    <refname>gzread</refname>
    <refpurpose>Binary-safe gz-file read</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>gzread</function></funcdef>
     <paramdef>int <parameter>zp</parameter></paramdef>
     <paramdef>int <parameter>length</parameter></paramdef>
    </funcsynopsis>
    <simpara>
     <function>gzread</function> reads up to
     <parameter>length</parameter> bytes from the gz-file pointer
     referenced by <parameter>zp</parameter>. Reading stops when
     <parameter>length</parameter> (uncompressed) bytes have been read
     or EOF is reached, whichever comes first.

    <para>
    <informalexample>
      <programlisting>
// get contents of a gz-file into a string
$filename = "/usr/local/something.txt.gz";
$zd = gzopen( $filename, "r" );
$contents = gzread( $zd, 10000 );
gzclose( $zd );
      </programlisting>
     </informalexample>

    <simpara>
     See also <function>gzwrite</function>, <function>gzopen</function>,
     <function>gzgets</function>, <function>gzgetss</function>,
     <function>gzfile</function>, and <function>gzpassthru</function>.
   </refsect1>
  </refentry>


  <refentry id="function.gzrewind">
   <refnamediv>
    <refname>gzrewind</refname>
    <refpurpose>rewind the position of a gz-file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>gzrewind</function></funcdef>
     <paramdef>int <parameter>zp</parameter></paramdef>
    </funcsynopsis>
<para>    Sets the file position indicator for zp to the
    beginning of the file stream.
  <para>    If an error occurs, returns 0.
  <para> The file pointer must be valid, and must point to a file
  successfully opened by <function>gzopen</function>.
  <para>
    See also <function>gzseek</function> and <function>gztell</function>.

   </refsect1>
  </refentry>

  <refentry id="function.gzseek">
   <refnamediv>
    <refname>gzseek</refname>
    <refpurpose>seek on a gz-file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>gzseek</function></funcdef>
     <paramdef>int <parameter>zp</parameter></paramdef>
     <paramdef>int <parameter>offset</parameter></paramdef>
    </funcsynopsis>
    <para>
     Sets the file position indicator for the file referenced by zp to
     offset bytes into the file stream. Equivalent to calling (in C)
     <literal>gzseek( zp, offset, SEEK_SET )</literal>.

    <para>
     If the file is opened for reading, this function is emulated but
     can be extremely slow. If the file is opened for writing, only
     forward seeks are supported; gzseek then compresses a sequence of
     zeroes up to the new starting position.

    <para>
     Upon success, returns 0; otherwise, returns -1. Note that seeking
     past EOF is not considered an error.

    <para>
     See also <function>gztell</function> and
     <function>gzrewind</function>.

   </refsect1>
  </refentry>


  <refentry id="function.gztell">
   <refnamediv>
    <refname>gztell</refname>
    <refpurpose>tell gz-file pointer read/write position</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>gztell</function></funcdef>
     <paramdef>int <parameter>zp</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns the position of the file pointer referenced by zp; i.e.,
     its offset into the file stream.

    <para>
     If an error occurs, returns false.

    <para>
     The file pointer must be valid, and must point to a file
     successfully opened by <function>gzopen</function>.

    <para> See also <function>gzopen</function>,
    <function>gzseek</function> and <function>gzrewind</function>.

   </refsect1>
  </refentry>

  <refentry id="function.gzwrite">
   <refnamediv>
    <refname>gzwrite</refname>
    <refpurpose>Binary-safe gz-file write</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>gzwrite</function></funcdef>
     <paramdef>int <parameter>zp</parameter></paramdef>
     <paramdef>string <parameter>string</parameter></paramdef>
     <paramdef>int <parameter><optional>length</optional></parameter></paramdef>
    </funcsynopsis>
    <simpara>
     <function>gzwrite</function> writes the contents of
     <parameter>string</parameter> to the gz-file stream pointed to by
     <parameter>zp</parameter>. If the <parameter>length</parameter>
     argument is given, writing will stop after
     <parameter>length</parameter> (uncompressed) bytes have been
     written or the end of <parameter>string</parameter> is reached,
     whichever comes first.

    <simpara>
     Note that if the <parameter>length</parameter> argument is given,
     then the <link
     linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link>
     configuration option will be ignored and no slashes will be
     stripped from <parameter>string</parameter>. 

    <simpara>
     See also <function>gzread</function>, <function>gzopen</function>,
     and <function>gzputs</function>.
   </refsect1>
  </refentry>

  <refentry id="function.readgzfile">
   <refnamediv>
    <refname>readgzfile</refname>
    <refpurpose>output a gz-file</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>readgzfile</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
     <paramdef>int <parameter><optional>use_include_path</optional></parameter></paramdef>
    </funcsynopsis>
    <para> Reads a file, decompresses it and writes it to standard
    output.

    <para>
     Readgzfile() can be used to read a file which is not in gzip
     format; in this case readgzfile() will directly read from the
     file without decompression.

    <para> Returns the number of (uncompressed) bytes read from the
     file. If an error occurs, false is returned and unless the
     function was called as @readgzfile, an error message is printed.

    <para> The file <parameter>filename</parameter> will be opened
     from the filesystem and its contents written to standard output.

    <para>
     You can use the optional second parameter and set it to "1", if
     you want to search for the file in the <link
     linkend="ini.include-path">include_path</link>, too.

    <para>
     See also <function>gzpassthru</function>,
     <function>gzfile</function>, and <function>gzopen</function>.

   </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
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->