Skip to main content
Be Bitwise
CCapstone: Key-Value Store

Adding File Persistence

An in-memory key-value store forgets everything the moment the process exits. This lesson teaches it to remember — saving the table to a file and loading it back.

File Format

Format: one entry per line, key and value split by a tab.

c
name\tAlice
age\t30
city\tNew York

Easy to parse, easy to eyeball when something breaks, easy to cat. Production databases reach for binary because it's denser on disk, but text wins for teaching.

The format has one hard rule: a key can't contain a tab, and neither a key nor a value can contain a newline. Save note with the value line one\nline two and the file gets a second line with no tab, which the loader below throws away, so the value silently comes back cut short. The simplest fix is to refuse such strings in the command interface; the thorough one is to escape them (\t and \n as two characters) when saving and unescape them when loading.

Saving to Disk

c
int ht_save(HashTable *ht, const char *filename) {
FILE *fp = fopen(filename, "w");
if (!fp) return -1;
int saved = 0;
for (int i = 0; i < TABLE_SIZE; i++) {
Entry *entry = ht->buckets[i];
while (entry) {
if (fprintf(fp, "%s\t%s\n", entry->key, entry->value) < 0) {
fclose(fp);
return -1;
}
saved++;
entry = entry->next;
}
}
if (fclose(fp) != 0) return -1; // the final flush can fail too (disk full)
return saved;
}
Key Concept

Always check the return value of fopen(). A NULL return means the file could not be opened - maybe the directory does not exist, or you do not have write permission. Ignoring this leads to a segfault when you try to use the NULL pointer.

Loading from Disk

c
int ht_load(HashTable *ht, const char *filename) {
FILE *fp = fopen(filename, "r");
if (!fp) return -1;
char line[1024];
int loaded = 0;
while (fgets(line, sizeof(line), fp)) {
// Remove trailing newline
line[strcspn(line, "\n")] = '\0';
// Find the tab separator
char *tab = strchr(line, '\t');
if (!tab) continue;
*tab = '\0';
const char *key = line;
const char *value = tab + 1;
ht_set(ht, key, value);
loaded++;
}
fclose(fp);
return loaded;
}

The strcspn Trick

strcspn(line, "\n") hands back the index of the first newline, or the string's length when there isn't one. Drop a '\0' at that index and the trailing newline vanishes. Classic C idiom for sanitising fgets() output.

Error Recovery

Corrupt file? Our parser quietly skips any line missing a tab, which gives you a thin layer of resilience. Thin is the word. The runner below feeds ht_load's parsing loop a hand-made bad file (stored with a store stub in place of ht_set, so you can see each entry it would create). Predict which lines survive before you run it.

Try itFix the long-line bug: if fgets returns no newline, skip the rest of that line instead of parsing it.
C (GCC 9.2.0)
What went wrong, and one fix

The 80-character value doesn't fit, so fgets hands it over in two pieces. The first piece still contains bio and a tab, so it's stored with a truncated value. The second piece is parsed as a brand new line, and because the value happened to contain a tab, it creates a bogus xxxx… key with the value surprise. The NUL byte makes ci look like the end of the string, so strchr never finds the tab and the line is silently dropped.

For the long line, notice when fgets filled the whole buffer without reaching a newline, and throw away the rest of that line:

c
size_t len = strlen(line);
if (len == sizeof(line) - 1 && line[len - 1] != '\n') { // buffer full, line unfinished
int c;
while ((c = fgetc(fp)) != EOF && c != '\n') {}
continue; // or report an error
}
line[strcspn(line, "\n")] = '\0';

Rejecting the NUL line properly needs a reader that knows how many bytes it got, such as POSIX getline, which returns the length.

A production system would lean harder on:

  • Validate key and value lengths
  • Use checksums to detect corruption
  • Keep a write-ahead log for crash recovery

Atomic Saves

Lose power mid-fclose() and you can end up with half a file on disk. Safer pattern:

c
#include <fcntl.h>
#include <libgen.h> // dirname
#include <unistd.h>
// fsync() pushes a file's data from the kernel's page cache to the disk.
// It works on any open descriptor, so reopen the path to get one.
static int fsync_path(const char *path) {
int fd = open(path, O_RDONLY);
if (fd < 0) return -1;
int rc = fsync(fd);
close(fd);
return rc;
}
int ht_save_safe(HashTable *ht, const char *filename) {
char tmpname[256];
if (snprintf(tmpname, sizeof(tmpname), "%s.tmp", filename) >= (int)sizeof(tmpname))
return -1; // name too long to add .tmp
// ht_save's fclose() has already flushed stdio's buffer to the kernel
int result = ht_save(ht, tmpname);
if (result < 0 || fsync_path(tmpname) != 0) {
remove(tmpname);
return -1;
}
// Atomic rename replaces the old file
if (rename(tmpname, filename) != 0) {
remove(tmpname);
return -1;
}
// The rename lives in the directory, so sync that too
char dir[256];
snprintf(dir, sizeof(dir), "%s", filename);
if (fsync_path(dirname(dir)) != 0) return -1;
return result;
}

On POSIX filesystems rename() is atomic. You'll see the old file or the new one, never a hybrid stitched out of both. That guarantee is about what other processes see, though. To survive a power cut as well, the data has to be on the disk before the rename, which is what the first fsync is for, and the directory has to be synced afterwards so the new name sticks. Skip the first and a crash can leave the new name pointing at an empty or partial file; skip the second and the old file can reappear after a reboot.