After os.replace returns, why is os.fsync on the containing directory still needed?

## Two guarantees people run together **Atomicity** is about what other processes can observe: with the temp-file-then-rename pattern, a concurrent reader resolves the name either to the complete old file or to the complete new one. **Durability** is about what survives the machine losing power: whether the change is on the storage device or still only in memory. The rename buys the first outright. It buys none of the second, because like almost every filesystem operation it is applied to in-memory state and written to the device later, in whatever order the filesystem prefers. So after `os.replace` returns successfully there are three things that may still be only in memory: the new file's contents, the new directory entry that names it, and the removal of the old entry. A power loss at that moment can leave the directory looking exactly as it did before. ## The two syncs and their order ```python fd, tmp = tempfile.mkstemp(dir=directory) with os.fdopen(fd, "wb") as f: f.write(payload) f.flush() # Python buffer to the operating system os.fsync(f.fileno()) # operating system to the device os.replace(tmp, target) dir_fd = os.open(directory, os.O_RDONLY) try: os.fsync(dir_fd) finally: os.close(dir_fd) ``` **`flush()` is not `fsync`.** Flushing pushes bytes out of the file object's userspace buffer into the operating system. `os.fsync` asks the operating system to push its own cached copy down to the storage device and, on most platforms, to wait for it. Skipping the flush before the fsync means syncing a file the kernel has not been told about yet. **Sync the data before the rename.** If the rename reaches the device before the data does, a crash in between leaves a perfectly valid directory entry pointing at a file whose blocks were never written - the classic zero-length-file-after-a-crash report. Syncing first makes the ordering explicit rather than relying on a filesystem's own heuristics, which vary between filesystems and mount options. **Sync the directory after the rename.** The entry lives in the parent directory, so making the entry durable means syncing the directory itself. Builtin `open()` refuses a directory, so obtain a descriptor with the low-level `os.open(directory, os.O_RDONLY)`, pass it to `os.fsync`, and close it in a `finally`. You never read from it. This is a Unix technique; on Windows you cannot get a directory handle this way, and durability there is handled differently by the filesystem. ## What each sync buys you concretely * Data sync only: after a crash the name may still resolve to the old file, but you never see corruption. * Data sync plus directory sync: after a crash the name resolves to the new file, and its contents are complete. * Directory sync without a data sync: the worst of the options - the name may point at a file with no contents. Notice that even the full sequence does not promise *which* version you get after a crash; it promises that whichever one you get is whole and that once the directory sync returns, the new one is committed. ## The cost, and when to skip it `os.fsync` is expensive. It is a round-trip to the device, it can be milliseconds even on fast storage, and on a shared volume it can stall other writers. A route-optimisation job rewriting a 17-service dependency graph every few minutes should pay it without hesitation. The same job writing per-request scratch files thousands of times a minute should not - the syncs would dominate its runtime for data a restart would recompute anyway. The useful split is by what the file is for. Files whose loss changes correctness - state that cannot be recomputed, a checkpoint, an acknowledgement someone else relies on - get both syncs. Files that are caches or derived artefacts get the rename, which is nearly free and prevents corruption, and skip the syncs. The rename is about your readers; the syncs are about your recovery story, and the two decisions are independent. ## Diagnosing the absence The symptom of missing syncs is a file that is *old* after a hard reboot rather than corrupt: the service restarts with the previous version of its state and nobody can explain where the last update went, because the application logged a successful write. Reproducing it requires a real power cut or an equivalent - a clean process kill will not do it, because a kill does not discard the kernel's cache. That gap between how the bug is reported and how it is reproduced is why it survives so long in production systems.