Documentation
¶
Overview ¶
Package file provides atomic file write utilities and platform-specific optimizations. Atomic writes ensure that files are either fully written or not modified, preventing corruption from partial writes or concurrent access. Large files are marked as not needed to optimize page cache behavior on Linux systems.
Atomicity and durability are two different guarantees and this package provides both. The rename is what makes a reader see whole-old or whole-new bytes; it is NOT what makes the new bytes survive a power cut. Without an fsync of the file before the rename, and of the parent directory after it, a crash can leave the destination present but zero-length — the failure mode that took out the CNI conflist and the mesh-DNS snapshot fleet-wide on 2026-08-29 (#645, four power incidents on record for that cluster). Every write published by this package is therefore synced.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AtomicWrite ¶
AtomicWrite writes data atomically to a file with the specified permissions. It uses a temporary file in the same directory and atomically renames it to the target path.
func AtomicWriteReader ¶
AtomicWriteReader writes data from a reader atomically to a file with the specified permissions. It uses a temporary file and atomically renames it, marking large files as not needed for cache optimization. The temp file is fsynced before the rename and the parent directory after it: this path publishes the mesh-DNS record snapshot and the CNI conflist, both of which must survive an unclean power loss. It also installs binaries (the proxy supervisor onto its shared volume, the CNI plugin onto the host); WithOwner and KeepInPageCache are for those.
func Exists ¶
Exists checks if a file or directory exists at the given path. It returns false only if the file does not exist; other errors (such as permission denied) return true.
func WriteFileAtomic ¶
WriteFileAtomic writes data to a file atomically using a temporary file and rename. It ensures that the file is either fully written with the new data or left unchanged. The data is fsynced before the rename and the parent directory is fsynced after it, so the new contents survive a power cut rather than coming back zero-length.
Types ¶
type WriteOption ¶
type WriteOption func(*atomicWriteOpts)
WriteOption adjusts one AtomicWriteReader call.
func KeepInPageCache ¶
func KeepInPageCache() WriteOption
KeepInPageCache leaves the written file's pages in the page cache. By default AtomicWriteReader marks a large file FADV_DONTNEED once it is synced, which is right for a file this process only copies; it is wrong for a file that is read or exec'd straight afterwards, such as a binary installed onto the host.
func WithOwner ¶
func WithOwner(uid, gid int) WriteOption
WithOwner gives the written file the owner uid:gid. The temp file is chowned through its descriptor, after the chmod and before any byte is written, so the destination name never points at a file with another owner: a failed chown fails the write and leaves the destination as it was.
Source Files