Export (0) Print
Expand All
Expand Minimize

FsRtlMdlReadEx routine

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

FileObject [in]

A pointer to the file object.

FileOffset [in]

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

Length [in]

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

LockKey [in]

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.

MdlChain [out]

On output, a pointer to a linked list of memory descriptor lists (MDLs).

IoStatus [out]

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 codeDescription
STATUS_INSUFFICIENT_RESOURCES

The IRP for an the 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

Target platform

Universal

Version

Available starting with Windows 8.

Header

Ntifs.h (include Ntifs.h)

Library

Ntoskrnl.lib

IRQL

PASSIVE_LEVEL

See also

CcMdlRead
CcMdlReadComplete
MmGetSystemAddressForMdlSafe

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft