<?xml version="1.0" encoding="iso-8859-1"?>
 <reference id="ref.zlib">
  <title>Funciones de Compresi&oacute;n</title>
  <titleabbrev>Zlib</titleabbrev>
  <partintro>
  <para>
   Este m&oacute;dulo usa la funci&oacute;n de <ulink url="&url.zlib;">zlib</ulink> de Jean-loup Gailly y Mark Adler para
   leer y grabar archivos comprimidos .gz, de un modo transparente. Con este m&oacute;dulo, es requisito usar una versi&oacute;n
   de zlib igual o posterior a 1.0.9.
  </para>
  <para>
   Este m&oacute;dulo contiene versiones de la mayor&iacute;a de las funciones de <link linkend="ref.filesystem">Sistema de archivos</link>
   que funcionan con los archivos comprimidos con gzip (y con los no-comprimidos tambien, pero no con conectores (sockets)).
  </para>

   <sect1 id="zlib-example">
    <title>Peque&ntilde;o c&oacute;digo de ejemlo</title>
     <para>
      Abre un archivo temporal y escribe en &eacute;l, una cadena de prueba, y luego presenta el
      cotenido del archivo dos veces
     </para>

    <example>
     <title>Ejemplo de Zlib</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 = "S&oacute;lo es una prueba, prueba, prueba,prueba, prueba, prueba!\n";
  // Abre el archivo para escribirlo con m&aacute;ximo de compresi&oacute;n
  $zp = gzopen($filename, "w9");
  // Escribe la cadena en &eacute;l
  gzwrite($zp, $s);
  // Cierra el fichero
  gzclose($zp);
  // Abre el fichero para lectura
  $zp = gzopen($filename, "r");
  // Lee 3 caracteres
  print gzread($zp, 3);
  // Salida hasta el final del fichero, para cerrarlo luego.
  gzpassthru($zp);
  print "\n";
  // Abre el fichero y muestra su contenido (por segunda vez).
  if (readgzfile($filename) != strlen($s)) {
          echo "Error con las funciones zlib!";
  }
  unlink($filename);
  print "&lt;pre>\n&lt;/h1>&lt;/body>\n&lt;/html>\n";
