NtFlushBuffersFileEx - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers 
#ifndef _NTIOAPI_H
#if (PHNT_VERSION >= PHNT_WINDOWS_8)

/**
 * The NtFlushBuffersFileEx routine sends a flush request for a given file to the file system. An optional flush operation flag can be set to control how file data is written to storage.
 *
 * \param FileHandle A handle to the file object representing the file, directory, device or volume.
 * \param Flags Flush operation flags.
 * \param Parameters Pointer to a block with additional parameters. This parameter must currently be set to NULL.
 * \param ParametersSize The size, in bytes, of the block that Parameters point to. This parameter must currently be set to 0.
 * \param IoStatusBlock Address of the caller's I/O status block. This parameter is required and cannot be NULL.
 * \return NTSTATUS Successful or errant status.
 * \sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntflushbuffersfileex
 */
NTSYSCALLAPI
NTSTATUS
NTAPI
NtFlushBuffersFileEx(
    _In_ HANDLE FileHandle,
    _In_ ULONG Flags,
    _In_reads_bytes_(ParametersSize) PVOID Parameters,
    _In_ ULONG ParametersSize,
    _Out_ PIO_STATUS_BLOCK IoStatusBlock
    );

#endif
#endif

View code on GitHub
#ifndef _NTZWAPI_H

NTSYSCALLAPI
NTSTATUS
NTAPI
ZwFlushBuffersFileEx(
    _In_ HANDLE FileHandle,
    _In_ ULONG Flags,
    _In_reads_bytes_(ParametersSize) PVOID Parameters,
    _In_ ULONG ParametersSize,
    _Out_ PIO_STATUS_BLOCK IoStatusBlock
    );

#endif

View code on GitHub
// ntifs.h

__kernel_entry NTSYSCALLAPI NTSTATUS NtFlushBuffersFileEx(
  [in]  HANDLE           FileHandle,
  [in]  ULONG            Flags,
  [in]  PVOID            Parameters,
  [in]  ULONG            ParametersSize,
  [out] PIO_STATUS_BLOCK IoStatusBlock
);
View the official Windows Driver Kit DDI reference
// ntifs.h

NTSYSAPI NTSTATUS ZwFlushBuffersFileEx(
  [in]  HANDLE           FileHandle,
        ULONG            FLags,
        PVOID            Parameters,
        ULONG            ParametersSize,
  [out] PIO_STATUS_BLOCK IoStatusBlock
);
View the official Windows Driver Kit DDI reference

NtDoc

This function is documented in Windows Driver Kit here and here.

Edit description on GitHub

Windows Driver Kit DDI reference (nf-ntifs-ntflushbuffersfileex)

NtFlushBuffersFileEx function

Description

The NtFlushBuffersFileEx routine sends a flush request for a given file to the file system. An optional flush operation flag can be set to control how file data is written to storage.

Parameters

FileHandle [in]

Handle returned by NtCreateFile or NtOpenFile for the file whose buffers will be flushed. This parameter is required and cannot be NULL.

Flags [in]

Flush operation flags. Flags can be one of the following values:

Value Meaning
0 (normal) File data and metadata in the file cache will be written, and the underlying storage is synchronized to flush its cache. Windows file systems supported: NTFS, ReFS, FAT, exFAT.
FLUSH_FLAGS_FILE_DATA_ONLY File data in the file cache will be written. No metadata is written and the underlying storage is not synchronized to flush its cache. This flag is not valid with volume handles. Windows file systems supported: NTFS, FAT, exFAT.
FLUSH_FLAGS_NO_SYNC File data and metadata in the file cache will be written. The underlying storage is not synchronized to flush its cache. This flag is not valid with volume handles. Windows file systems supported: NTFS, FAT, exFAT.
FLUSH_FLAGS_FILE_DATA_SYNC_ONLY Data from the given file will be written from the Windows in-memory cache. Only metadata that is necessary for data retrieval will be flushed (timestamp updating will be skipped as much as possible). The underlying storage is synchronized to flush its cache. This flag is not valid with volume or directory handles. Windows file systems supported: NTFS.

