Part 6 of 7 · 4 min read
Atomic replace
Making an application's update atomic
Think of changing a sign on a shop. The safe way is to make the new sign in the workshop, check it, and then swap it in one move. Nobody sees half a sign. The analogy stops in one place: swapping a sign takes seconds, while a rename is one atomic step in the file system.
In plain words: The file system makes one thing atomic: rename of a name within one file system. A program that must replace a configuration file safely does not overwrite it in place, since a crash in the middle would leave half of the old and half of the new content. It writes the new content to a temporary file in the same directory, calls fsync on the temporary file so that its data is on disk, calls rename to put it over the old name in one step, and finally calls fsync on the directory so that the rename itself survives. After a crash, the name holds either the whole old file or the whole new one.
A worked example.
#include <fcntl.h>
#include <stdio.h>
#include <string.h>
#include <unistd.h>
/* Replace a file so that a crash leaves either the old content or the new one, never a mix. */
static int replace_file(const char *path, const char *text) {
char tmp[256];
snprintf(tmp, sizeof tmp, "%s.tmp", path);
int fd = open(tmp, O_WRONLY | O_CREAT | O_TRUNC, 0644);
if (fd < 0) return -1;
if (write(fd, text, strlen(text)) < 0) { close(fd); return -1; }
if (fsync(fd) < 0) { close(fd); return -1; } /* 1: the new content is on disk */
close(fd);
if (rename(tmp, path) < 0) return -1; /* 2: one atomic step swaps the names */
int dfd = open(".", O_RDONLY); /* 3: make the rename itself durable */
if (dfd >= 0) { fsync(dfd); close(dfd); }
return 0;
}
int main(void) {
replace_file("config.txt", "version 1\n");
replace_file("config.txt", "version 2\n");
char buf[64]; int fd = open("config.txt", O_RDONLY);
ssize_t n = read(fd, buf, sizeof buf - 1); buf[n > 0 ? n : 0] = 0;
printf("config.txt holds: %s", buf);
printf("config.txt.tmp exists: %s\n", access("config.txt.tmp", F_OK) == 0 ? "yes" : "no");
return 0;
}
Output:
config.txt holds: version 2
config.txt.tmp exists: no
The old content is replaced as a whole. The order of the three steps is what makes it safe. Without the first fsync, a crash might keep the rename but lose the data, and leave an empty file of the new name.
The key lines. The same pattern is used by editors, package managers and databases. It works because rename is atomic and because the data was made durable before the name was switched.
Atomic replace
An atomic replace is a way to change a file so that other programs and a crash see either the complete old content or the complete new content. A program writes the new content to a temporary file, forces it to disk, and renames it over the old name.
Example: writing config.txt.tmp, calling fsync, and then rename("config.txt.tmp", "config.txt").
Interview angle
A common question is "How does a journaling file system survive a crash, and what does it not protect?" A good answer describes the transaction, commit and replay, names the mode (ordered logs only metadata), and says that the journal does not make an application's several writes atomic, which needs fsync and rename.
Check yourself:
1. Why is the temporary file in the same directory?
2. Why is fsync needed before rename?
3. What does the fsync on the directory protect?
Words you will meet
| Word | Meaning |
|---|---|
| Crash consistency | Valid structures after a power cut. |
| fsck | Checks and repairs all the metadata. |
| Journal | A log of planned changes, written first. |
| Commit record | Marks a transaction as complete. |
| Checkpoint | Writing the logged blocks to their real places. |
| Barrier | A rule that keeps two writes in order. |
Quick notes
- A block append writes data, inode and bitmap. A crash can stop after any of them.
- Two of the eight subsets are correct. Others leak a block or point to a free block.
fsckchecks everything in passes. Its time grows with the metadata.- A journal writes a transaction and a commit record first, then checkpoints. Replay completes or discards it.
- Ordered mode logs metadata and writes data first. Data mode also logs data.
- A journal does not make application updates atomic. Use write, fsync, rename, fsync directory.