?>
</programlisting>
    </example></sect1>

  </partintro>

  <refentry id="function.gzclose">
   <refnamediv>
    <refname>gzclose</refname>
    <refpurpose>cierra un puntero a archivo-gz abierto</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripci&oacute;n</title>
     <methodsynopsis>
     <type>int</type><methodname>gzclose</methodname>
     <methodparam><type>int</type><parameter>zp</parameter></methodparam>
     </methodsynopsis>
    <para>
     El archivo-gz al que apunta zp se cierra.</para>

    <para>
     Devuelve &true; (verdadero) si fue exitoso, si hubo errores devuelve &false;.</para>

    <para>
     El puntero al archivo-gz debe ser v&aacute;lido y debe apuntar
     a un archivo correctamente abierto con <function>gzopen</function>.</para>

   </refsect1>
  </refentry>


  <refentry id="function.gzeof">
   <refnamediv>
    <refname>gzeof</refname>
    <refpurpose>prueba el fin-de-archivo de un puntero de archivo-gz</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripci&oacute;n</title>
     <methodsynopsis>
     <type>int</type><methodname>gzeof</methodname>
     <methodparam><type>int</type><parameter>zp</parameter></methodparam>
     </methodsynopsis>
    <para>
     Devuelve verdadero si el puntero-a-archivo est&aacute; en el fin-de-archivo, o ha
     ocurrido un error. De otro modo devuelve falso.</para>

    <para>
     El puntero al archivo-gz debe ser v&aacute;lido y debe apuntar
     a un archivo correctamente abierto con <function>gzopen</function>.</para>

   </refsect1>
  </refentry>


  <refentry id="function.gzfile">
   <refnamediv>
    <refname>gzfile</refname> <refpurpose>lee el archivo gz completo en un arreglo</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripci&oacute;n</title>
     <methodsynopsis>
     <type>array</type><methodname>gzfile</methodname>
     <methodparam><type>string</type><parameter>nombre_archivo</parameter></methodparam>
     <methodparam choice="opt"><type>int</type><parameter>usar_include_path</parameter></methodparam>
     </methodsynopsis>
    <para> Identico a <function>readgzfile</function>, solo que gzfile()
     devuelve el fichero en un arreglo.</para>

    <para>
     Se puede usar el segundo par&aacute;metro opcional poni&eacute;ndolo a  "1",
     si se quiere que la funci&oacute;n busque tambi&eacute;n el archivo en la trayectoria definida como <link linkend="ini.include-path">include_path.</link></para>

    <para> Vea tambi&eacute;n <function>readgzfile</function>, y
     <function>gzopen</function>.</para>
   </refsect1>
  </refentry>


  <refentry id="function.gzgetc">
   <refnamediv>
    <refname>gzgetc</refname>
    <refpurpose>toma caracteres de un archivo-gz</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripci&oacute;n</title>
     <methodsynopsis>
     <type>cadena</type><methodname>gzgetc</methodname>
     <methodparam><type>int</type><parameter>zp</parameter></methodparam>
     </methodsynopsis>
    <para>
     Devuelve una cadena conteniendo un caracter en particular (sin comprimir)
     le&iacute;do del archivo al que apunta zp.  Devuelve &false; cuando est&aacute; al final
     del archivo (al igual que <function>gzeof</function>).</para>
    <para>
     El puntero al archivo-gz debe ser v&aacute;lido y debe apuntar
     a un archivo correctamente abierto con <function>gzopen</function>.</para>

    <para> Vea tambi&eacute;n
     <function>gzopen</function>, y
     <function>gzgets</function>.</para>

   </refsect1>
  </refentry>


  <refentry id="function.gzgets">
   <refnamediv>
    <refname>gzgets</refname>
    <refpurpose>toma una linea del archivo apuntado</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripci&oacute;n</title>
     <methodsynopsis>
     <type>string</type><methodname>gzgets</methodname>
     <methodparam><type>int</type><parameter>zp</parameter></methodparam>
     <methodparam><type>int</type><parameter>longitud</parameter></methodparam>
     </methodsynopsis>

    <para>
     Devuelve una cadena (descomprimida) con longitud - 1 bytes de largo,
     le&iacute;da del archivo apuntado por fp. La lectura finaliza cuando se han le&iacute;do longitud - 1
     bytes, ante un salto de linea o un fin-de-archivo (lo que ocurra primero).</para>

    <para> Si ocurre un error, devuelve falso.</para>

    <para>
     El puntero al archivo-gz debe ser v&aacute;lido y debe apuntar
     a un archivo correctamente abierto con <function>gzopen</function>.</para>

    <para> Vea tambi&eacute;n <function>gzopen</function>,
     <function>gzgetc</function>, y <function>fgets</function>.</para>

   </refsect1>
  </refentry>


  <refentry id="function.gzgetss">
   <refnamediv>
    <refname>gzgetss</refname>
    <refpurpose>toma una linea del archivo-gz apuntado y le quita los tags HTML</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripci&oacute;n</title>
     <methodsynopsis>
     <type>string</type><methodname>gzgetss</methodname>
     <methodparam><type>int</type><parameter>zp</parameter></methodparam>
     <methodparam><type>int</type><parameter>longitud</parameter></methodparam>
     <methodparam choice="opt"><type>string</type><parameter>tags_permitidos</parameter></methodparam>
     </methodsynopsis>
    <para>
     Id&eacute;ntica a <function>gzgets</function>,
     excepto que gzgetss intenta quitar cualquier "tag" HTML o PHP del texto que lee.</para>
    <para>
     Se puede usar el tercer par&aacute;metro para indicar qu&eacute; parametros no deben ser extra&iacute;dos.

    <note>
     <para>
      <parameter>tags_permitidos</parameter> fue agregado en la versi&oacute;n de PHP 3.0.13, PHP4B3.</para>
    </note></para>

    <para>
     V&eacute;ase tambi&eacute;n <function>gzgets</function>,
     <function>gzopen</function>, y <function>strip_tags</function>.</para>

   </refsect1>
  </refentry>

  <refentry id="function.gzopen">
   <refnamediv>
    <refname>gzopen</refname>
    <refpurpose>open gz-file</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripci&oacute;n</title>
     <methodsynopsis>
     <type>int</type><methodname>gzopen</methodname>
     <methodparam><type>string</type><parameter>nombre_fichero</parameter></methodparam>
     <methodparam><type>string</type><parameter>modo</parameter></methodparam>
     <methodparam choice="opt"><type>int</type><parameter>use_include_path</parameter></methodparam>
     </methodsynopsis>
    <para>
     Abre un archivo gzip (.gz) para lectura o escritura. El par&aacute;metro
     modo es, como en <function>fopen</function> ("rb" o "wb") pero
     puede incluir tambien el nivel de compresi&oacute;n ("wb9") o la estrategia: 'f'
     para filtrado de datos como en "wb6f", 'h' para comprimir solo por Huffman
     igual que en "wb1h". (Ver la descripci&oacute;n de deflateInit2 en zlib.h para m&aacute;s
     informaci&oacute;n sobre el par&aacute;metro de estrategia.)</para>

    <para>
     Gzopen puede usarse para leer o escribir un fichero que no est&eacute; en formato gzip; en
     ese caso <function>gzread</function> leer&aacute; el archivo directamente, sin descomprimirlo.</para>

    <para>
     Gzopen devuelve un puntero al archivo abierto y luego, cualquier proceso de lectura o escritura
     relacionado con ese descriptor de archivo, ser&aacute; transparente: se comprimir&aacute; o descomprimir&aacute;
     los datos seg&uacute;n la necesidad, de manera autom&aacute;tica.</para>

    <para>
     Si la apertura fallase, se devolver&aacute; falso.</para>

    <para>
     Se puede usar el tercer par&aacute;metro opcional, poni&eacute;ndolo a  "1", si se
     quiere buscar tambi&eacute;n el fichero en la trayectoria <link linkend="ini.include-path">include_path</link>.</para>

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

    <para>
     Vea tambi&eacute;n <function>gzclose</function>.</para>

   </refsect1>
  </refentry>


  <refentry id="function.gzpassthru">
   <refnamediv>
    <refname>gzpassthru</refname>
    <refpurpose>Devuelve el remanente de datos de un fichero-gz</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripci&oacute;n</title>
     <methodsynopsis>
     <type>int</type><methodname>gzpassthru</methodname>
     <methodparam><type>int</type><parameter>zp</parameter></methodparam>
     </methodsynopsis>
    <para>
     Lee hasta el Fin-De-Archivo del archivo gz dado,  y escribe los resultados
     (descomprimidos) en la salida standard.</para>

    <para>
     Si ocurre un error, devuelve Falso.</para>

    <para>
     El puntero al archivo-gz debe ser v&aacute;lido y debe apuntar
     a un archivo correctamente abierto con <function>gzopen</function>.</para>

    <para>
     El archivo-gz es cerrado cuando <function>gzpassthru</function> termina de leerlo
     (dejando <parameter>zp</parameter> sin utilidad).</para>

   </refsect1>
  </refentry>


  <refentry id="function.gzputs">
   <refnamediv>
    <refname>gzputs</refname>
    <refpurpose>escribe al fichero-gz que se apunta</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripci&oacute;n</title>
     <methodsynopsis>
     <type>int</type><methodname>gzputs</methodname>
     <methodparam><type>int</type><parameter>zp</parameter></methodparam>
     <methodparam><type>string</type><parameter>str</parameter></methodparam>
     <methodparam choice="opt"><type>int</type><parameter>longitud</parameter></methodparam>
     </methodsynopsis>

    <para>
     <function>gzputs</function> es un alias a
     <function>gzwrite</function>, y es absolutamente id&eacute;ntico.</para>

   </refsect1>
  </refentry>


  <refentry id="function.gzread">
   <refnamediv>
    <refname>gzread</refname>
    <refpurpose>Lee archivos-gz en modo Binario</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripci&oacute;n</title>
     <methodsynopsis>
     <type>string</type><methodname>gzread</methodname>
     <methodparam><type>int</type><parameter>zp</parameter></methodparam>
     <methodparam><type>int</type><parameter>longitud</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     <function>gzread</function> lee hasta
     <parameter>longitud</parameter> bytes del archivo-gz apuntado por el par&aacute;metro
     <parameter>zp</parameter>. La lectura termina cuando se han le&iacute;do
     <parameter>longitud</parameter> bytes (descomprimidos) o se
     alcanza el fin-de-archivo, lo que sucediera primero.</simpara>

    <para>
    <informalexample>
      <programlisting>