Parameters [in]

Pointer to a block with additional parameters. This parameter must currently be set to NULL.

ParametersSize [in]

The size, in bytes, of the block that Parameters point to. This parameter must currently be set to 0.

IoStatusBlock [out]

Address of the caller's I/O status block. This parameter is required and cannot be NULL.

Return value

NtFlushBuffersFileEx returns STATUS_SUCCESS or an appropriate NTSTATUS value, such as one of the following:

Return code Description
STATUS_MEDIA_WRITE_PROTECTED The file resides on a write-protected volume; this is an error code.
STATUS_VOLUME_DISMOUNTED The file resides on a volume that is not currently mounted; this is an error code.
STATUS_ACCESS_DENIED The file does has neither write or append access.

Remarks

Minifilter drivers should call FltFlushBuffers2 instead of calling NtFlushBuffersFileEx.

A legacy file system filter driver can call NtFlushBuffersFileEx to issue an IRP_MJ_FLUSH_BUFFERS request to the file system for a given file. The flush operation is synchronous.

Callers of NtFlushBuffersFileEx must be running at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled.

For calls from kernel-mode drivers, the Nt*Xxx* and Zw*Xxx* versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

See also

FltFlushBuffers2

IRP_MJ_FLUSH_BUFFERS

Using Nt and Zw Versions of the Native System Services Routines

NtCreateFile

NtOpenFile

View the official Windows Driver Kit DDI reference

Edit description on GitHub

Windows Driver Kit DDI reference (nf-ntifs-zwflushbuffersfileex)

ZwFlushBuffersFileEx function

Description

The ZwFlushBuffersFileEx routine is called by a file system filter driver to send a flush request for a given file to the file system. An optional flush operation flag can be set to control how file data is written to storage.

Parameters

FileHandle [in]

Handle returned by ZwCreateFile or ZwOpenFile for the file whose buffers will be flushed. This parameter is required and cannot be NULL.

FLags

Flush operation flags. Flags can be 0 or one of the following values.

Value Meaning
FLUSH_FLAGS_FILE_DATA_ONLY If the file is on an NTFS file system, file data in the file cache will be written. No metadata is written and the underlying storage is not synchronized to flush its cache. This flag is not valid with volume handles.
FLUSH_FLAGS_NO_SYNC If the file is on an NTFS file system, file data and metadata in the file cache will be written. The underlying storage is not synchronized to flush its cache. This flag is not valid with volume handles.

Parameters

Address of the caller's I/O status block. This parameter is required and cannot be NULL.

ParametersSize

The size, in bytes, of the parameters block.

IoStatusBlock [out]

Address of the caller's I/O status block. This parameter is required and cannot be NULL.

Return value

ZwFlushBuffersFileEx returns STATUS_SUCCESS or an appropriate NTSTATUS value, such as one of the following:

Return code Description
STATUS_MEDIA_WRITE_PROTECTED The file resides on a write-protected volume; this is an error code.
STATUS_VOLUME_DISMOUNTED The file resides on a volume that is not currently mounted; this is an error code.
STATUS_ACCESS_DENIED The file does has neither write or append access.

Remarks

A file system filter driver can call ZwFlushBuffersFileEx to issue an IRP_MJ_FLUSH_BUFFERS request to the file system for a given file. The flush operation is synchronous.

Minifilter drivers should call FltFlushBuffers instead of calling ZwFlushBuffersFileEx.

Callers of ZwFlushBuffersFileEx must be running at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled.

Note If the call to the ZwFlushBuffersFileEx function occurs in user mode, you should use the name "NtFlushBuffersFileEx" instead of "ZwFlushBuffersFileEx".

For calls from kernel-mode drivers, the Nt*Xxx* and Zw*Xxx* versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

See also

FltFlushBuffers

IRP_MJ_FLUSH_BUFFERS

Using Nt and Zw Versions of the Native System Services Routines

ZwCreateFile

ZwOpenFile

View the official Windows Driver Kit DDI reference

Edit description on GitHub