{"id":50614571,"url":"https://github.com/algodesigner/fat12tool","last_synced_at":"2026-06-06T07:02:34.852Z","repository":{"id":346124239,"uuid":"1188586286","full_name":"algodesigner/fat12tool","owner":"algodesigner","description":"Lightweight FAT12 implementation in C with an interactive shell, FUSE mount support, and MBR partition handling. Supports standard 8.3 filenames.","archived":false,"fork":false,"pushed_at":"2026-04-01T09:23:49.000Z","size":327,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-01T11:34:14.097Z","etag":null,"topics":["c","cli","fat12","filesystem","fuse","fuse-filesystem","linux","macos","msx","msx-ide","msx2","osdev","retrocomputing","storage"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/algodesigner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-22T09:47:43.000Z","updated_at":"2026-04-01T09:23:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/algodesigner/fat12tool","commit_stats":null,"previous_names":["algodesigner/fat12tool"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/algodesigner/fat12tool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algodesigner%2Ffat12tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algodesigner%2Ffat12tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algodesigner%2Ffat12tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algodesigner%2Ffat12tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/algodesigner","download_url":"https://codeload.github.com/algodesigner/fat12tool/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/algodesigner%2Ffat12tool/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33972398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","cli","fat12","filesystem","fuse","fuse-filesystem","linux","macos","msx","msx-ide","msx2","osdev","retrocomputing","storage"],"created_at":"2026-06-06T07:02:33.125Z","updated_at":"2026-06-06T07:02:34.846Z","avatar_url":"https://github.com/algodesigner.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FAT12 Toolkit (CLI + Filesystem Mount)\n\nThis project provides two ways to work with FAT12 images:\n\n- `fat12tool`: interactive command shell for direct FAT12 read/write operations.\n- `fat12mount`: filesystem driver that mounts a FAT12 image to a regular directory so any application can use it.\n\nThe code is split into:\n\n- `fat12_core.c/.h`: portable FAT12 engine (allocation, directory operations, file IO).\n- `fat12tool.c`: interactive shell frontend.\n- `fat12mount.c`, `vfs_ops.h`, `vfs_fuse.c`, `vfs_winfsp.c`: cross-platform mounting via FUSE (Linux/macOS) or WinFSP (Windows).\n\n## Features\n\n- Read/write FAT12 files and directories\n- Create/remove files and directories\n- Truncate files\n- Persist metadata updates (write/access timestamps)\n- Preserve file attributes (timestamps, read-only, hidden) on host-image roundtrips\n- Open FAT12 at offset `0` (partition image) or at MBR partition offset (`--partition N`)\n- Cross-platform: works on Linux, macOS, and Windows\n\n## Current Limitations\n\n- FAT12 only (not FAT16/FAT32/exFAT)\n- 8.3 short filenames only (no long filename/LFN support)\n- No journaling/crash recovery\n- Root directory expansion is limited by FAT12 root entry table constraints\n- `rename` in mounting mode is implemented as copy+unlink for files, and directories are currently not supported for rename\n\n## Build\n\n### Linux\n\n```sh\nmake\n```\n\nInstall FUSE dependencies if needed:\n\n```sh\n# Ubuntu/Debian\nsudo apt-get update\nsudo apt-get install -y libfuse3-dev fuse3 pkg-config\n\n# Fedora\nsudo dnf install -y fuse3-devel fuse3 pkgconf-pkg-config\n```\n\n### macOS\n\n```sh\nmake\n```\n\nInstall FUSE-T:\n\n1. Install FUSE-T (Homebrew cask `macos-fuse-t/homebrew-cask/fuse-t`).\n2. Ensure FUSE headers are available (`/usr/local/include/fuse/fuse.h`) and `libfuse-t` is present (`/usr/local/lib/libfuse-t.dylib`).\n\n### Windows (MinGW + WinFSP)\n\n1. **Install WinFSP**: Download the installer from the [official website](https://winfsp.dev/). \n   * **Important**: During installation, ensure you tick the **\"Developer\"** section (it is unticked by default). This is absolutely essential as it contains the header files required for the build.\n2. **Configure PATH**: The WinFSP installer does not automatically add its binary directory to your system `PATH`. You must manually add `C:\\Program Files (x86)\\WinFSP\\bin` (or your custom install path) to your environment variables. This is essential for the application to load `winfsp-x64.dll` at runtime.\n3. Install make via [Scoop](https://scoop.sh/):\n```sh\nscoop install make\n```\n4. Install MinGW-w64 via Scoop:\n```sh\nscoop install mingw\n```\n5. Build:\n```sh\nmake fat12mount.exe\n```\n\n## Creating a New Image\n\nTo create a new blank FAT12 image, use the provided Python script (defaults to 1.44MB):\n\n```sh\n# Create standard 1.44MB image\npython3 scripts/create_fat12.py floppy.img\n\n# Create a 10MB image\npython3 scripts/create_fat12.py large.img 10240\n```\n\nNote: FAT12 is technically limited to \u003c 4085 clusters. The script automatically adjusts sectors per cluster to accommodate larger sizes (up to ~128MB with 64 sectors per cluster).\n\nAlternatively, you can use system tools:\n\n- **macOS**: `hdiutil create -size 1.44m -fs \"MS-DOS FAT12\" -volname \"MYFAT\" myfat.img`\n- **Linux**: `mkfs.fat -F 12 -C myfat.img 1440` (requires `dosfstools`)\n\n## Using `fat12tool` (Interactive Shell)\n\n```sh\n./fat12tool sample-fat12-p1.img\n```\n\nCommands:\n\n- `ls [path]` (displays entries with size, date and time)\n- `cd \u003cpath\u003e`\n- `pwd`\n- `cat \u003cpath\u003e`\n- `read \u003cimg_path\u003e \u003chost_path\u003e` (preserves timestamps and read-only status)\n- `write \u003chost_path\u003e \u003cimg_path\u003e` (preserves timestamps, read-only status, and hidden status for dot-files)\n- `touch \u003cpath\u003e`\n- `mkdir \u003cpath\u003e`\n- `rm \u003cpath\u003e`\n- `rmdir \u003cpath\u003e`\n- `stat \u003cpath\u003e` (displays detailed metadata including attribute bits)\n- `verify [--full] [--fix] [--verbose] [--yes]` (check and repair filesystem integrity)\n- `help`\n- `exit`\n\nExample session:\n\n```text\nfat12:/\u003e ls\nREADME.TXT                   62 2026-03-09 00:02:12\nHELLO.TXT                    14 2026-03-09 00:02:12\nTESTDIR        \u003cDIR\u003e          0 2026-03-09 00:02:12\nfat12:/\u003e cat /README.TXT\nfat12:/\u003e write ./local.txt /LOCAL.TXT\nfat12:/\u003e mkdir /DOCS\nfat12:/\u003e read /LOCAL.TXT ./copy.txt\nfat12:/\u003e exit\n ```\n\n## Filesystem Integrity Verification\n\nThe `verify` command performs comprehensive checks on FAT12 images and can repair common filesystem issues.\n\n### Basic Usage\n\n```sh\nfat12:/\u003e verify                    # Run basic integrity checks\nfat12:/\u003e verify --verbose          # Show detailed error information\nfat12:/\u003e verify --fix              # Attempt to fix detected issues\nfat12:/\u003e verify --fix --yes        # Auto-confirm fixes (no prompts)\nfat12:/\u003e verify --full --verbose   # Comprehensive check with details\n```\n\n### Checks Performed\n\n1. **FAT Consistency**: Verifies all FAT copies are identical\n2. **Cross-linked Clusters**: Detects cycles in cluster allocation chains\n3. **Orphaned Clusters**: Finds allocated clusters not referenced by any directory\n4. **Cluster Allocation Analysis**: Counts free, allocated, and bad clusters\n5. **Root Directory Validation**: Checks root directory entry limits\n\n### Repair Capabilities\n\n- **FAT Inconsistencies**: Synchronizes all FAT copies\n- **Cross-linked Clusters**: Breaks cycles by marking shorter/unreferenced chains as bad\n- **Orphaned Clusters**: Frees unreferenced clusters for reuse\n- **Automatic Backup**: Creates timestamped backup before any repair\n\n### Example Output\n\n```text\nfat12:/\u003e verify --verbose\nVerifying FAT12 image integrity...\nVerification Results:\n  FAT consistency: ✓ OK\n  Cross-linked clusters: ✗ 2 found\n  Orphaned clusters: ✓ None\n  Root directory: 15/224 entries (6.7%)\n  Free space: 124/2846 clusters (4.4%)\n  Total issues: 2\n\nfat12:/\u003e verify --fix\nVerifying FAT12 image integrity...\n✗ Found 2 cross-linked clusters\n\nProposed fixes:\n• Fix 2 cross-linked clusters (mark shorter chains as bad)\n• Create backup: sample.img.verify-backup-20260401-143022\n\nApply these fixes? [y/N]: y\nCreating backup... ✓\nApplying fixes...\n✓ Fixed 2 cross-links\n✓ All fixes applied successfully\n```\n\n### Options\n\n- `--full` : Perform comprehensive checks (currently always enabled)\n- `--fix` : Attempt to repair detected issues\n- `--verbose` : Show detailed progress and error information\n- `--yes` : Auto-confirm fixes (use with `--fix`)\n\n### Safety Features\n\n1. **Backup Creation**: Automatic timestamped backup before any repair\n2. **User Confirmation**: Requires explicit confirmation before applying fixes (unless `--yes` used)\n3. **Conservative Repair**: Marks problematic clusters as bad (0xFF7) rather than freeing, allowing data recovery\n4. **Memory Warnings**: Alerts if verification may use significant memory (\u003e50MB)\n\n## Using `fat12mount`\n\nThe mount point directory is created automatically (Windows) or must be created first (Linux/macOS). On all platforms, the directory is automatically removed after unmount.\n\n### Mount a partition image directly\n\n```sh\n# Windows: directory is created automatically\n# Linux/macOS: create directory first\nmkdir -p ./mnt\n\n./fat12mount --image sample-fat12-p1.img --mount ./mnt\n```\n\nIn another shell:\n\n```sh\nls -la ./mnt\ncat ./mnt/README.TXT\necho \"hello\" \u003e ./mnt/NEW.TXT\n```\n\n### Mount a partition inside an MBR disk image\n\n```sh\nmkdir -p ./mnt\n./fat12mount --image sample-fat12-2part.img --partition 1 --mount ./mnt\n```\n\nUse `--partition 2` for the second partition.\n\n### Unmount\n\n```sh\n./fat12mount -u ./mnt\n```\n\n## Test Suite\n\nRun full tests:\n\n```sh\nmake test\n```\n\n### `test-core` (C API tests)\n\nBinary: `fat12_core_test`  \nSource: `tests/test_fat12_core.c`\n\nCoverage includes:\n\n- Open and stat root\n- List root directory and validate fixture entries\n- Read existing file contents\n- Create new file\n- Sparse write behaviour (`offset \u003e file_size` zero-fills gap)\n- Truncate shrink behaviour\n- Create/remove nested directories and files\n- Proper error on `rmdir` non-empty directory\n- Timestamp update call\n- Persistence across close/reopen\n- Open FAT12 partition from MBR image offset and read expected content\n\n### `test-cli` (shell smoke test)\n\nScript: `tests/test_cli.sh`\n\nCoverage includes:\n\n- Launch `fat12tool`\n- `pwd`, `ls`, `cat`\n- `touch`, `write`, `read`\n- `mkdir`, nested file create/remove, `rmdir`\n- `stat`\n- Host roundtrip verification for written/read file content\n\n## Sample Images\n\nProvided fixtures:\n\n- `sample-fat12-p1.img`: standalone FAT12 partition image\n- `sample-fat12-p2.img`: standalone FAT12 partition image\n- `sample-fat12-2part.img`: MBR disk image with two FAT12 partitions\n\nThese include sample files for immediate testing.\n\n## Troubleshooting\n\n### `fat12mount` not built on Linux/macOS\n\nIf `make` prints:\n\n```text\nSkipping fat12mount (FUSE not available in build environment).\n```\n\nInstall FUSE development headers/libraries and rerun `make`.\n\n### Cannot mount on macOS\n\n- Confirm FUSE-T is installed (Homebrew cask `macos-fuse-t/homebrew-cask/fuse-t`).\n- If prompted, allow access to Network Volumes in Privacy \u0026 Security.\n- If `fat12mount` exits immediately with SIGTRAP, double-check that your\n  terminal app has Network Volumes permission.\n- Ensure the mountpoint directory exists and is writable.\n\n### Cannot mount on Windows\n\n- **WinFSP Installation**: Confirm WinFSP is installed. Download from [https://winfsp.dev/](https://winfsp.dev/).\n- **Missing Headers**: Ensure you ticked the **\"Developer\"** section during WinFSP installation. Without it, the build will fail as headers like `winfsp/winfsp.h` won't be found.\n- **Missing DLL**: If the application fails to start with a \"DLL not found\" error, ensure `C:\\Program Files (x86)\\WinFSP\\bin` is added to your system `PATH`. This is essential for loading `winfsp-x64.dll`.\n- **WinFSP Launcher**: Confirm the \"Launcher\" component was included during installation. Run the installer as Administrator to ensure the WinFsp.Launcher service is registered.\n- If you installed WinFSP without Administrator privileges, you can manually register the service:\n  ```cmd\n  sc create WinFsp.Launcher binPath= \"C:\\Program Files (x86)\\WinFSP\\bin\\launcher-x64.exe\" DisplayName= \"WinFsp Launcher\" start= demand\n  sc start WinFsp.Launcher\n  ```\n- If unmount fails, check that no other applications are using the mounted volume.\n\n### File names rejected\n\nCurrent implementation enforces FAT 8.3 names. Use names up to `8.3` format (`NAME.TXT`, `DATA.BIN`, etc.).\n\n## Development Notes\n\nThe FAT12 core is written to be embeddable and used by all frontends. If you add features (LFN, FAT16/32, better rename semantics), implement in `fat12_core` first, then expose via `fat12tool` and `fat12mount`.\n\nThe cross-platform mounting layer uses an abstraction via `vfs_ops.h`:\n- `vfs_fuse.c`: FUSE backend for Linux/macOS\n- `vfs_winfsp.c`: WinFSP backend for Windows\n\n## License\n\nThis project is licensed under the 3-Clause BSD License. See the [LICENSE](LICENSE) file for details.\nCopyright (c) 2026, Vlad Shurupov.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falgodesigner%2Ffat12tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falgodesigner%2Ffat12tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falgodesigner%2Ffat12tool/lists"}