Share via


CcMdlRead routine

The CcMdlRead routine provides direct access to cached file memory so that the caller can read data from the file.

Syntax

VOID CcMdlRead(
  _In_  PFILE_OBJECT     FileObject,
  _In_  PLARGE_INTEGER   FileOffset,
  _In_  ULONG            Length,
  _Out_ PMDL             *MdlChain,
  _Out_ PIO_STATUS_BLOCK IoStatus
);

Parameters

  • FileObject [in]
    Pointer to a file object for the cached file.

  • FileOffset [in]
    Pointer to a variable that specifies the starting byte offset within the cached file where the desired data resides.

  • Length [in]
    Length in bytes of the data to be read from the system cache.

  • MdlChain [out]
    A chain of one or more memory descriptor lists (MDL) describing the pages containing the data.

  • IoStatus [out]
    Pointer to an IO_STATUS_BLOCK structure. If the call to CcMdlRead 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 were successfully locked down in the MDL chain.

Return value

None

Remarks

CcMdlRead is similar to CcCopyRead, except that the cached file data is not copied. Instead, the physical pages containing the data are locked in memory, and CcMdlRead returns one or more memory descriptor lists (MDL) describing the specified byte range. The pages containing the data remain locked in memory until CcMdlReadComplete is called. Thus each call to CcMdlRead must be followed by a call to CcMdlReadComplete.

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

If any failure occurs, CcMdlRead raises a status exception for that particular failure. For example, if a pool allocation failure occurs, CcMdlRead raises a STATUS_INSUFFICIENT_RESOURCES exception; if an I/O error occurs, CcMdlRead raises the status exception of the I/O error. Therefore, to gain control if a failure occurs, the driver should wrap the call to CcMdlRead in a try-except or try-finally statement.

Note that even if the call to CcMdlRead fails, one or more MDLs may have been allocated. The caller can examine the value of IoStatus.Information to determine whether this has occurred. If it has, the caller must call CcMdlReadComplete to free the allocated MDLs.

To cache a file, use CcInitializeCacheMap.

Requirements

Target platform

Universal

Header

Ntifs.h (include Ntifs.h)

Library

NtosKrnl.lib

DLL

NtosKrnl.exe

IRQL

< DISPATCH_LEVEL

See also

CcCopyRead

CcInitializeCacheMap

CcMdlReadComplete

IoAllocateMdl

IoBuildPartialMdl

MmGetMdlByteCount

MmGetMdlByteOffset

MmGetMdlPfnArray

MmGetMdlVirtualAddress

MmGetSystemAddressForMdl

MmGetSystemAddressForMdlSafe

MmInitializeMdl

MmMapLockedPages

MmPrepareMdlForReuse

MmProbeAndLockPages

MmUnlockPages

MmUnmapLockedPages

 

 

Send comments about this topic to Microsoft