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

Статья
06/27/2024

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

Синтаксис

BOOL FlushFileBuffers(
  [in] HANDLE hFile
);

Параметры

[in] hFile

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

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

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

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

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

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

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

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

Замечания

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

Из-за взаимодействия с кэшированием дисков в системе функция FlushFileBuffers может быть неэффективной при использовании после каждой записи на устройство диска при выполнении многих операций записи отдельно. Если приложение выполняет несколько операций записи на диск, а также необходимо обеспечить запись критически важных данных в постоянный носитель, приложение должно использовать небуферированные операции ввода-вывода вместо частого вызова FlushFileBuffers. Чтобы открыть файл для неуправляемого ввода-вывода, вызовите функцию createFile 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 (TFO)	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Отказоустойчивая файловая система (ReFS)	Да

Примеры

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	fileapi.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll