CcCoherencyFlushAndPurgeCache function (ntifs.h)
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 |