// Pone los contenidos del gz, a una cadena
$filename = "/usr/local/algo.txt.gz";
$zd = gzopen( $filename, "r" );
$contents = gzread( $zd, 10000 );
gzclose( $zd );
      </programlisting>
     </informalexample></para>

    <simpara>
     Ver tambi&eacute;n <function>gzwrite</function>, <function>gzopen</function>,
     <function>gzgets</function>, <function>gzgetss</function>,
     <function>gzfile</function>, y <function>gzpassthru</function>.</simpara>
   </refsect1>
  </refentry>


  <refentry id="function.gzrewind">
   <refnamediv>
    <refname>gzrewind</refname>
    <refpurpose>Reposiciona al puntero de archivo-gz, al inicio de aquel</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripci&oacute;n</title>
     <methodsynopsis>
     <type>int</type><methodname>gzrewind</methodname>
     <methodparam><type>int</type><parameter>zp</parameter></methodparam>
     </methodsynopsis>
<para>    Reubica el indicador de posici&oacute;n del archivo, al comienzo del mismo.</para>
  <para>    si surge un error, devuelve 0.</para>
  <para>  El puntero al archivo-gz debe ser v&aacute;lido y debe apuntar
     a un archivo correctamente abierto con <function>gzopen</function>.</para>
  <para>
    Ver tambi&eacute;n: <function>gzseek</function> y <function>gztell</function>.</para>

   </refsect1>
  </refentry>

  <refentry id="function.gzseek">
   <refnamediv>
    <refname>gzseek</refname>
    <refpurpose>Posiciona el puntero del archivo-gz</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripci&oacute;n</title>
     <methodsynopsis>
     <type>int</type><methodname>gzseek</methodname>
     <methodparam><type>int</type><parameter>zp</parameter></methodparam>
     <methodparam><type>int</type><parameter>offset</parameter></methodparam>
     </methodsynopsis>
    <para>
     Busca la posici&oacute;n dentro del archivo zp, indicada en bytes por el parametro de
     desplazamiento offset. Es equivalente a llamar (en C)
     <literal>gzseek( zp, offset, SEEK_SET )</literal>.</para>

    <para>
     Si el archivo se abre para lectura, la funci&oacute;n ser&aacute; emulada, pero puede ponerse
     extremadamente lenta. Si se trata de escritura, solo est&aacute; soportada
     la b&uacute;squeda hacia adelante; gzseek comprime entonces una secuencia de ceros
     hasta que alcanza la nueva ubicaci&oacute;n.</para>

    <para>
     Si se completa el pedido con &eacute;xito, devuelve 0; de lo contrario, devuelve -1. Note que la busqueda
     m&aacute;s all&aacute; del fin-de-archivo no se considera un error.</para>

    <para>
     Vea tambi&eacute;n <function>gztell</function> y
     <function>gzrewind</function>.</para>

   </refsect1>
  </refentry>


  <refentry id="function.gztell">
   <refnamediv>
    <refname>gztell</refname>
    <refpurpose>Indica la posici&oacute;n de lecto-escritura en el archivo</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripci&oacute;n</title>
     <methodsynopsis>
     <type>int</type><methodname>gztell</methodname>
     <methodparam><type>int</type><parameter>zp</parameter></methodparam>
     </methodsynopsis>
    <para>
     Devuelve la posici&oacute;n dentro del fichero referido por zp; p.e.,
     su desplazamiento en el cuerpo del archivo.</para>

    <para>
     Si hay alg&uacute;n error, devuelve falso.</para>

    <para>
     El puntero al archivo-gz debe ser v&aacute;lido y debe apuntar
     a un archivo correctamente abierto con <function>gzopen</function>.</para>

    <para> Ver tambi&eacute;n <function>gzopen</function>,
    <function>gzseek</function> y <function>gzrewind</function>.</para>

   </refsect1>
  </refentry>

  <refentry id="function.gzwrite">
   <refnamediv>
    <refname>gzwrite</refname>
    <refpurpose>Escritura de ficheros gz en modo Binario</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripci&oacute;n</title>
     <methodsynopsis>
     <type>int</type><methodname>gzwrite</methodname>
     <methodparam><type>int</type><parameter>zp</parameter></methodparam>
     <methodparam><type>string</type><parameter>cadena</parameter></methodparam>
     <methodparam choice="opt"><type>int</type><parameter>largo</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     <function>gzwrite</function> escribe el contenido de
     <parameter>cadena</parameter> al fichero gz referido por <parameter>zp</parameter>.
      Si el par&aacute;metro <parameter>largo</parameter>
     est&aacute; presente, se detendr&aacute; la escritura luego de escribir
     <parameter>largo</parameter> bytes (descomprimidos) o al llegar el final de la <parameter>cadena</parameter>,
      lo que ocurriese primero.</simpara>

    <simpara>
     Note que si se pasa el argumento <parameter>largo</parameter>,
     la opcion <link linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link>
     ser&aacute; ignorada y no se quitar&aacute;n barras de la <parameter>cadena</parameter> en cuesti&oacute;n.</simpara>

    <simpara>
     Ver tambi&eacute;n <function>gzread</function>, <function>gzopen</function>,
     y <function>gzputs</function>.</simpara>
   </refsect1>
  </refentry>

  <refentry id="function.readgzfile">
   <refnamediv>
    <refname>readgzfile</refname>
    <refpurpose>devuelve el fichero-gz</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Descripci&oacute;n</title>
     <methodsynopsis>
     <type>int</type><methodname>readgzfile</methodname>
     <methodparam><type>string</type><parameter>nombre_archivo</parameter></methodparam>
     <methodparam choice="opt"><type>int</type><parameter>usar_trayectoria_include</parameter></methodparam>
     </methodsynopsis>
    <para> Lee el archivo, lo descomprime y lo escribe en la salida est&aacute;ndar.</para>

    <para>
     Readgzfile() puede usarse para leer un archivo comprimido o no con gzip;
     en cuyo caso readgzfile() leer&aacute; directamente el archivo, sin descomprimirlo.</para>

    <para> Devuelve el numero de bytes (descomprimidos) le&iacute;dos del archivo,
    si ocurre un error, se devuelve falso y hasta que se llame como @readgzfile,
    se imprime un mensaje de error.</para>

    <para> El archivo <parameter>nombre_archivo</parameter> se abrir&aacute; en el sistema de archivos
     y su contenido enviado a la salida est&aacute;ndar.</para>

    <para>
     Puede usarse el segundo paametro opcional d&aacute;ndole el valor "1", si se quiere
     que se busque el archivo tambi&eacute;n dentro de la trayectoria "include": <link linkend="ini.include-path">include_path</link>.</para>

    <para>
     Ver tambi&eacute;n <function>gzpassthru</function>,
     <function>gzfile</function>, y <function>gzopen</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:
-->