Binary files

A binary file stores the bytes of objects instead of their printed form. One fwrite call moves a whole record, and fread brings it back into a struct of the same type. The format is the memory layout from lesson 36, including its padding and its byte order, which is the catch.

Writing records

A record is a struct with a fixed-size name. The mode "wb" opens for writing in binary, which matters on systems that translate line endings. fwrite takes the address, the size of one element, the count and the stream, and returns how many complete elements it wrote.

#include <stdio.h> struct Record { int id; char name[16]; }; int main(void) { struct Record records[2] = {{1, "alpha"}, {2, "beta"}}; FILE *file = fopen("records.bin", "wb"); size_t written; if (file == NULL) { return 1; } written = fwrite(records, sizeof records[0], 2, file); fclose(file); printf("written: %zu\n", written); return 0; }

gcc -Wall -Wextra write.c -o write
./write

written: 2

The file is small: each record is twenty bytes on this machine, four for the int and sixteen for the name. The count returned is in elements, not bytes, so comparing it with two proves that both records went out. The buffer is flushed by fclose.

Reading them back

fread mirrors fwrite and returns the number of complete elements read. A loop that stops when the result is not one reads every record without knowing the count in advance. The struct must have exactly the layout that was written, or the fields land in the wrong bytes.

#include <stdio.h> struct Record { int id; char name[16]; }; int main(void) { struct Record record; FILE *file = fopen("records.bin", "rb"); size_t got; if (file == NULL) { return 1; } while ((got = fread(&record, sizeof record, 1, file)) == 1) { printf("%d %s\n", record.id, record.name); } fclose(file); return 0; }

gcc -Wall -Wextra read.c -o read
./read

1 alpha
2 beta

The assignment inside the condition is deliberate and parenthesised, so the compiler does not warn about it. The name in the struct is a terminated string only because the initialiser zeroed the rest of the sixteen bytes; a name of exactly sixteen characters would have no terminator.

Seeking to a record

Because every record has the same size, the position of record n is n times the size. fseek moves the read position, ftell reports it, and the next fread starts there. This is the random access that a text file with variable-length lines cannot give.

#include <stdio.h> struct Record { int id; char name[16]; }; int main(void) { struct Record record; FILE *file = fopen("records.bin", "rb"); if (file == NULL) { return 1; } if (fseek(file, (long) sizeof record, SEEK_SET) != 0) { fclose(file); return 1; } if (fread(&record, sizeof record, 1, file) == 1) { printf("second: %d %s\n", record.id, record.name); } printf("position: %ld\n", ftell(file)); fclose(file); return 0; }

gcc -Wall -Wextra seek.c -o seek
./seek

second: 2 beta
position: 40

The cast (long) is not decoration: the offset argument is a long while sizeof is unsigned, and the compiler warns about the mixed types under -Wconversion, as the last section shows. The position after reading the second record is 40, the end of the file.

Bytes and endianness

A binary file has no types: it has bytes. Writing the integer 0x01020304 and reading the file as four bytes shows the order the machine uses. On x86_64 the least significant byte comes first, so the file starts with 04.

#include <stdint.h> #include <stdio.h> int main(void) { uint32_t value = 0x01020304u; unsigned char bytes[4] = {0}; FILE *file = fopen("word.bin", "wb"); if (file == NULL) { return 1; } fwrite(&value, sizeof value, 1, file); fclose(file); file = fopen("word.bin", "rb"); if (file == NULL) { return 1; } if (fread(bytes, 1, sizeof bytes, file) == 4) { printf("%02X %02X %02X %02X\n", bytes[0], bytes[1], bytes[2], bytes[3]); } fclose(file); return 0; }

gcc -Wall -Wextra endian.c -o endian
./endian

04 03 02 01

A file meant for another machine writes each field in a defined byte order, usually big-endian, with shifts and masks from lesson 11. Writing a struct directly also writes the padding, which a different compiler may place differently.

A signed offset

The offset argument of fseek is a long, and an offset computed from size_t is unsigned. The conversion is harmless for a small file and silently wrong for an offset above the signed range, and -Wconversion reports the mixed arithmetic before the file is opened:

#include <stdio.h> struct Record { int id; char name[16]; }; int main(void) { struct Record record; size_t index = 1; FILE *file = fopen("records.bin", "rb"); if (file == NULL) { return 1; } fseek(file, sizeof record * index, SEEK_SET); if (fread(&record, sizeof record, 1, file) == 1) { printf("%d\n", record.id); } fclose(file); return 0; }

gcc -Wall -Wextra -Wconversion seekwarn.c -o seekwarn

seekwarn.c: In function 'main':
seekwarn.c:17:31: warning: conversion to 'long int' from 'long unsigned int' may change the sign of the result [-Wsign-conversion]
17 | fseek(file, sizeof record * index, SEEK_SET);
| ~~~~~~~~~~~~~~^~~~~~~

The program is not run here: the warning is the lesson, and the fix is the cast to long used in the seek section. A file larger than two gigabytes is where the difference becomes a real failure on a 32-bit long.

Exercises

1. Add a third record with a name of fifteen characters and read the file back; check that the name still has a terminator.
2. Write a function that updates record n in place with fseek and fwrite.
3. Store the record count in the first four bytes of the file and use it to allocate the array before reading.

The code on this page was run with gcc (Alpine 15.2.0) 15.2.0 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev