gazagnaire.org / ocaml-ext4
Pure ext4 superblock codecs and deterministic sparse images
Star
Fork 0
Watch
OCaml 74%
C 16%
4%
C++ 3%
Roff 2%
Dune <1%
3 1 0
c
lib
test
.gitignore
.ocamlformat
dune
dune-project
ext4.opam
LICENSE.md
README.md
README.md

ext4 #

ext4 is a pure OCaml library for the Linux ext4 on-disk format.

Building a Linux disk image usually means running mke2fs on the build host, which ties the output to that host's e2fsprogs version and its mke2fs.conf, and reading a partition's label or clean-unmount flag means parsing the superblock by hand. This library provides a typed Wire codec and a checked interpretation of the 1024-byte superblock, and a deterministic sparse formatter for one named profile: 4 KiB blocks and no extents. Callers provide the bytes and perform all filesystem I/O.

Ext4.Superblock separates magic-only inspection from checked geometry. Its raw Wire value retains every uninterpreted byte, so decoding and re-encoding an existing superblock does not erase reserved or future fields.

Ext4.Image produces ordered, non-overlapping metadata spans for an empty filesystem. Its Fixed_4k_no_extents profile uses 256-byte inodes, sparse superblocks and a JBD2 journal sized by the e2fsprogs curve. ext4 divides the disk into block groups and may keep a backup copy of the superblock in each; with sparse superblocks (sparse_super) only groups 0 and 1 and the groups whose number is a power of 3, 5 or 7 hold one. JBD2 is the Linux kernel's journalling layer: it logs metadata changes before writing them in place, so a mount after a power cut replays the log. The journal's size in blocks depends only on the filesystem's block count n, as e2fsprogs' ext2fs_default_journal_size computes it (Ext4.Image): none for n < 2,048, then 1,024 for n < 32,768, 4,096 for n < 262,144, 8,192 for n < 524,288, 16,384 for n < 1,048,576 and 32,768 above. A 1 GiB filesystem of 4 KiB blocks has n = 262,144 and so an 8,192-block (32 MiB) journal. Tiny filesystems, and geometries without room for the journal and its mapping blocks, omit the journal and its feature bit together. Timestamps and the default UUID are zero, so explicit inputs determine every output byte.

Installation #

$ opam install ext4

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install ext4

Status #

The package reads and writes the superblock and formats empty filesystems. It is not a filesystem driver: it does not read or write files, directories or extents. The Linux ext4 documentation (Documentation/filesystems/ext4/) is the specification, and e2fsprogs is the independent implementation the test fixtures are checked against.

The nox-fat, mbr and nox-qcow packages follow the same pure Wire codec and image layout conventions for other disk formats.

Licence #

ISC. See LICENSE.md.