atomicfile

Overview ¶

Package atomicfile writes a file atomically: a reader opening or reading the file sees either the old content or the new content in full, never a part of either.

Contract and Guarantees ¶

Every write follows a strict, bounded sequence:

1. Path and parent directory validation: The target path must be in clean canonical form (filepath.Clean(path) == path); non-clean paths (e.g. holding lexical ".." traversals or redundant slashes) are refused immediately to prevent lexical versus physical directory divergence. The parent directory must already exist; atomicfile never creates parent directories silently. The base filename must not exceed 241 bytes so that the temporary file's fixed 14-byte overhead does not exceed the filesystem NAME_MAX (255 bytes). Only standard file permissions 0000-0777 are supported; mode bits outside this mask (such as setuid 04755, setgid, sticky, or file-type bits) are refused. If the target is an existing directory or symlink, or if the parent directory is a symlink, is read-only, does not exist, or fails to resolve via EvalSymlinks, the operation is refused immediately with an error naming the path. A symlink parent is refused before anything is written; the error tells the caller to pass the real directory.
2. Exclusive temporary file creation: A temporary file is created exclusively in the SAME physical directory as the target file, using a fixed-length name of the form ".<base>.tmp-%08x" where the suffix is drawn from crypto/rand. This guarantees that concurrent writers never collide and temporary files never escape their parent directory.
3. Umask-honoring permissions: The temporary file is created with the caller's requested os.FileMode, allowing the process umask to apply naturally (perm & ^umask), matching the permission semantics of os.OpenFile and os.WriteFile. No explicit chmod is performed by default, so the process umask is preserved.
4. Full write and final permissions: The data payload is written to the temporary file in full. With ExactMode, chmod then sets the requested permission bits exactly, overriding the umask before the file is synced.
5. Media flush (fsync): The file contents and inode metadata are flushed to durable storage media using fsync (f.Sync()).
6. Clean closure: The temporary file descriptor is closed.
7. Atomic publication: The temporary file is renamed over the target path (os.Rename). With NoReplace, an exclusive hard link installs it only where the target is absent, and the temporary name is removed.
8. Parent directory fsync: The parent directory is fsynced (best-effort) after the publication so that the directory entry is durable on filesystems requiring directory flushes. Errors from directory fsync are ignored on platforms or filesystems where directory fsync is unsupported.

Failure and Cleanup Guarantees ¶

On any failure before publication (creation, write, chmod, sync, close, rename or exclusive link), atomicfile attempts to remove the temporary file immediately (os.Remove), leaving the target file completely untouched. If removing the temporary file fails (for example due to sudden permission loss or filesystem error), the cleanup error is joined to the returned error via errors.Join, explicitly naming the leftover temporary path so callers can detect and inspect any uncollected file. If NoReplace publishes successfully but removal of its temporary name fails, the returned error names both the created target and the leftover name. The complete target remains published; the parent-directory sync is still attempted.

Temporary files left behind by abrupt process termination outside runtime control (such as SIGKILL, power loss, or kernel panic) cannot be swept by defer and are not automatically removed on subsequent invocations.

Directory Boundary and Concurrency Note ¶

The initial symlink and directory check is a safeguard against accidental caller mistakes (e.g. attempting to overwrite a symlink or directory path, or writing through a symlink parent). It is designed for caller-owned directories; it is not an adversarial race-free lock against malicious actors concurrently swapping directory contents on untrusted trees.

Differences from os.WriteFile ¶

Callers migrating from os.WriteFile should note five key differences:

1. Atomicity: os.WriteFile truncates and overwrites in-place, allowing concurrent readers to observe truncated or empty intermediate states. atomicfile writes to a sibling temporary file first and renames, ensuring readers always see a complete version.
2. Permissions & umask: os.WriteFile preserves the permissions of existing files when overwriting them, and applies the process umask to newly created files. atomicfile creates a new sibling temporary file with perm masked naturally by the process umask (perm & ^umask) and renames it over the target; thus, the resulting file mode reflects perm & ^umask regardless of whether the target already existed. With ExactMode, chmod sets perm exactly before fsync; callers preserving an existing mode must explicitly select that option.
3. Inodes and hard links: Because atomicfile replaces the directory entry via rename(2), the target receives a new inode. Existing hard links to the target path continue pointing to the previous inode and will not reflect new writes.
4. Special files and FIFOs: If the target is an existing FIFO, socket, or device node, atomicfile does not write into the stream; atomic rename replaces the directory entry with a regular file.
5. fsync: atomicfile flushes file data and metadata with fsync before renaming, and performs a best-effort fsync on the parent directory after rename; os.WriteFile performs no fsync.

Power-Loss Durability (What is and is not promised) ¶

What is promised:

• Atomicity for readers: Concurrent readers in this process or other processes will observe either the pre-existing file or the newly written file, never a truncated file, zero-filled pages, or a partially overwritten mixture of the two.
• Data and file-metadata durability: The temporary file data and inode metadata are synced to persistent storage via fsync prior to rename. Once Write returns nil, the file contents are safely flushed to media.
• Directory entry durability: The parent directory is fsynced after rename on a best-effort basis, making directory entry creation durable across sudden power loss on filesystems that support directory fsync.

What is NOT promised:

• Platforms without directory sync: On platforms or filesystems that do not support directory fsync (e.g. Windows or filesystems where syncing a directory descriptor returns an error or is unsupported), parent directory sync is best-effort and silently ignored.