Функция FlushFileBuffers (fileapi.h)

Статья
08/23/2023

Очищает буферы указанного файла и вызывает запись всех буферных данных в файл.

Синтаксис

BOOL FlushFileBuffers(
  [in] HANDLE hFile
);

Параметры

[in] hFile

Дескриптор открытого файла.

Дескриптор файла должен иметь право доступа к GENERIC_WRITE . Дополнительные сведения см. в разделе Безопасность файлов и права доступа.

Если hFile является дескриптором для устройства связи, функция очищает только буфер передачи.

Если hFile является дескриптором серверного конца именованного канала, функция не возвращается, пока клиент не считает все буферные данные из канала.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Функция завершается ошибкой, если hFile является дескриптором выходных данных консоли. Это связано с тем, что выходные данные консоли не буферичены. Функция возвращает значение FALSE, а GetLastError — ERROR_INVALID_HANDLE.

Обычно функции WriteFile и WriteFileEx записывают данные во внутренний буфер, который операционная система регулярно записывает на диск или канал связи. Функция FlushFileBuffers записывает все буферизованные сведения для указанного файла на устройство или канал.

Из-за взаимодействия кэширования диска в системе функция FlushFileBuffers может быть неэффективной при использовании после каждой записи на устройство диска, когда большое количество операций записи выполняется отдельно. Если приложение выполняет несколько операций записи на диск и также должно обеспечить запись критически важных данных на постоянный носитель, приложение должно использовать небуферизованные операции ввода-вывода вместо частого вызова FlushFileBuffers. Чтобы открыть файл для небуферированных операций ввода-вывода, вызовите функцию CreateFile с флагами FILE_FLAG_NO_BUFFERING и FILE_FLAG_WRITE_THROUGH . Это предотвращает кэширование содержимого файла и сбрасывает метаданные на диск при каждой записи. Дополнительные сведения см. в разделе CreateFile.

Чтобы очистить все открытые файлы тома, вызовите FlushFileBuffers с дескриптором тома. Вызывающий объект должен иметь права администратора. Дополнительные сведения см. в разделе Выполнение с особыми привилегиями.

При открытии тома с помощью CreateFile строка lpFileName должна иметь следующий вид: \.\x: или \?\Volume{GUID}. Не используйте обратную косую черту в конце имени тома, так как это указывает на корневой каталог диска.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология	Поддерживается
Протокол SMB 3.0	Да
SMB 3.0 Transparent Failover (TFO)	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Восстанавливаемая файловая система (ReFS)	Да

Примеры

Пример см. в разделе Многопоточный сервер канала.

Требования


Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	fileapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll

См. также

CreateFile

Функции управления файлами

WriteFile

WriteFileEx