archived-doc-es/reference/filesystem/functions/flock.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 5eb641c91a7e3edbb5ab5a614225fdd6de925326 Maintainer: seros Status: ready -->
<!-- Reviewed: yes Maintainer: seros -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.flock">
 <refnamediv>
  <refname>flock</refname>
  <refpurpose>Bloqueo de ficheros recomendado y portable</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>flock</methodname>
   <methodparam><type>resource</type><parameter>handle</parameter></methodparam>
   <methodparam><type>int</type><parameter>operation</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter role="reference">wouldblock</parameter></methodparam>
  </methodsynopsis>
  <para>
   <function>flock</function> permite representar un modelo sencillo de lectura/escritura
   que puede emplearse virtualmente en cada plataforma (incluidas la mayoría de las derivadas
   de Unix e incluso Windows).
  </para>
  <para>
   En versiones de PHP anteriores a la 5.3.2, el bloqueo es liberado también por
   <function>fclose</function> (la cual es también llamada automáticamente cuando finaliza
   el script).
  </para>
  <para>
   PHP soporta de manera portable el bloqueo de ficheros completos de una forma recomendada
   (lo cual significa que todos los programas que accedan tiene que utilizar la misma forma de
   bloqueo o este no funcionará). Por defecto, esta función estará en espera hasta adquirir el bloqueo
   solicitado; esto se puede controlar con la opción <constant>LOCK_NB</constant> documentada abajo.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>handle</parameter></term>
     <listitem>
      &fs.file.pointer;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>operation</parameter></term>
     <listitem>
      <para>
       <parameter>operation</parameter> es una operación de las siguientes:
       <itemizedlist>
        <listitem>
         <simpara>
          <constant>LOCK_SH</constant> para adquirir un bloqueo compartido (lectura).
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>LOCK_EX</constant> para adquirir un bloqueo exclusivo (escritura).
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>LOCK_UN</constant> para liberar un bloqueo (compartido o exclusivo).
         </simpara>
        </listitem>
       </itemizedlist>
      </para>
      <para>
       También es posible añadir <constant>LOCK_NB</constant> como una máscara de bit
       a una de las operaciones de arriba si no se desea que <function>flock</function>
       quede esperando mientras obtiene el bloqueo.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>wouldblock</parameter></term>
     <listitem>
      <para>
       El tercer argumento opcional se establece a 1 si el bloqueo hará que la función quede esperando
       (condición de errno EWOULDBLOCK).
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>
 
 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>5.5.22, 5.6.6</entry>
       <entry>
        Se añadió soporte para el parámetro <parameter>wouldblock</parameter> en
        Windows.
       </entry>
      </row>
      <row>
       <entry>5.3.2</entry>
       <entry>
        Se eliminó la liberación del bloqueo automática al cerrarse el manejador del
        recurso. La liberación del bloqueo ahora siempre tiene que realizarse manualmente.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplo de <function>flock</function></title>
    <programlisting role="php">
<![CDATA[
<?php

$fp = fopen("/tmp/lock.txt", "r+");

if (flock($fp, LOCK_EX)) {  // adquirir un bloqueo exclusivo
    ftruncate($fp, 0);      // truncar el fichero
    fwrite($fp, "Escribir algo aquí\n");
    fflush($fp);            // volcar la salida antes de liberar el bloqueo
    flock($fp, LOCK_UN);    // libera el bloqueo
} else {
    echo "¡No se pudo obtener el bloqueo!";
}

fclose($fp);

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>flock</function> usando la opción <constant>LOCK_NB</constant></title>
    <programlisting role="php">
<![CDATA[
<?php
$fp = fopen('/tmp/lock.txt', 'r+');

/* Activar la opción LOCK_NB sobre una operación LOCK_EX */
if(!flock($fp, LOCK_EX | LOCK_NB)) {
    echo 'No se puede obtener el bloqueo';
    exit(-1);
}

/* ... */

fclose($fp);
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    En Windows, <function>flock</function> usa el bloqueo obligado en lugar del
    bloqueo recomendado. El bloqueo obligado también está soportado en sistemas operativos
    basados en Linux y System V mediante el mecanismo habitual soportado por la
    llamada al sistema fcntl(): esto es, si el fichero en cuestión tiene el bit de
    permiso setgid establecido y el bit de ejecución de grupo despejado. Para que esto funcione
    en Linux, el sistema de ficheros también debe ser montado con la opción mand.
   </para>
  </note>
  <note>
   <para>
    Ya que <function>flock</function> requiere un puntero a un fichero, puede ser necesario
    usar un fichero de bloqueo especial para proteger el acceso al fichero que se quiere
    truncar, abriéndolo en modo escritura (con un argumento "w" o "w+" de
    <function>fopen</function>).
   </para>
  </note>
  <note>
   <para>
    Sólo se puede usar en punteros de ficheros devueltos por <function>fopen</function>
    para ficheros locales, o punteros de ficheros que apuenten a flujos de espacios de usuario que
    implementen el método <function>streamWrapper::stream_lock</function>.
   </para>
  </note>
  <warning>
   <para>
    Asignar otro valor al argumento <parameter>handle</parameter> en el
    código subsiguiente liberará el bloqueo.
   </para>
  </warning>
  <warning>
   <para>
    En algunos sistemas operativos <function>flock</function> está implementado a
    nivel de proceso. Cuando se usa una API de servidor multihilo como ISAPI, no
    se podrá confiar en <function>flock</function> para proteger ficheros contra
    otros scripts de PHP que se ejecuten en hilos paralelos en la misma instancia del
    servidor.
   </para>
   <para>
    <function>flock</function> no está soportado en sistemas de ficheros anticuados como
    <literal>FAT</literal> y sus derivados y por lo tanto siempre
    devuelve &false; bajo estos entornos (esto es especialmente válido para
    usuarios de Windows 98).
   </para>
  </warning>
 </refsect1>
 
</refentry>

<!-- 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:"~/.phpdoc/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
-->