Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
ZwLockFile

ZwLockFile routine

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

Syntax


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

Parameters

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.

Return value

The ZwLockFile routine returns STATUS_SUCCESS or an appropriate error NTSTATUS value. Possible NTSTATUS values include the following:

Return codeDescription
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 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".

Requirements

Target platform

Universal

Version

Available starting with Windows 7.

Header

Ntifs.h (include Ntifs.h or FltKernel.h)

Library

NtosKrnl.lib

DLL

NtosKrnl.exe

IRQL

PASSIVE_LEVEL (see Remarks section)

DDI compliance rules

PowerIrpDDis, HwStorPortProhibitedDDIs

See also

ZwUnlockFile

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft