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。

注解

锁定文件的区域用于使用此文件句柄获取对指定区域的共享或独占访问权限。如果文件句柄由锁定进程创建的进程继承，则不会向子进程授予对锁定区域的访问权限。如果锁定进程第二次打开文件，则在解锁该区域之前，它无法通过第二个句柄访问指定区域。

锁定文件的一部分以便进行独占访问会拒绝所有其他进程对文件的指定区域进行读取和写入访问。锁定超出当前文件结束位置的区域不是错误。

锁定文件的一部分进行共享访问会拒绝所有进程对文件的指定区域（包括首先锁定该区域的进程）的写入访问权限。所有进程都可以读取锁定的区域。

锁定文件的区域不会阻止从映射的文件视图读取或写入。

如果为异步 I/O 打开了文件句柄，则 LockFileEx 函数将异步运行，除非指定 了 LOCKFILE_FAIL_IMMEDIATELY 标志。如果为已具有共享或独占锁的文件范围请求独占锁，则函数 ERROR_IO_PENDING返回错误。授予锁后，系统会向 OVERLAPPED 结构中指定的事件发出信号。若要确定何时授予锁，请使用 GetOverlappedResult 函数或等待函数之一。有关详细信息，请参阅同步和异步 I/O。

如果未为异步 I/O 打开文件句柄，并且锁不可用，则此调用将等到授予锁或发生错误，除非指定 了LOCKFILE_FAIL_IMMEDIATELY 标志。

独占锁不能与文件的现有锁定区域重叠。共享锁可以与锁定区域重叠，前提是该区域上保留的锁是共享锁。如果两个锁是使用相同的文件句柄创建的，则共享锁可以与独占锁重叠。当共享锁与独占锁重叠时，唯一可能的访问是由锁的所有者读取。如果使用独占锁和共享锁锁定相同的范围，则需要执行两个解锁操作来解锁区域：第一个解锁操作解锁独占锁，第二个解锁操作解锁共享锁。

如果进程终止并锁定了文件的一部分，或者关闭了具有未完成锁的文件，则操作系统会解锁锁。但是，操作系统解锁这些锁所需的时间取决于可用的系统资源。因此，建议进程在终止时显式解锁已锁定的所有文件。如果未执行此操作，则如果操作系统尚未解锁这些文件，可能会拒绝访问这些文件。

在 Windows 8 和 Windows Server 2012 中，此函数由以下技术支持。

技术	支持
服务器消息块 (SMB) 3.0 协议	是
SMB 3.0 透明故障转移 (TFO)	是
具有横向扩展文件共享的 SMB 3.0 (SO)	是
群集共享卷文件系统 (CSV)	是
弹性文件系统 (ReFS)	是

要求

要求	值
最低受支持的客户端	Windows XP [桌面应用 \| UWP 应用]
最低受支持的服务器	Windows Server 2003 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	fileapi.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll