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

Статья
08/23/2023

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

Чтобы указать дополнительные параметры, например создание общей блокировки или операцию блокировки при сбое, используйте функцию LockFileEx .

Синтаксис

BOOL LockFile(
  [in] HANDLE hFile,
  [in] DWORD  dwFileOffsetLow,
  [in] DWORD  dwFileOffsetHigh,
  [in] DWORD  nNumberOfBytesToLockLow,
  [in] DWORD  nNumberOfBytesToLockHigh
);

Параметры

[in] hFile

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

[in] dwFileOffsetLow

32 бита начального смещения байтов в файле, где должна начинаться блокировка.

[in] dwFileOffsetHigh

32 бита начального смещения байтов в файле, где должна начинаться блокировка.

[in] nNumberOfBytesToLockLow

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

[in] nNumberOfBytesToLockHigh

32 бита длины байтового диапазона, который необходимо заблокировать.

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

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

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

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

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

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

Монопольные блокировки не могут перекрывать существующую заблокированную область файла. Дополнительные сведения см. в разделе LockFileEx.

Если LockFile не может заблокировать область файла, он немедленно возвращает ноль. Он не блокируется. Чтобы выполнить запрос на блокировку файла, который будет блокироваться до получения блокировки, используйте LockFileEx без флага 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