LockFile function

The LockFile function acquires an exclusive or shared lock on a specified range of bytes in a file. This function is part of the Windows API, primarily used for inter-process communication and resource synchronization.

Syntax

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

This function is declared in windows.h.

Parameters

Parameter	Type	Description
`hFile`	`HANDLE`	A handle to the file to be locked. The handle must have been created with the `GENERIC_READ` and `GENERIC_WRITE` access rights.
`dwFileOffsetLow`	`DWORD`	The low-order bits of the byte offset from the beginning of the file where the lock begins.
`dwFileOffsetHigh`	`DWORD`	The high-order bits of the byte offset from the beginning of the file where the lock begins.
`nNumberOfBytesToLockLow`	`DWORD`	The low-order bits of the number of bytes to lock. If this is 0 and `nNumberOfBytesToLockHigh` is 0, the function locks from the specified offset to the end of the file.
`nNumberOfBytesToLockHigh`	`DWORD`	The high-order bits of the number of bytes to lock. If this is 0 and `nNumberOfBytesToLockLow` is 0, the function locks from the specified offset to the end of the file.

Return value

`BOOL`

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The LockFile function attempts to acquire an exclusive lock on a specified byte range within an open file. If the lock is successfully acquired, other processes attempting to lock or access the same byte range will fail until the lock is released.

A lock acquired by LockFile is an exclusive lock. This means that no other process can acquire a lock (either shared or exclusive) on any part of the locked region. However, the process that holds the lock can still read from or write to the locked region.

If a process calls LockFile and the desired region is already locked by another process, LockFile returns zero and GetLastError returns ERROR_LOCK_VIOLATION.

To release a lock, use the UnlockFile function. Locks are automatically released when the file handle is closed or when the process terminates.

The lock range is specified by nNumberOfBytesToLockLow and nNumberOfBytesToLockHigh. If both are zero, the lock extends from the specified offset to the end of the file. If the file grows while it is locked, the lock is extended to cover the new bytes.

Note: Byte-range locking is advisory. It is the responsibility of all processes that access the file to use locking to coordinate their access. If a process does not use locking, it may bypass the locks set by other processes.

The following table lists common error codes returned by GetLastError for this function:

ERROR_LOCK_VIOLATION: The requested lock violates an existing lock.
ERROR_INVALID_HANDLE: The specified file handle is invalid.
ERROR_NEGATIVE_SEEK: The file offset is invalid.
ERROR_SEEK: The file offset is invalid.

Requirements

Attribute	Value
`Minimum supported client`	Windows 2000 Professional [desktop apps only]
`Minimum supported server`	Windows 2000 Server [desktop apps only]
`Header`	`windows.h`
`Library`	`Kernel32.lib`
`DLL`	`Kernel32.dll`