flock.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 0bfb0eb957e0468912af86bba09fae588010c1df Maintainer: shein Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.flock" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>flock</refname>
  <refpurpose>Блокирует файл методом переносимой рекомендательной блокировки</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>flock</methodname>
   <methodparam><type>resource</type><parameter>stream</parameter></methodparam>
   <methodparam><type>int</type><parameter>operation</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter role="reference">would_block</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Функция <function>flock</function> разрешает выполнять простую модель
   чтения-записи, которая будет работать на большей части Unix-платформ
   и даже на платформах семейства Windows.
  </para>
  <para>
   Блокировку также снимает функция <function>fclose</function>
   или сборщик мусора, когда уничтожает поток <parameter>stream</parameter>.
  </para>
  <para>
   PHP поддерживает способ полной переносимой рекомендательной блокировки
   файлов. То есть каждая программа, которая получает доступ к файлу,
   должна использовать один и тот же способ блокировки, иначе блокировка не будет
   работать. По умолчанию функция будет блокироваться до тех пор,
   пока запрошенная блокировка не будет получена; это поведение изменяют
   через описанный ниже флаг <constant>LOCK_NB</constant>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>stream</parameter></term>
     <listitem>
      &fs.file.pointer;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>operation</parameter></term>
     <listitem>
      <para>
       <parameter>operation</parameter> принимает следующие значения:
       <itemizedlist>
        <listitem>
         <simpara>
          <constant>LOCK_SH</constant> для получения разделяемой блокировки (чтение).
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>LOCK_EX</constant> для получения эксклюзивной блокировки (запись).
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>LOCK_UN</constant> для снятия блокировки (разделяемой или эксклюзивной).
         </simpara>
        </listitem>
       </itemizedlist>
      </para>
      <para>
       Флаг <constant>LOCK_NB</constant> добавляют
       как битовую маску к одной операции из списка выше,
       если функция <function>flock</function> не должна
       блокироваться во время попытки блокировки файла.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>would_block</parameter></term>
     <listitem>
      <para>
       Необязательный третий параметр получает значение 1,
       если блокировка будет блокирующей
       (в переменную errno будет записан код ошибки EWOULDBLOCK).
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Пример использования функции <function>flock</function></title>
    <programlisting role="php">
<![CDATA[
<?php

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

if (flock($fp, LOCK_EX)) { // Выполняем эксклюзивную блокировку
    ftruncate($fp, 0); // Очищаем файл
    fwrite($fp, "Пишем что-нибудь сюда\n");
    fflush($fp);        // Очищаем вывод перед отменой блокировки
    flock($fp, LOCK_UN); // Снимаем блокировку
} else {
    echo "Не удалось получить блокировку!";
}

fclose($fp);

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Использование функции <function>flock</function> с параметром <constant>LOCK_NB</constant></title>
    <programlisting role="php">
<![CDATA[
<?php

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

/* Включаем опцию LOCK_NB в операцию LOCK_EX */
if (!flock($fp, LOCK_EX | LOCK_NB)) {
    echo 'Не удалось получить блокировку';
    exit(-1);
}

/* ... */

fclose($fp);
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    В системах Windows функция <function>flock</function> включает обязательную
    блокировку вместо рекомендательной. Обязательная
    блокировка также поддерживается в операционных системах на базе Linux и System V
    через стандартный механизм, который
    поддерживает системный вызов fcntl(): то есть, если для файла
    установлен бит разрешения setgid и сброшен бит группового выполнения.
    Чтобы схема работала корректно в Linux, файловую систему
    также нужно смонтировать с опцией mand.
   </para>
  </note>
  <note>
   <para>
    Поскольку функция <function>flock</function> требует указатель
    на файл, возможно, придётся использовать специальный файл
    блокировки, чтобы защитить доступ к файлу, который вы собираетесь обрезать,
    открыв в режиме записи (в режимах «w» или «w+»
    в качестве аргумента функции <function>fopen</function>).
   </para>
  </note>
  <note>
   <para>
    Функцию разрешено вызывать только на дескрипторах локальных файлов,
    которые возвращает функция <function>fopen</function>, или файловых
    дескрипторах пользовательских потоков, которые реализуют метод
    <function>streamWrapper::stream_lock</function>.
   </para>
  </note>
  <warning>
   <para>
    Присвоение другого значения параметру <parameter>stream</parameter>
    в следующем дальше коде снимет текущую блокировку.
   </para>
  </warning>
  <warning>
   <para>
    В ряде операционных систем функция <function>flock</function> работает
    на уровне процессов. При работе с многопоточными серверными API,
    например, ISAPI, нельзя полагаться на функцию <function>flock</function>,
    чтобы защитить файлы от других PHP-скриптов, которые
    работают в параллельном потоке на том же сервере!
   </para>
   <para>
    Функцию <function>flock</function> не поддерживают старые файловые системы
    наподобие <literal>FAT</literal> и её производные, поэтому функцию будет
    возвращать &false; в этих окружениях.
   </para>
  </warning>
  <note>
   <para>
    Если в Windows процесс блокировки открывает файл во второй раз, он не может
    получить доступ к файлу через второй дескриптор, пока не разблокирует файл.
   </para>
  </note>
 </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
-->