Функция LockFileEx (fileapi.h)

Статья
08/23/2023

Блокирует указанный файл для монопольного доступа вызывающим процессом. Эта функция может работать синхронно или асинхронно и запрашивать монопольную или общую блокировку.

Синтаксис

BOOL LockFileEx(
  [in]      HANDLE       hFile,
  [in]      DWORD        dwFlags,
            DWORD        dwReserved,
  [in]      DWORD        nNumberOfBytesToLockLow,
  [in]      DWORD        nNumberOfBytesToLockHigh,
  [in, out] LPOVERLAPPED lpOverlapped
);

Параметры

[in] hFile

Дескриптор файла. Дескриптор должен быть создан с правом доступа GENERIC_READ или GENERIC_WRITE . Дополнительные сведения см. в разделе Безопасность файлов и права доступа.

[in] dwFlags

Этот параметр может иметь одно или несколько из следующих значений.

Значение	Значение
LOCKFILE_EXCLUSIVE_LOCK 0x00000002	Функция запрашивает монопольную блокировку. В противном случае запрашивается общая блокировка.
LOCKFILE_FAIL_IMMEDIATELY 0x00000001	Функция возвращается немедленно, если ей не удается получить запрошенную блокировку. В противном случае он ожидает.

dwReserved

Зарезервированный параметр; значение должно быть равно нулю.

[in] nNumberOfBytesToLockLow

32 бита нижнего порядка длины байтового диапазона для блокировки.

[in] nNumberOfBytesToLockHigh

Высокий порядок 32 бита длины диапазона байтов для блокировки.

[in, out] lpOverlapped

Указатель на структуру OVERLAPPED , используемую функцией с запросом блокировки. Эта структура, которая является обязательной, содержит смещение файла начала диапазона блокировки. Необходимо инициализировать элемент hEvent допустимым дескриптором или нулевым значением.

Возвращаемое значение

Если функция выполнена успешно, возвращается ненулевое значение (TRUE).

Если функция завершается сбоем, возвращаемое значение равно нулю (FALSE). Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Блокировка области файла используется для получения общего или монопольного доступа к указанному региону с помощью этого дескриптора файла. Если дескриптор файла наследуется процессом, созданным процессом блокировки, дочернему процессу не предоставляется доступ к заблокированной области. Если процесс блокировки открывает файл во второй раз, он не сможет получить доступ к указанному региону через этот второй дескриптор, пока не разблокирует регион.

Блокировка части файла для монопольного доступа запрещает всем остальным процессам доступ к указанной области файла как для чтения, так и для записи. Блокировка области, которая выходит за пределы текущей позиции в конце файла, не является ошибкой.

Блокировка части файла для общего доступа запрещает всем процессам доступ на запись в указанную область файла, включая процесс, который сначала блокирует регион. Все процессы могут считывать заблокированную область.

Блокировка области файла не препятствует чтению или записи из сопоставленного представления файла.

Функция LockFileEx работает асинхронно, если дескриптор файла был открыт для асинхронного ввода-вывода, если не указан флаг LOCKFILE_FAIL_IMMEDIATELY . Если запрашивается монопольная блокировка для диапазона файла, который уже имеет общую или монопольную блокировку, функция возвращает ошибку ERROR_IO_PENDING. Система будет сигнализировать о событии, указанном в структуре OVERLAPPED после предоставления блокировки. Чтобы определить, когда блокировка была предоставлена, используйте функцию GetOverlappedResult или одну из функций ожидания. Дополнительные сведения см. в разделе Синхронный и асинхронный ввод-вывод.

Если дескриптор файла не был открыт для асинхронного ввода-вывода и блокировка недоступна, этот вызов ожидает предоставления блокировки или возникновения ошибки, если не указан флаг LOCKFILE_FAIL_IMMEDIATELY .

Монопольные блокировки не могут перекрывать существующую заблокированную область файла. Общие блокировки могут перекрывать заблокированный регион, если блокировки, удерживаемые в этом регионе, являются общими. Общая блокировка может перекрывать монопольную блокировку, если обе блокировки были созданы с помощью одного дескриптора файла. Когда общая блокировка перекрывает монопольную блокировку, единственным возможным доступом является чтение владельцем блокировок. Если один и тот же диапазон заблокирован монопольной и общей блокировкой, для разблокировки региона необходимы две операции разблокировки; первая операция разблокировки разблокирует монопольную блокировку, вторая — общую блокировку.

Если процесс завершается блокировкой части файла или закрывается файл с незаблокированными блокировками, блокировки разблокируются операционной системой. Однако время, необходимое операционной системе для разблокировки этих блокировок, зависит от доступных системных ресурсов. Поэтому рекомендуется явно разблокировать все файлы, заблокированные при завершении процесса. Если этого не сделать, доступ к этим файлам может быть запрещен, если операционная система еще не разблокировала их.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология	Поддерживается
Протокол SMB 3.0	Да
Прозрачная отработка отказа (TFO) SMB 3.0	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Восстанавливаемая файловая система (ReFS)	Да

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	fileapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll