Skip to content
John-KPublic

About

Rust library and CLI tool to manipulate Apple MFS floppy disk images

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

12 Commits

Folders and files

Repository files navigation

macfs

crates.io docs.rs license

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.

Library

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.

Command-line tool

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.

Testing

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.

Known limitations

  • Case-insensitive matching is MacRoman's, not Unicode's. Names are folded through a MacRoman uppercase table, approximating the classic Toolbox's _UprString/_RelString: README matches readme, and café matches CAFÉ, but ß deliberately does not match SS and ı does not match I, 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 u32 range 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; mkfs leaves 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/mkfs accept 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 are u32.
  • The whole image lives in memory, both to read and to write, so a volume costs its own size in RAM.
  • check reports, 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_path truncates the destination and writes the image over it; save_to does 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.

Resources

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 tagChecksum skips 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):

License

Licensed under either of

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.

About

Rust library and CLI tool to manipulate Apple MFS floppy disk images

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages