MSDN Documentation

File Locking in Windows

File locking is a crucial mechanism for controlling access to files, especially in multi-user or multi-threaded environments. It prevents data corruption and ensures data integrity by allowing only one process to modify a file or a portion of it at any given time.

Why File Locking?

In a concurrent system, multiple applications or threads might attempt to read or write to the same file simultaneously. Without proper synchronization, this can lead to:

• Race Conditions: The outcome of operations depends on the unpredictable timing of multiple threads.
• Data Corruption: Partial writes from one process might be overwritten or interleaved with writes from another, resulting in an invalid file state.
• Inconsistent Reads: A process might read data while another process is in the middle of updating it, leading to incomplete or incorrect information.

Types of File Locks

Windows supports several types of file locks, primarily managed through the CreateFile function and its parameters, along with specific file control codes (IOCTLs).

Share Modes

When opening a file with CreateFile, you specify share modes that indicate how other processes can access the file while it's open:

• FILE_SHARE_READ: Other processes can read the file.
• FILE_SHARE_WRITE: Other processes can write to the file.
• FILE_SHARE_DELETE: Other processes can delete the file.

If a process tries to open a file with incompatible share modes, the open operation will fail.

Locking Mechanisms

Beyond share modes, Windows provides more granular control over file access:

Byte Range Locking

This is the most common and flexible method. It allows a process to lock specific regions (byte ranges) within a file, while other parts of the file might remain accessible for reading or writing by other processes. This is achieved using the LockFile and UnlockFile functions.

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

This function attempts to acquire an exclusive lock on a specified byte range of an open file.

• hFile: A handle to the file.
• dwFileOffsetLow, dwFileOffsetHigh: The starting offset of the byte range to lock.
• nNumberOfBytesToLockLow, nNumberOfBytesToLockHigh: The number of bytes to lock. A value of 0 means locking from the offset to the end of the file.

UnlockFile(HANDLE hFile, DWORD dwFileOffsetLow, DWORD dwFileOffsetHigh, DWORD nNumberOfBytesToUnlockLow, DWORD nNumberOfBytesToUnlockHigh)

This function releases a previously acquired byte range lock.

Advisory vs. Mandatory Locking

Windows primarily implements advisory locking. This means that locks are cooperative. Processes must explicitly check for and respect locks set by other processes. If a process does not check for locks, it can still access the locked region, potentially causing corruption. Some other operating systems support mandatory locking, where the system automatically enforces locks.

File Locking APIs

Here's a summary of key Win32 API functions related to file locking:

Using LockFileEx

LockFileEx provides greater flexibility:

LockFileEx(HANDLE hFile, DWORD dwFlags, DWORD dwReserved, DWORD nNumberOfBytesToLockLow, DWORD nNumberOfBytesToLockHigh, LPOVERLAPPED lpOverlapped)

Key flags include:

• LOCKFILE_EXCLUSIVE_LOCK: Acquires an exclusive lock.
• LOCKFILE_FAIL_IMMEDIATELY: Returns immediately if the lock cannot be acquired.
• LOCKFILE_SHARED_LOCK: Acquires a shared lock (allows other shared locks, but prevents exclusive locks).

Example: Locking a File Region

Consider a scenario where multiple processes update different sections of a configuration file. Each process could:

1. Open the file with appropriate share modes (e.g., FILE_SHARE_READ | FILE_SHARE_WRITE).
2. Determine the specific byte range it needs to lock.
3. Call LockFileEx to acquire an exclusive lock on that range.
4. Perform its read/write operations within the locked region.
5. Call UnlockFileEx (or UnlockFile) to release the lock.
6. Close the file handle.

Here's a conceptual C++ snippet:

#include <windows.h>
#include <iostream>

// ... inside a function ...

HANDLE hFile = CreateFile(
    L"config.dat",
    GENERIC_READ | GENERIC_WRITE,
    FILE_SHARE_READ | FILE_SHARE_WRITE,
    NULL,
    OPEN_ALWAYS,
    FILE_ATTRIBUTE_NORMAL,
    NULL
);

if (hFile == INVALID_HANDLE_VALUE) {
    std::cerr << "Failed to open file. Error: " << GetLastError() << std::endl;
    return;
}

// Example: Lock bytes 100 to 199 (100 bytes)
DWORD offset = 100;
DWORD numBytes = 100;
OVERLAPPED ol = {0}; // For LockFileEx

// Try to acquire an exclusive lock, wait if necessary
BOOL locked = LockFileEx(hFile, LOCKFILE_EXCLUSIVE_LOCK, 0, numBytes, 0, &ol);

if (!locked) {
    std::cerr << "Failed to lock file region. Error: " << GetLastError() << std::endl;
    CloseHandle(hFile);
    return;
}

std::cout << "File region locked successfully." << std::endl;

// --- Perform read/write operations on the locked region ---
// Example: write some data
DWORD bytesWritten;
const char* data = "UPDATED DATA";
if (!WriteFile(hFile, data, strlen(data), &bytesWritten, NULL)) {
    std::cerr << "Error writing to file." << std::endl;
} else {
    std::cout << "Successfully wrote " << bytesWritten << " bytes." << std::endl;
}
// --- End of operations ---


// Release the lock
BOOL unlocked = UnlockFileEx(hFile, 0, numBytes, 0, &ol);
if (!unlocked) {
    std::cerr << "Failed to unlock file region. Error: " << GetLastError() << std::endl;
} else {
    std::cout << "File region unlocked." << std::endl;
}

CloseHandle(hFile);
                

Considerations and Best Practices

• Granularity: Lock only the necessary portions of the file to minimize contention.
• Error Handling: Always check the return values of locking functions and handle errors gracefully.
• Deadlocks: Be aware of the potential for deadlocks if multiple processes try to acquire locks in different orders. Implement timeouts or careful locking strategies.
• Cleanup: Ensure locks are released properly, even if errors occur, by using RAII or `finally` blocks in your code.
• Performance: Frequent locking and unlocking can impact performance. Consider alternative synchronization primitives or file access strategies if performance is critical.
• Network Shares: File locking behavior can be more complex and less reliable over network shares due to varying implementations and network latency.

Proper file locking is essential for building robust and reliable Windows applications that interact with the file system.