#ifndef _NTIOAPI_H
NTSYSCALLAPI
NTSTATUS
NTAPI
NtLockFile(
_In_ HANDLE FileHandle,
_In_opt_ HANDLE Event,
_In_opt_ PIO_APC_ROUTINE ApcRoutine,
_In_opt_ PVOID ApcContext,
_Out_ PIO_STATUS_BLOCK IoStatusBlock,
_In_ PLARGE_INTEGER ByteOffset,
_In_ PLARGE_INTEGER Length,
_In_ ULONG Key,
_In_ BOOLEAN FailImmediately,
_In_ BOOLEAN ExclusiveLock
);
View code on GitHub
#ifndef _NTZWAPI_H
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwLockFile(
_In_ HANDLE FileHandle,
_In_opt_ HANDLE Event,
_In_opt_ PIO_APC_ROUTINE ApcRoutine,
_In_opt_ PVOID ApcContext,
_Out_ PIO_STATUS_BLOCK IoStatusBlock,
_In_ PLARGE_INTEGER ByteOffset,
_In_ PLARGE_INTEGER Length,
_In_ ULONG Key,
_In_ BOOLEAN FailImmediately,
_In_ BOOLEAN ExclusiveLock
);
View code on GitHub
// ntifs.h
__kernel_entry NTSYSCALLAPI NTSTATUS NtLockFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] PLARGE_INTEGER ByteOffset,
[in] PLARGE_INTEGER Length,
[in] ULONG Key,
[in] BOOLEAN FailImmediately,
[in] BOOLEAN ExclusiveLock
);
View the official Windows Driver Kit DDI reference
// ntifs.h
NTSYSAPI NTSTATUS ZwLockFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] PLARGE_INTEGER ByteOffset,
[in] PLARGE_INTEGER Length,
[in] ULONG Key,
[in] BOOLEAN FailImmediately,
[in] BOOLEAN ExclusiveLock
);
View the official Windows Driver Kit DDI reference
No description available.
The NtLockFile routine requests a byte-range lock for the specified file.
FileHandle
[in]A handle for the file on which a byte-range lock is requested.
Event
[in, optional]A handle to a caller-created event. If not NULL, the caller is placed into a wait state until the operation succeeds, at which time the event is set into the Signaled state.
ApcRoutine
[in, optional]A pointer to a caller-supplied APC routine that is executed after the operation completes. Can be NULL.
ApcContext
[in, optional]A pointer to a caller-specified context for the APC routine. This value is passed to the APC routine when it is executed. Can be NULL.
IoStatusBlock
[out]A pointer to an IO_STATUS_BLOCK structure that contains the final status.
ByteOffset
[in]A pointer to a variable that specifies the starting byte offset of the range to lock.
Length
[in]A pointer to a variable that specifies the length in bytes of the range to lock.
Key
[in]A caller-assigned value used to describe groups of related locks. This value should be set to zero.
FailImmediately
[in]If TRUE, immediately return if the file cannot be locked. If FALSE, wait for the lock request to be granted.
ExclusiveLock
[in]If TRUE, byte-range lock is exclusive; otherwise, shared lock.
The NtLockFile routine returns STATUS_SUCCESS or an appropriate error NTSTATUS value. Possible NTSTATUS values include the following:
Return code | Description |
---|---|
STATUS_INSUFFICIENT_RESOURCES | Insufficient resources exist to grant the byte-range lock for the specified file. |
STATUS_LOCK_NOT_GRANTED | The byte-range lock was not granted for the specified file. |
Callers of NtLockFile must be running at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled**.
[!NOTE] If the call to the NtLockFile function occurs in user mode, you should use the name "NtLockFile" instead of "ZwLockFile".
For calls from kernel-mode drivers, the NtXxx and ZwXxx versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines**.
Using Nt and Zw Versions of the Native System Services Routines
The ZwLockFile routine requests a byte-range lock for the specified file.
FileHandle
[in]A handle for the file on which a byte-range lock is requested.
Event
[in, optional]A handle to a caller-created event. If not NULL, the caller is placed into a wait state until the operation succeeds, at which time the event is set into the Signaled state.
ApcRoutine
[in, optional]A pointer to a caller-supplied APC routine that is executed after the operation completes. Can be NULL.
ApcContext
[in, optional]A pointer to a caller-specified context for the APC routine. This value is passed to the APC routine when it is executed. Can be NULL.
IoStatusBlock
[out]A pointer to an IO_STATUS_BLOCK structure that contains the final status.
ByteOffset
[in]A pointer to a variable that specifies the starting byte offset of the range to lock.
Length
[in]A pointer to a variable that specifies the length in bytes of the range to lock.
Key
[in]A caller-assigned value used to describe groups of related locks. This value should be set to zero.
FailImmediately
[in]If TRUE, immediately return if the file cannot be locked. If FALSE, wait for the lock request to be granted.
ExclusiveLock
[in]If TRUE, byte-range lock is exclusive; otherwise, shared lock.
The ZwLockFile routine returns STATUS_SUCCESS or an appropriate error NTSTATUS value such as one of the following.
Error code | Description |
---|---|
STATUS_INSUFFICIENT_RESOURCES | Insufficient resources exist to grant the byte-range lock for the specified file. |
STATUS_LOCK_NOT_GRANTED | The byte-range lock was not granted for the specified file. |
Callers of ZwLockFile must be running at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled.
[!NOTE]
If the call to the ZwLockFile function occurs in user mode, you should use the name "NtLockFile" instead of "ZwLockFile".
For calls from kernel-mode drivers, the NtXxx and ZwXxx versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.
Using Nt and Zw Versions of the Native System Services Routines
This function is documented in Windows Driver Kit here and here.
HANDLE
to File Object opened with FILE_READ_DATA
access.
Optional HANDLE
to Event Object, which is signaled when lock is created (typically used with ReturnImmediately
parameter set to TRUE
).
APC routine executed when lock is granted.
Optional parameter for ApcRoutine
.
IO result of call.
Offset (in bytes) to begin of file region to lock.
Length of region to lock, in bytes.
Pointer to user's defined 4-bytes key associated with this lock. It can be used in multi-thread process to allow reading or writing data only for one specified thread, with known Key
value.
If TRUE
, function returns immediately. Caller is informed about lock creation by LockGrantedEvent
or by executing ApcRoutine
.
If set, all read and write operation are denied for other processes. If not, only write operation is denied.