Skip to content
152 changes: 89 additions & 63 deletions reference/filesystem/functions/flock.xml
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 75a76afb61d91f04feebc83931c5412b13682d2b Maintainer: shein Status: ready -->
<!-- EN-Revision: 0baba6599fa96a354d01ce3592bee5d2d355e1ba Maintainer: shein Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.flock" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>flock</refname>
<refpurpose>Блокирует файл методом переносимой рекомендательной блокировки</refpurpose>
<refpurpose>Устанавливает переносимую рекомендательную блокировку файла</refpurpose>
</refnamediv>

<refsect1 role="description">
Expand All @@ -16,21 +16,23 @@
<methodparam choice="opt"><type>int</type><parameter role="reference">would_block</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<para>
Функция <function>flock</function> разрешает выполнять простую модель
чтения-записи, которая будет работать на большей части Unix-платформ
и даже на платформах семейства Windows.
Функция <function>flock</function> устанавливает блокировку файла на чтение или запись.
Функция помогает организовать модель «читатель-писатель»,
которая поддерживается на большей части платформ на основе Unix и даже в Windows.
</para>
<para>
Блокировку также снимает функция <function>fclose</function>
или сборщик мусора, когда уничтожает поток <parameter>stream</parameter>.
Вызов функции с флагом <constant>LOCK_UN</constant> снимает блокировку.
Блокировка также снимается при вызове функции <function>fclose</function>
или когда сборщик мусора уничтожает поток <parameter>stream</parameter>.
</para>
<para>
PHP поддерживает способ полной переносимой рекомендательной блокировки
файлов. То есть каждая программа, которая получает доступ к файлу,
должна использовать один и тот же способ блокировки, иначе блокировка не будет
работать. По умолчанию функция будет блокироваться до тех пор,
пока запрошенная блокировка не будет получена; это поведение изменяют
через описанный ниже флаг <constant>LOCK_NB</constant>.
PHP поддерживает переносимый способ блокировки файлов целиком,
который держится на «джентльменском соглашении» и работает,
только если при доступе к файлу каждая программа действует в рамках единой согласованной модели блокировок —
вызывает функцию <function>flock</function> и учитывает чужие блокировки.
По умолчанию функция приостанавливает выполнение скрипта и ждёт,
пока не получит запрошенную блокировку файла,
если только поведение блокировки не изменили флагом <constant>LOCK_NB</constant>.
</para>
</refsect1>

