Michael Heilemann, The Norseman / The Viking - Field notes from the disk revival project: Apple II archiving
A claim I'll stand behind after building this whole pipeline: if you only implement one filesystem check on a DOS 3.3 disk beyond "does the catalog parse," make it this one. It catches more real corruption than the T/S-list walk from last post, including corruption that looks completely fine from every other angle. Here's why.
-=[ DOS 3.3 KEEPS A SECOND, INDEPENDENT RECORD OF THE TRUTH ]=-
Every disk validator worth using will walk the catalog and follow every file's track/sector chain, the way the last post described. That tells you what DOS 3.3's files claim about themselves. What it doesn't check is whether that story agrees with DOS 3.3's other bookkeeping: the allocation bitmap sitting in the VTOC, four bytes per track (the first two used, one bit per sector), that DOS uses to answer a completely different question: is this sector free, or is it in use?
That bitmap is written independently of the catalog and T/S list structures. It isn't derived from them at read time. It's DOS's own separate ledger, updated whenever a file is created, deleted, or resized. Which means it gives you something the catalog walk alone can never give you: a second, structurally independent opinion on the same question. When two independent sources of truth about the same disk disagree, that disagreement is a real indicator that something is wrong.
Reading the bitmap is simple once you know the layout. The VTOC is the one sector at track 17, sector 0, and the bitmap starts 0x38 bytes into it. Each of the 35 tracks gets four bytes there (35 × 4 = 140 bytes), and only the first two are used: 16 bits, one per sector. A bit set to 1 means the sector is free, and 0 means it's in use. That's the opposite of what you might expect, and it's the easiest thing to get backwards. The two bytes are also stored in the opposite order from what you'd guess: the first covers sectors 15 down to 8 and the second covers 7 down to 0. Here's the lookup, which takes the 256-byte VTOC and a track and sector and says whether the bitmap considers that sector allocated:
off = 0x38 + 4 * track
if sector < 8:
byte, bit = vtoc[off + 1], sector
else:
byte, bit = vtoc[off], sector - 8
free = bool(byte & (1 << bit))
return not free
Step by step: off is where this track's four bytes begin. Sectors 0 to 7 live in the second byte (vtoc[off + 1]) at the bit matching the sector number. Sectors 8 to 15 live in the first byte (vtoc[off]) at the sector number minus 8. The mask 1 << bit picks out that one bit, and since a set bit means free, the function returns the inverse. Track 12, sector 6, for example, is bit 6 of vtoc[0x38 + 48 + 1].
Track 12 as the bitmap stores it. Free sectors are 1 and used sectors are 0, and the bytes run in the order you would not guess.
-=[ THE CHECK THAT CATCHES SOMETHING ]=-
While following every file's T/S list (from the last post), this pipeline tracks who "owns" every sector it touches: the VTOC itself, the catalog chain, and each file's own T/S list and data sectors. Once that ownership map is built for the whole disk, it gets checked against the bitmap, sector by sector, in both directions:
| Bitmap says | Ownership map says | Meaning |
|---|---|---|
| Free | In use by a real file | Hard corruption. DOS's own free-space ledger disagrees with a file that claims to live there. One of the two is wrong, and it means this disk's bookkeeping is inconsistent with itself. |
| Allocated | Not owned by anything found | Usually benign. DOS reserves boot tracks it never assigns to a cataloged file, and deleted files leave their old sectors marked used until something overwrites them. Noted, not flagged as a problem. (The repair step described below can reclaim these.) |
The first row is the one worth dwelling on, because of exactly how it can happen without anything else on the disk looking wrong. Picture a file that legitimately occupied track 12, sectors 4 through 9. It gets deleted. DOS updates the bitmap to mark those sectors free again, but doesn't zero them out; it just changes one bit per sector. Now imagine a marginal read during a later transfer subtly corrupts a byte somewhere in a different file's T/S list, and that corrupted pointer happens to land on track 12, sector 6, one of those "freed" sectors. The catalog walk from the last post will happily follow that pointer, read whatever stale data is still physically sitting there, and never notice anything is wrong. It's a valid track, a valid sector, readable data. Only the bitmap cross-check catches it: DOS's own ledger says that sector is free, but a file is confidently claiming it.
This check takes more work than the others. It needs a full map of which file owns each sector, built during the walk and then compared against the 140 bytes of bitmap at the end. That's more code than "does the T/S chain terminate," and it only pays off on disks where everything else already looks fine. It's easy to leave out of a first version, but without it a silently corrupted disk can pass as a clean copy.
-=[ TWO SILENT SECTORS, ONE REAL BUG ]=-
There's a second direction this same ownership map catches, and it's not about the bitmap at all: two different files silently claiming the exact same sector. If "LANDER.BAS" and "LANDER.DATA" both have a T/S list entry pointing at track 8, sector 3, that's flagged the moment both show up in the ownership map for the same coordinates. A sector cannot belong to two files on a disk that's consistent with itself. This one doesn't even need the bitmap; it falls out of the same ownership-tracking machinery for free.
Put together, allocation-bitmap cross-checking and duplicate-sector detection are the two checks in this pipeline that consistently find damage nothing else does. They get there by building the full picture of a disk's sector usage instead of stopping the moment each individual file's chain terminates cleanly.
-=[ WHEN THE LEDGER IS WRONG: THE VTOC REBUILD ]=-
Detecting the disagreement is half of it. The other half is that the program can fix the ledger, on a repaired copy. When every file's chain reads cleanly, the catalog is the better witness and the bitmap is the one to correct. The rebuild frees sectors that are marked allocated but belong to nothing (deleted-file remnants and stale state), and allocates sectors that a file uses but the bitmap says are free. It never frees DOS's own tracks 0 to 2 or anything on track 17, it only changes the VTOC sector itself, and it refuses to run at all unless every file's chain completed without a loop, an off-disk pointer or a runaway. With a partial walk, "belongs to nothing" can't be told apart from "belongs to the part we couldn't read."
The rebuild trusts the catalog, which makes the order of repairs matter. If a bad link cuts a catalog sector off cleanly, every file in it looks like it belongs to nothing, and the bitmap rebuild would free its sectors. So the program repairs the catalog first (Part 9) and rebuilds the bitmap against the result.
The same logic now reaches one level up. The VTOC's header (35 tracks, 16 sectors, 256 bytes, 122 pairs per list, a sane allocator hint) is the same on every DOS 3.3 disk, and everything else here refuses a disk that doesn't say so. If that header is the damaged part, and track 17 still holds a chain of catalog sectors linked the way DOS's INIT links them (at least four, with believable entries), the standard values are written back and the rest of the sector is kept. If the bitmap was wiped as well, it is computed from the catalog once the catalog is repaired. Two guards matter. A disk that already reads as DOS 3.3 isn't touched, because odd header values are common on working disks. And a disk with no DOS image to boot (a data disk, or a protected game with its own loader) may have a blank VTOC on purpose, so there the damage is reported and nothing is written.
The caveat is the second row of the table above. Some protection schemes hide data in sectors that are marked allocated but belong to no file, and a rebuild would free them. That's why it's a switch (--no-vtoc-rebuild) and why Part 9 comes back to it. The repaired disk is a separate copy. Your original is untouched either way.
Beneath Apple DOS (chapter 4, "Emergency Repairs") describes exactly this repair, and names the most common way the ledger goes wrong. DOS allocates an entire track of sectors at a time while a file is open, so hitting RESET mid-write leaves sectors marked in use in the VTOC that were never added to any T/S list. Deleting the file can't free them, because they aren't in its list, and the disk reports DISK FULL while it isn't. The book's cure is the one this check automates: compare every sector in every T/S list against the bitmap. It also warns to copy files off with FID, not COPY, because COPY duplicates the whole disk image, bad VTOC and all.
The rebuild also repairs one thing outside the bitmap: the allocator hint from Part 4, the last-track and direction bytes in the VTOC. If they're out of range it resets them to track 17 moving up, a valid starting state whatever they held before, because DOS would otherwise follow them off the disk on the next write. Nothing else in the VTOC header is touched, since a header that disagrees may be a deliberate DOS variant rather than damage.
Next up: the same idea, a different filesystem. ProDOS keeps its own version of this ledger, a volume-wide free-block bitmap instead of DOS 3.3's per-track scheme, and the cross-check translates almost directly.
Prepare ye to plunder,
Michael Heilemann - The Norseman/The Viking