Read and write MFS (Macintosh File System) floppy disk images — the flat
filesystem the original 1984 Macintosh used on its 400K single-sided floppies,
and on the 800K double-sided ones that followed — with no dependencies beyond
std.
Images may be bare sector dumps or DiskCopy 4.2 containers; the container is autodetected on open and written back in the same shape. Anything the crate does not interpret is preserved verbatim — boot blocks, reserved MDB and directory fields, DiskCopy 4.2 tags — so opening an image and saving it again without changes reproduces the original bytes exactly. HFS volumes are detected and reported as unsupported.
use macfs::{Fork, ImageFormat, MfsVolume, Result};
use std::io::Cursor;
fn main() -> Result<()> {
// Format a blank 400K volume in memory and put a file on it. `add_file`
// places the entry and both forks in one all-or-nothing step.
let mut vol = MfsVolume::format(MfsVolume::FLOPPY_400K, "My Disk", ImageFormat::Raw)?;
vol.add_file("Read Me", *b"TEXT", *b"MACA", b"hello from 1984", &[])?;
let mut image = Cursor::new(Vec::new());
vol.save_to(&mut image)?;
// Read it back. Name lookup is case-insensitive, as on a real Mac.
let disk = MfsVolume::open(Cursor::new(image.into_inner()))?;
assert_eq!(disk.read_fork("read me", Fork::Data)?, b"hello from 1984");
Ok(())
}Volumes are handled whole: open pulls the entire image into memory, every
operation works on that copy, and one save_to call re-serializes it. Nothing
touches the image between those two points, so a filesystem operation that
fails — a full volume, a locked file, a name that will not fit — leaves the
in-memory volume unchanged and never reaches the file at all. Saving itself is
the one step that writes: save_path creates (and so truncates) the file
before streaming the image into it, so an I/O failure part-way through a save
can leave a short file behind, and save_to does not truncate at all — it
writes from offset 0 over whatever the stream already held. Files have the two
classic Mac forks (data and resource), and names are stored as MacRoman.
The crate ships an mfs binary:
mfs info <image>
mfs ls <image> [-l]
mfs cat <image> <name> [--rsrc]
mfs extract <image> <name> [--rsrc] [-o PATH]
mfs add <image> <hostfile> [--name NAME] [--type XXXX] [--creator XXXX] [--rsrc HOSTFILE] [--force]
mfs rm <image> <name> [--force]
mfs mv <image> <old> <new>
mfs touch <image> <name> [--created "YYYY-MM-DD HH:MM:SS"] [--modified "..."]
mfs settype <image> <name> [--type XXXX] [--creator XXXX]
mfs lock <image> <name>
mfs unlock <image> <name>
mfs label <image> <newname>
mfs mkfs <image> [--size 400k|800k|BYTES] [--name NAME] [--dc42] [--force]
mfs convert <image> --to raw|dc42 [-o OUT]
mfs check <image>
mfs bootblocks <image> [--export FILE | --import FILE]
mfs help
mfs add --force replaces an existing file instead of refusing, rewriting its
type and creator too — so leaving --creator off resets it to ????.
Exit codes:
| Code | Meaning |
|---|---|
| 0 | Success. For check: the volume is clean, or only warnings were reported. |
| 1 | The operation failed (no such file, volume full, unreadable image, …), or check reported at least one problem. |
| 2 | The command line was wrong: unknown command, missing or repeated argument, unknown option. |
The unit, round-trip and robustness suites are self-contained, with one
deliberate exception: a single unit test inside the library compares the
geometry format() computes against an Apple-formatted blank disk field by
field, and it lives there rather than in tests/ because that comparison
needs the crate's private structures. Like every golden test it skips when
the image has not been fetched.
The robustness suite throws roughly 1,600 deterministic hostile mutants of
real images at the public API and asserts that it never panics, never hangs
and never allocates on the strength of a number it read out of the image —
every failure is a typed MfsError.
The golden tests additionally verify byte-identical open/save against real
Apple system disks, which are copyrighted and not distributed with the crate;
run scripts/fetch-test-images.sh to download them into tests/images/, and
set MACFS_REQUIRE_GOLDEN=1 to make their absence a test failure instead of a
skip. See TESTING.md for details.
- Case-insensitive matching is MacRoman's, not Unicode's. Names are folded
through a MacRoman uppercase table, approximating the classic Toolbox's
_UprString/_RelString:READMEmatchesreadme, andcafématchesCAFÉ, butßdeliberately does not matchSSandıdoes not matchI, because MacRoman has no capital for either — which is what a real Mac did. - Timestamps have no time zone. MFS stores seconds since 1904-01-01 as the
creating machine's wall clock, with no offset recorded, so the crate applies
no correction. The
u32range ends at 2040-02-06. - DiskCopy 4.2 tags are preserved, not maintained. The tag bytes of an image that has them are carried through edits verbatim; they are not recomputed to describe the files you write. Wrapping a raw image in a container writes zeroed tags, and unwrapping one drops them.
- HFS is detected and rejected, not read: an HFS volume comes back as
MfsError::UnsupportedHfs. - Boot blocks can be imported, never synthesized. The boot code is Apple's
68K ROM loader;
mkfsleaves the region zeroed, and a bootable disk is made by copying the 1,024 boot-block bytes off a real system disk. - MFS is flat. There are no folders, and a file created here gets a zero Finder icon position, so the Finder places the icon itself on first sight.
- One volume per image. No partition maps and no multi-volume containers.
- Size limits.
format/mkfsaccept 100 KiB to 32 MiB, in whole 512-byte sectors (a DiskCopy 4.2 container additionally means exactly 400K or 800K, the only geometries the format encodes). MFS's 12-bit allocation map caps any volume at 4,078 allocation blocks however large it is, and fork lengths areu32. - The whole image lives in memory, both to read and to write, so a volume costs its own size in RAM.
checkreports, it never repairs. Findings come back as warnings (things a real Mac tolerates, reads unaffected) and problems (anything that breaks a read or hides a file from lookup); fixing them is left to you.- Saving is not atomic.
save_pathtruncates the destination and writes the image over it;save_todoes not truncate, so writing a smaller volume over a larger stream leaves the old tail behind. - Names are MacRoman, 1–63 bytes for a file and 1–27 for a volume, with
:and NUL forbidden; anything MacRoman cannot encode is rejected.
Format documentation:
- Inside Macintosh, Volume II, "The File Manager" (Apple, 1985) — the MFS
on-disk structures: master directory block, file directory, and the 12-bit
allocation block map. Field names in the source (
drSigWord,flFndrFlags, …) follow its nomenclature. - MFSLives — Apple's MFS sample code, a reference implementation of the format.
- The DiskCopy 4.2 container layout and its checksum algorithm — including the
undocumented but universal quirk that
tagChecksumskips the first sector's 12 tag bytes — were matched against real images produced by Apple's Disk Copy.
Golden test images (fetched by scripts/fetch-test-images.sh; provenance and
license notes in TESTING.md):
Sample.imgfrom the MFSLives repo — Apple's sample MFS volume.- Mini vMac blank disk images
(gryphel.com) — Apple-formatted blank 400K/800K volumes, used as the
mkfsoracle. - earlymacintosh.org — Finder 1.0, System 1.1, and System 2.0 boot disks.
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Developed with the help of Claude Code.