FsRtlMdlReadEx function (ntifs.h)

Article
02/22/2024

The FsRtlMdlReadEx routine performs a fast cached MDL read. If the requested data is not cached, the routine reverts to an IRP based MDL read operation.

Syntax

NTSTATUS FsRtlMdlReadEx(
  [in]  PFILE_OBJECT     FileObject,
  [in]  PLARGE_INTEGER   FileOffset,
  [in]  ULONG            Length,
  [in]  ULONG            LockKey,
  [out] PMDL             *MdlChain,
  [out] PIO_STATUS_BLOCK IoStatus
);

Parameters

[in] FileObject

A pointer to the file object.

[in] FileOffset

A pointer to a variable that specifies the starting byte offset within the cached file that holds the data.

[in] Length

The length in bytes of the data to read from the cache.

[in] LockKey

A value that is associated with the byte range to lock. If the range to lock overlaps another range that is already locked with a nonexclusive lock, or if the range to read is a subrange of another range that is already locked nonexclusively, the value in this parameter must be the key for that nonexclusive lock The lock must be held by the parent process of the calling thread. Otherwise, this parameter has no effect.

[out] MdlChain

An address of a variable that receives a pointer to a linked list of memory descriptor lists (MDLs). MdlChain must be initialized to NULL before the call to FsRtlMdlReadEx.

[out] IoStatus

A pointer to an IO_STATUS_BLOCK structure that, on output, contains the status of the transfer. If the operation succeeds, IoStatus.Status is set to STATUS_SUCCESS. Otherwise, it is set to an appropriate NTSTATUS error code. IoStatus.Information is set to the actual number of bytes that the routine successfully locked.

Return value

FsRtlMdlReadEx returns STATUS_SUCCESS or an appropriate NTSTATUS value, such as one of the following:

Return code	Description
STATUS_INSUFFICIENT_RESOURCES	The IRP for an IRP based read could not be allocated.

Remarks

If fast I/O is available from the file system, the FsRtlMdlReadEx routine will bypass the usual IRP read mechanism and return a linked list of memory descriptor lists (MDL) that the caller can use to directly access the cached file data. This operation does not copy or buffer data and therefore is much faster than a normal read. If fast I/O is not enabled, FsRtlMdlReadEx will generate a synchronous IRP based MDL read and return the MDLs from the request.

The pages described by the MDLs are locked in memory, but not mapped in system space. The caller can perform this mapping by calling MmGetSystemAddressForMdlSafe.

Similar to CcMdlRead, the FsRtlMdlReadEx routine locks the pages that contain the cached file data to prevent the system from swapping these pages to the page file. The pages remain locked in memory until the caller invokes the CcMdlReadComplete routine.

Requirements

Requirement	Value
Minimum supported client	Windows 8
Target Platform	Universal
Header	ntifs.h (include Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL