CcPrepareMdlWrite function (ntifs.h)

Article
10/25/2021

The CcPrepareMdlWrite routine provides direct access to cached file memory so that the caller can write data to the file.

Syntax

void CcPrepareMdlWrite(
  [in]  PFILE_OBJECT     FileObject,
  [in]  PLARGE_INTEGER   FileOffset,
  [in]  ULONG            Length,
  [out] PMDL             *MdlChain,
  [out] PIO_STATUS_BLOCK IoStatus
);

Parameters

[in] FileObject

Pointer to a file object for the cached file.

[in] FileOffset

Pointer to a variable that specifies the starting byte offset within the cached file where the data is to be written.

[in] Length

Length in bytes of the data to be written to the system cache.

[out] MdlChain

A chain of one or more memory descriptor lists (MDL) describing the pages to which the data is to be written.

[out] IoStatus

Pointer to an IO_STATUS_BLOCK structure. If the call to CcPrepareMdlWrite 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

CcPrepareMdlWrite is similar to CcCopyWrite, except that the data is not copied to the cached file. Instead, the physical pages to be overwritten in the system cache are locked in memory, and CcPrepareMdlWrite returns one or more memory descriptor lists (MDL) describing the specified byte range. These pages remain locked in memory until CcMdlWriteComplete or CcMdlWriteAbort is called. Thus each call to CcPrepareMdlWrite must be followed by a call to CcMdlWriteComplete or CcMdlWriteAbort.

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.

Note that even if the call to CcPrepareMdlWrite 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 CcMdlWriteComplete to free the allocated MDLs.

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

To cache a file, use CcInitializeCacheMap.

Requirements

Requirement	Value
Target Platform	Universal
Header	ntifs.h (include Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	< DISPATCH_LEVEL