cucinato Wed Oct 24 11:13:09 2001 EDT
Added files:
/phpdoc/it/functions bzip2.xml
Log:
added to IT tree.
Index: phpdoc/it/functions/bzip2.xml
+++ phpdoc/it/functions/bzip2.xml
<?xml encoding="iso-8859-1"?>
<!-- EN-Revision: 1.10 Maintainer: cucinato Status: working -->
<reference id="ref.bzip2">
<title>Funzioni di compressione Bzip2</title>
<titleabbrev>Bzip2</titleabbrev>
<partintro>
<para>
Questo modulo utilizza le funzioni della libreria <ulink
url="&url.bzip2;">bzip2</ulink> di Julian Seward per
leggere e scrivere in modo trasparente i file compressi con bzip2 (.bz2).
</para>
<para>
Il spporto di Bzip2 in PHP non è attivo per default. Si deve
usare l'opzione di configurazione <link
linkend="install.configure.with-bzip2">--with-bz2</link>
quando si compila PHP per sbilitare il supporto bzip2. Questo modulo
richiede bzip2/libbzip2 con versione >= 1.0.x.
</para>
<sect1 id="bzip2-example">
<title>Breve sorgente di esempio</title>
<para>
Questo esempio apre un file temporaneo e scrive una stringa di prova su
di esso, quindi stampa il contenuto del file.
</para>
<example>
<title>breve esempio di bzip2</title>
<programlisting role="php">
<?php
$nomefile = "/tmp/filediprova.bz2";
$str = "Questa è una stringa di prova.\n";
// apre il file in lettura
$bz = bzopen($nomefile, "w");
// scrive la stringa sul file
bzwrite($bz, $str);
// chiude il file
bzclose($bz);
// apre il file in lettura
$bz = bzopen($nomefile, "r");
// legge 10 caratteri
print bzread($bz, 10);
// stampa fino alla fine del file (o fino ai prossimi 1024 caratteri) e chiude il file.
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>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>bzclose</function></funcdef>
<paramdef>int <parameter>bz</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<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>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>bzcompress</function></funcdef>
<paramdef>string <parameter>source</parameter></paramdef>
<paramdef>int
<parameter><optional>blocksize</optional></parameter>
</paramdef>
<paramdef>int
<parameter><optional>workfactor</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<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"><?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>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>bzdecompress</function></funcdef>
<paramdef>string <parameter>source</parameter></paramdef>
<paramdef>int
<parameter><optional>small</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<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"><?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>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>bzerrno</function></funcdef>
<paramdef>int <parameter>bz</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<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>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>bzerror</function></funcdef>
<paramdef>int <parameter>bz</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<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"><?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>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>bzerrstr</function></funcdef>
<paramdef>int <parameter>bz</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<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>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>bzflush</function></funcdef>
<paramdef>int <parameter>bz</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Forces a write of all buffered bzip2 data for the file pointer
<parameter>bz</parameter>.
</para>
<para>
Returns &true; on success, &false; on failure.
</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>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>bzopen</function></funcdef>
<paramdef>string <parameter>filename</parameter></paramdef>
<paramdef>string <parameter>mode</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<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"><?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>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>bzread</function></funcdef>
<paramdef>int <parameter>bz</parameter></paramdef>
<paramdef>int
<parameter><optional>length</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<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"><?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>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>bzwrite</function></funcdef>
<paramdef>int <parameter>bz</parameter></paramdef>
<paramdef>string <parameter>data</parameter></paramdef>
<paramdef>int
<parameter><optional>length</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<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"><?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
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
-->