Expand All @@ -48,40 +50,40 @@
<term><parameter>operation</parameter></term>
<listitem>
<para>
<parameter>operation</parameter> принимает следующие значения:
Параметр <parameter>operation</parameter> принимает следующие значения:
<itemizedlist>
<listitem>
<simpara>
<constant>LOCK_SH</constant> для получения разделяемой блокировки (чтение).
<constant>LOCK_SH</constant> — разделяемая блокировка при чтении.
</simpara>
</listitem>
<listitem>
<simpara>
<constant>LOCK_EX</constant> для получения эксклюзивной блокировки (запись).
<constant>LOCK_EX</constant> — эксклюзивная блокировка при записи.
</simpara>
</listitem>
<listitem>
<simpara>
<constant>LOCK_UN</constant> для снятия блокировки (разделяемой или эксклюзивной).
<constant>LOCK_UN</constant> — снятие блокировки, разделяемой или эксклюзивной.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
Флаг <constant>LOCK_NB</constant> добавляют
как битовую маску к одной операции из списка выше,
если функция <function>flock</function> не должна
блокироваться во время попытки блокировки файла.
Флаг <constant>LOCK_NB</constant> добавляют к приведённым операциям
как битовую маску, чтобы при попытке заблокировать файл
функция <function>flock</function> не приостанавливала выполнение скрипта.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>would_block</parameter></term>
<listitem>
<para>
Необязательный третий параметр получает значение 1,
если блокировка будет блокирующей
(в переменную errno будет записан код ошибки EWOULDBLOCK).
При вызове с флагом <constant>LOCK_NB</constant> на занятом файле
выполняется условие, при котором системная переменная errno заполняется значением EWOULDBLOCK,
и третий необязательный параметр заполняется значением 1. Единица указывает,
что при блокирующем вызове потребовалось бы приостановить выполнение скрипта и ждать, пока файл не освободится.
</para>
</listitem>
</varlistentry>
Expand All @@ -100,33 +102,31 @@
&reftitle.examples;
<para>
<example>
<title>Пример использования функции <function>flock</function></title>
<title>Пример блокировки файла функцией <function>flock</function></title>
<programlisting role="php">
<![CDATA[
<?php

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

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

fclose($fp);

?>
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Использование функции <function>flock</function> с параметром <constant>LOCK_NB</constant></title>
<title>Пример вызова функции <function>flock</function> с флагом <constant>LOCK_NB</constant></title>
<programlisting role="php">
<![CDATA[
<?php
Expand All @@ -135,14 +135,13 @@ $fp = fopen('/tmp/lock.txt', 'r+');

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

/* ... */

fclose($fp);
?>
]]>
</programlisting>
</example>
Expand All @@ -153,58 +152,85 @@ fclose($fp);
&reftitle.notes;
<note>
<para>
В системах Windows функция <function>flock</function> включает обязательную
блокировку вместо рекомендательной. Обязательная
блокировка также поддерживается в операционных системах на базе Linux и System V
через стандартный механизм, который
поддерживает системный вызов fcntl(): то есть, если для файла
В системах Windows функция <function>flock</function> устанавливает обязательную,
а не рекомендательную блокировку. Обязательная блокировка
также поддерживается в операционных системах на базе Linux и System V
через стандартный механизм,
который поддерживается системным вызовом fcntl(): если для файла
установлен бит разрешения setgid и сброшен бит группового выполнения.
Чтобы схема работала корректно в Linux, файловую систему
также нужно смонтировать с опцией mand.
Для корректной работы схемы в Linux файловую систему
монтируют с опцией mand.
</para>
</note>
<note>
<para>
Поскольку функция <function>flock</function> требует указатель
на файл, возможно, придётся использовать специальный файл
блокировки, чтобы защитить доступ к файлу, который вы собираетесь обрезать,
открыв в режиме записи (в режимах «w» или «w+»
в качестве аргумента функции <function>fopen</function>).
Для блокировки файла функции <function>flock</function> требуется файловый указатель,
а функция <function>fopen</function> при вызове с аргументами "w" или "w+"
сначала усекает файл, а только потом возвращает указатель на файл.
Поэтому защита файла строится на дополнительном lock-файле: вначале получают блокировку дополнительного файла,
а только потом усекают целевой файл.
</para>
</note>
<note>
<para>
Функцию разрешено вызывать только на дескрипторах локальных файлов,
которые возвращает функция <function>fopen</function>, или файловых
дескрипторах пользовательских потоков, которые реализуют метод
<function>streamWrapper::stream_lock</function>.
</para>
<simpara>
Функция работает только при вызове на файловых указателях,
которые функция <function>fopen</function> возвращает для локальных файлов,
или указателях пользовательских потоков,
которые реализуют метод <function>streamWrapper::stream_lock</function>.
Начиная с PHP 8.5.0 появилась поддержка файловых указателей,
которые возвращает функция <function>gzopen</function>.
</simpara>
</note>
<warning>
<para>
Присвоение другого значения параметру <parameter>stream</parameter>
в следующем дальше коде снимет текущую блокировку.
Текущая блокировка снимется, если после вызова функции переменной,
которую передали в параметр <parameter>stream</parameter>, присвоить другое значение.
</para>
</warning>
<warning>
<para>
В ряде операционных систем функция <function>flock</function> работает
на уровне процессов. При работе с многопоточными серверными API,
например, ISAPI, нельзя полагаться на функцию <function>flock</function>,
чтобы защитить файлы от других PHP-скриптов, которые
работают в параллельном потоке на том же сервере!
на уровне процессов. При работе с многопоточными серверными API
наподобие ISAPI нельзя полагаться на функцию <function>flock</function>,
чтобы защитить файлы от других PHP-скриптов,
которые работают в параллельном потоке на том же сервере!
</para>
<para>
Функцию <function>flock</function> не поддерживают старые файловые системы
наподобие <literal>FAT</literal> и её производные, поэтому функцию будет
возвращать &false; в этих окружениях.
Старые файловые системы наподобие <literal>FAT</literal> и производные файловые системы
не поддерживают функцию <function>flock</function>,
поэтому в таких окружения функция возвращает &false;.
</para>
<para>
В Windows попытка выполнить из PHP файл с исходным PHP-кодом,
на который через флаг <constant>LOCK_EX</constant> поставили эксклюзивную блокировку,
зависнет, пока файл не освободится. Следующий пример вызовет взаимную блокировку:
<informalexample>
<programlisting role="php">
<![CDATA[
<?php

if ($argv[1] ?? null === 'child') {
die();
}

$fp = fopen(__FILE__, "rb");
flock($fp, LOCK_EX);

shell_exec("php " . escapeshellarg(__FILE__) . " child");
]]>
</programlisting>
</informalexample>
</para>
</warning>
<note>
<para>
Если в Windows процесс блокировки открывает файл во второй раз, он не может
получить доступ к файлу через второй дескриптор, пока не разблокирует файл.
В Windows процесс, который уже держит блокировку файла, не получит доступ к файлу через второй дескриптор,
пока не освободится блокировка первого дескриптора.
</para>
<simpara>
В Windows попытка подключить файл, который заблокировали флагом LOCK_EX,
выбросит исключение ErrorException: require(): Read of X bytes failed with errno=13 Permission denied
</simpara>
</note>
</refsect1>

Expand Down
Loading
Loading