FlushFileBuffers-Funktion (fileapi.h)

Artikel
06/27/2024

Löscht die Puffer einer angegebenen Datei und bewirkt, dass alle gepufferten Daten in eine Datei geschrieben werden.

Syntax

BOOL FlushFileBuffers(
  [in] HANDLE hFile
);

Parameter

[in] hFile

Ein Handle für die geöffnete Datei.

Das Dateihandle muss über das zugriffsrecht GENERIC_WRITE verfügen. Weitere Informationen finden Sie unter Dateisicherheits- und Zugriffsberechtigungen.

Wenn hFile- ein Handle für ein Kommunikationsgerät ist, löscht die Funktion nur den Übertragungspuffer.

Wenn hFile- ein Handle für das Serverende einer benannten Pipe ist, wird die Funktion erst zurückgegeben, wenn der Client alle gepufferten Daten aus der Pipe gelesen hat.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Die Funktion schlägt fehl, wenn hFile- ein Handle für die Konsolenausgabe ist. Das liegt daran, dass die Konsolenausgabe nicht gepuffert ist. Die Funktion gibt FALSE-zurück, und GetLastError gibt ERROR_INVALID_HANDLEzurück.

Bemerkungen

In der Regel schreiben die funktionen WriteFile und WriteFileEx daten in einen internen Puffer, den das Betriebssystem regelmäßig auf einen Datenträger oder eine Kommunikationspipeline schreibt. Die FlushFileBuffers--Funktion schreibt alle gepufferten Informationen für eine angegebene Datei auf das Gerät oder die Pipe.

Aufgrund von Zwischenspeicherungsinteraktionen innerhalb des Systems kann die FlushFileBuffers- Funktion ineffizient sein, wenn nach jedem Schreiben auf ein Laufwerkgerät verwendet wird, wenn viele Schreibvorgänge separat ausgeführt werden. Wenn eine Anwendung mehrere Schreibvorgänge auf einen Datenträger durchführt und außerdem sicherstellen muss, dass wichtige Daten in persistente Medien geschrieben werden, sollte die Anwendung nicht entbufferte E/A verwenden, anstatt häufig FlushFileBuffersaufzurufen. Rufen Sie die CreateFile--Funktion mit den Flags FILE_FLAG_NO_BUFFERING und FILE_FLAG_WRITE_THROUGH auf, um eine Datei für nicht gepufferte E/A-Vorgänge zu öffnen. Dadurch wird verhindert, dass der Dateiinhalt zwischengespeichert wird und die Metadaten mit jedem Schreibvorgang auf den Datenträger geleert werden. Weitere Informationen finden Sie unter CreateFile-.

Um alle geöffneten Dateien auf einem Volume zu leeren, rufen Sie FlushFileBuffers mit einem Handle auf das Volume auf. Der Aufrufer muss über Administratorrechte verfügen. Weitere Informationen finden Sie unter Ausführen mit speziellen Rechten.

Beim Öffnen eines Volumes mit CreateFile-sollte die lpFileName- Zeichenfolge die folgende Form aufweisen: \\.\x: oder \\?\Volume{GUID}. Verwenden Sie keinen nachfolgenden umgekehrten Schrägstrich im Volumenamen, da dies das Stammverzeichnis eines Laufwerks angibt.

In Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.

Technologie	Abgestützt
Server Message Block (SMB) 3.0-Protokoll	Ja
SMB 3.0 Transparent Failover (TFO)	Ja
SMB 3.0 mit Skalierungsdateifreigaben (SO)	Ja
Freigegebenes Clustervolumedateisystem (CsvFS)	Ja
Resilient File System (ReFS)	Ja

Beispiele

Ein Beispiel finden Sie unter Multithreaded Pipe Server.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	fileapi.h (include Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll