Edit

Share via

NtLockFile function (ntifs.h)

  • Article

The NtLockFile routine requests a byte-range lock for the specified file.

Syntax

__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
);

Parameters

[in] FileHandle

A handle for the file on which a byte-range lock is requested.

[in, optional] Event

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.

[in, optional] ApcRoutine

A pointer to a caller-supplied APC routine that is executed after the operation completes. Can be NULL.

[in, optional] ApcContext

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.

[out] IoStatusBlock

A pointer to an IO_STATUS_BLOCK structure that contains the final status.

[in] ByteOffset

A pointer to a variable that specifies the starting byte offset of the range to lock.

[in] Length

A pointer to a variable that specifies the length in bytes of the range to lock.

[in] Key

A caller-assigned value used to describe groups of related locks. This value should be set to zero.

[in] FailImmediately

If TRUE, immediately return if the file cannot be locked. If FALSE, wait for the lock request to be granted.

[in] ExclusiveLock

If TRUE, byte-range lock is exclusive; otherwise, shared lock.

Return value

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.

Remarks

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**.

Requirements

Requirement Value
Minimum supported client Windows 7
Target Platform Universal
Header ntifs.h (include Ntifs.h, FltKernel.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL (see Remarks section)
DDI compliance rules HwStorPortProhibitedDDIs, PowerIrpDDis

See also

ZwUnlockFile