FsRtlFastLock function

The FsRtlFastLock macro is used by file systems and filter drivers to request a byte-range lock for a file stream.

Syntax


BOOLEAN FsRtlFastLock(
  _In_  PFILE_LOCK       FileLock,
  _In_  PFILE_OBJECT     FileObject,
  _In_  PLARGE_INTEGER   FileOffset,
  _In_  PLARGE_INTEGER   Length,
  _In_  PEPROCESS        ProcessId,
  _In_  ULONG            Key,
  _In_  BOOLEAN          FailImmediately,
  _In_  BOOLEAN          ExclusiveLock,
  _Out_ PIO_STATUS_BLOCK Iosb,
  _In_  PVOID            Context,
  _In_  BOOLEAN          AlreadySynchronized
);

Parameters

FileLock [in]

Pointer to the FILE_LOCK structure for the file. This structure must have been initialized by a previous call to FsRtlAllocateFileLock or FsRtlInitializeFileLock.

FileObject [in]

Pointer to the file object for the open file. The file object must have been created with GENERIC_READ or GENERIC_WRITE access to the file (or both).

FileOffset [in]

Pointer to a variable that specifies the starting byte offset within the file of the range to be locked.

Length [in]

Pointer to a variable that specifies the length in bytes of the range to be locked.

ProcessId [in]

Pointer to the process ID for the process requesting the byte-range lock.

Key [in]

The key to be assigned to the byte-range lock.

FailImmediately [in]

Boolean value specifying whether the lock request should fail if the lock cannot be granted immediately. If the caller can be put into a wait state until the request is granted, set FailImmediately to FALSE. If it cannot, set FailImmediately to TRUE.

ExclusiveLock [in]

Set to TRUE if an exclusive lock is requested, FALSE if a shared lock is requested.

Iosb [out]

Pointer to a caller-allocated IO_STATUS_BLOCK structure that receives status information about the lock request.

Context [in]

Optional pointer to a context to use when releasing the byte-range lock.

AlreadySynchronized [in]

This parameter is obsolete, but is retained for compatibility with legacy drivers.

Return value

If FailImmediately is FALSE, FsRtlFastLock returns TRUE if the lock operation succeeds, FALSE otherwise.

If FailImmediately is TRUE, FsRtlFastLock always returns TRUE.

Remarks

The FsRtlFastLock macro causes the caller to acquire a byte-range lock on a region of the specified file.

A return value of TRUE indicates that the IO_STATUS_BLOCK structure pointed to by Iosb received status information about the lock operation. To examine the contents of this structure, use the NT_STATUS macro.

Requirements

Target platform

Desktop

Header

Ntifs.h (include Ntifs.h)

IRQL

<= APC_LEVEL

See also

FsRtlAllocateFileLock
FsRtlInitializeFileLock

 

 

Send comments about this topic to Microsoft

Show: