mirror of
https://github.com/macintoshplus/doc-en.git
synced 2026-03-29 12:22:18 +02:00
7839d91186
removing the others git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@78562 c90b9560-bf6c-de11-be94-00142212c4b1
497 lines
14 KiB
XML
497 lines
14 KiB
XML
<!-- D O N O T E D I T T H I S F I L E ! ! !
|
|
|
|
it is still here for historical reasons only
|
|
(as translators may need to check old revision diffs)
|
|
|
|
if you want to change things documented in this file
|
|
you should now edit the files found under en/reference
|
|
instead -->
|
|
|
|
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.21 $ -->
|
|
<reference id="ref.bzip2">
|
|
<title>Bzip2 Compression Functions</title>
|
|
<titleabbrev>Bzip2</titleabbrev>
|
|
|
|
<partintro>
|
|
<para id="bzip2.intro">
|
|
The bzip2 functions are used to transparently read and write bzip2 (.bz2)
|
|
compressed files.
|
|
</para>
|
|
|
|
<section id="bzip2.requirements">
|
|
<title>Requirements</title>
|
|
<para>
|
|
This module uses the functions of the <ulink
|
|
url="&url.bzip2;">bzip2</ulink> library by Julian Seward
|
|
</para>
|
|
</section>
|
|
|
|
<section id="bzip2.installation">
|
|
<title>Installation</title>
|
|
<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 >= 1.0.x.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="bzip2.configuration">
|
|
<title>Runtime Configuration</title>
|
|
&no.config;
|
|
</section>
|
|
|
|
<section id="bzip2.resources">
|
|
<title>Resource types</title>
|
|
<para>
|
|
This extension defines one resource type: a file pointer identifying
|
|
the bz2-file to work on.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="bzip2.constants">
|
|
<title>Predefined constants</title>
|
|
&no.constants;
|
|
</section>
|
|
|
|
<section id="bzip2.examples">
|
|
<title>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>
|
|
</section>
|
|
</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>resource</type><parameter>bz</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Closes the bzip2 file referenced by the pointer <parameter>bz</parameter>.
|
|
</para>
|
|
<para>
|
|
&return.success;
|
|
</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>resource</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>resource</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>resource</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>resource</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>resource</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>resource</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>resource</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
|
|
-->
|
|
|