Edit

CcCoherencyFlushAndPurgeCache function (ntifs.h)

  • Article

The CcCoherencyFlushAndPurgeCache routine flushes, or flushes and purges, the cache to ensure cache coherency.

Syntax

void CcCoherencyFlushAndPurgeCache(
  [in]           PSECTION_OBJECT_POINTERS SectionObjectPointer,
  [in, optional] PLARGE_INTEGER           FileOffset,
  [in]           ULONG                    Length,
  [out]          PIO_STATUS_BLOCK         IoStatus,
  [in, optional] ULONG                    Flags
);

Parameters

[in] SectionObjectPointer

A pointer to a SECTION_OBJECT_POINTERS structure that contains the section object pointers of the file object.

[in, optional] FileOffset

A pointer to a variable that specifies the starting byte offset to flush, or to flush and purge.

[in] Length

The length in bytes of the data to flush, or to flush and purge, starting at FileOffset. This parameter is ignored if a NULL pointer is passed to FileOffset.

[out] IoStatus

A pointer to a caller-allocated IO_STATUS_BLOCK structure that receives the final completion status and information about the operation.

[in, optional] Flags

A bitmask of the following flags that specify how the operation is to be performed:

Value Meaning
CC_FLUSH_AND_PURGE_NO_PURGE Flush, but do not purge the cache. This is useful for read coherency flushes.
CC_FLUSH_AND_PURGE_GATHER_DIRTY_BITS Reserved for system use; do not use.
CC_FLUSH_AND_PURGE_WRITEABLE_VIEWS_NOTSEEN The caller can set this flag when there are no mappings to the file outside of the cache manager, in order to skip the expensive operation of trimming process working sets.

Return value

None

Remarks

Use CcCoherencyFlushAndPurgeCache when possible instead of an explicit flush and purge call sequence as it will invalidate user mapped views to prevent data corruption. CcCoherencyFlushAndPurgeCache ensures cache coherency; as such, there is no option to do a purge only via this function.

The file must be acquired exclusively before you call CcCoherencyFlushAndPurgeCache.

You can flush, or flush and purge, any byte range within a file by using the FileOffset and Length parameters. Or you can flush, or flush and purge, an entire file if you pass a NULL pointer to the FileOffset parameter.

A call to CcCoherencyFlushAndPurgeCache is a synchronous (blocking) operation, not an asynchronous (non-blocking) operation.

An IoStatus->Status value of STATUS_CACHE_PAGE_LOCKED indicates that page invalidation failed. Be aware that page invalidation can fail even if you pass CC_FLUSH_AND_PURGE_NO_PURGE in the Flags parameter. Note that STATUS_CACHE_PAGE_LOCKED is a success status (that is, testing it with the NT_SUCCESS macro would return TRUE).

Requirements

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

See also

CcFlushCache

CcPurgeCacheSection