Signatur
Beschreibung
fdatasync() leert den internen Puffer eines geöffneten Datei-Streams und stellt sicher, dass alle geänderten Dateidaten tatsächlich auf das physische Speichermedium geschrieben werden. Im Gegensatz zu fsync() werden dabei keine Metadaten (z. B. Änderungszeiten, Inode-Informationen) synchronisiert, was die Funktion in der Regel schneller macht.
Die Funktion ist besonders nützlich in Szenarien, bei denen Datenkonsistenz nach einem Systemabsturz oder Stromausfall kritisch ist – etwa beim Schreiben in Protokolldateien, Datenbanken oder anderen persistenten Speichern. Wenn nur die eigentlichen Dateiinhalte wichtig sind und auf Metadaten-Konsistenz verzichtet werden kann, ist fdatasync() die performantere Wahl gegenüber fsync().
Intern ruft die Funktion den systemnahen POSIX-Aufruf fdatasync(2) auf. Auf Systemen, die diesen Aufruf nicht unterstützen (z. B. macOS), fällt PHP automatisch auf fsync() zurück, sodass die Funktion plattformübergreifend verwendet werden kann.
Der Stream muss mit einem der Schreibmodi (w, r+, a usw.) über fopen() geöffnet worden sein. Für reine Lesezugriffe ist ein Aufruf in der Regel wirkungslos oder schlägt fehl.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $stream Pflicht | resource | Ein gültiger Datei-Stream, wie er von fopen() zurückgegeben wird. Muss eine reguläre Datei referenzieren. |
Rückgabewert
true zurück, wenn die Synchronisierung erfolgreich war, andernfalls false (z. B. bei einem ungültigen Stream oder einem E/A-Fehler).Beispiele
Kritische Daten sicher auf Disk schreiben
<?php
$datei = fopen('/var/log/kritisch.log', 'a');
if ($datei === false) {
die('Datei konnte nicht geöffnet werden.');
}
fwrite($datei, date('Y-m-d H:i:s') . ' - Wichtiger Eintrag' . PHP_EOL);
// Nur Dateidaten (nicht Metadaten) sicher auf Disk schreiben
if (!fdatasync($datei)) {
error_log('fdatasync fehlgeschlagen!');
}
fclose($datei);
?>Vergleich mit fsync: Wann fdatasync wählen?
<?php
$pfad = '/tmp/testdatei.bin';
$stream = fopen($pfad, 'w');
// Binärdaten in die Datei schreiben
fwrite($stream, random_bytes(1024));
// fdatasync: nur Dateiinhalt synchronisieren (schneller)
$start = microtime(true);
fdatasync($stream);
$dauerDatasync = microtime(true) - $start;
fwrite($stream, random_bytes(1024));
// fsync: Dateiinhalt UND Metadaten synchronisieren (vollständiger)
$start = microtime(true);
fsync($stream);
$dauerFsync = microtime(true) - $start;
fclose($stream);
printf("fdatasync: %.6f Sekunden\n", $dauerDatasync);
printf("fsync: %.6f Sekunden\n", $dauerFsync);
?>// Wichtig · Fallstricke
Plattformunterstützung: fdatasync() erfordert PHP 8.1.0 oder neuer. Auf Betriebssystemen ohne nativen fdatasync(2)-Systemaufruf (insbesondere macOS) wird intern automatisch auf fsync() ausgewichen – das Verhalten bleibt korrekt, aber der Geschwindigkeitsvorteil entfällt.
Kein Ersatz für Transaktionen: fdatasync() schützt vor Datenverlust durch Systemabstürze, ersetzt jedoch keine Transaktionsmechanismen bei komplexen Schreibvorgängen. Für atomare Schreiboperationen empfiehlt sich das Schreiben in eine temporäre Datei mit anschließendem rename() kombiniert mit fdatasync().
Performance: Das häufige Aufrufen von fdatasync() bei jedem kleinen Schreibvorgang kann die Performance erheblich reduzieren, da auf physisches Schreiben gewartet wird. Es empfiehlt sich, mehrere Schreibvorgänge zu bündeln und danach einmal zu synchronisieren.