How Disk First Aid Repaired Catalog Files in Mac OS 9

In Mac OS 9, Disk First Aid served as Apple’s primary built-in utility for diagnosing and repairing file system inconsistencies on HFS (Hierarchical File System) and HFS Plus (Mac OS Extended) volumes. The Catalog File was the most critical directory structure on these drives, acting as a database that maintained the hierarchy of files and folders alongside their metadata. When file corruption occurred, Disk First Aid repaired the damaged Catalog File through a rigorous, multi-step process that involved isolating the drive, traversing and validating the Catalog B-tree, repairing broken node links, reconciling structural counts, and updating the volume header.

Isolation and Volume Mounting

Before attempting repairs, Disk First Aid placed the target volume into a read-only state or temporarily unmounted it. This prevented system extensions, running applications, or the Finder from writing new data while the diagnostic routines operated. If the target was the active startup disk, users were typically required to boot from a Mac OS 9 installation CD-ROM or a secondary disk to enable full write permissions for repairs.

Traversing the Catalog B-Tree

The Catalog File is structured as a balanced tree (B-tree) consisting of a header node, index nodes, leaf nodes, and free map nodes. Disk First Aid began by parsing the B-tree header to determine the root node location, tree depth, and total node count.

From the root, it traversed down through the index nodes to the leaf nodes, which contain the actual catalog records:

  • Directory records: Folder hierarchies and folder IDs.
  • File records: File attributes, data/resource fork sizes, creation/modification dates, and first data extents.
  • Thread records: Reverse-lookup links enabling the operating system to resolve a file or folder's parent directory.

During this traversal, Disk First Aid checked the physical integrity of each 512-byte (HFS) or 4096-byte (HFS Plus) node, verifying that node descriptors and record offsets were mathematically consistent and not overlapping.

Rebuilding Broken Node Chains

Leaf nodes in an HFS/HFS Plus Catalog B-tree are connected via forward and backward pointers, forming a doubly-linked list that allows sequential file searches. System crashes or improper shutdowns often corrupted these pointers, breaking directory searches.

Disk First Aid repaired broken node chains by:

  1. Identifying damaged leaf nodes with missing or pointing-to-invalid forward/backward addresses.
  2. Cross-referencing parent index nodes to determine where the broken node belonged in the sequence.
  3. Rewriting the forward and backward pointers in adjacent nodes to bypass or re-link the damaged node.

Pruning Corrupted Records and Resolving Threads

If a node contained unreadable or truncated records, Disk First Aid attempted to salvage undamaged records within that block and discard corrupted entries. When thread records were missing, the utility re-established the relationship between a file and its parent folder using the folder's Catalog Node ID (CNID). If a parent directory record was completely destroyed, orphaned files were relocated to a reconstructed directory, often labeled as a rescued items folder, to ensure files were not permanently lost.

Reconciling Metadata with the Volume Header

Once the internal structure of the Catalog File was repaired, Disk First Aid verified the data against other core file system components:

  • Volume Bitmap: Disk First Aid verified that all blocks mapped in the catalog records matched the allocation blocks marked as "in-use" in the Volume Bitmap.
  • Extents Overflow File: Files with more than three allocation extents relied on the Extents Overflow File. Disk First Aid confirmed that catalog records properly referenced any additional extents registered in the overflow B-tree.
  • Catalog Totals: Disk First Aid recalculated the total number of files, folders, and free nodes on the disk. It then updated the Master Directory Block (MDB) on HFS drives or the Volume Header on HFS Plus drives with the corrected counts.

In-Place Patching vs. Directory Rebuilding

Disk First Aid performed in-place patching rather than generating a completely new catalog file from scratch. It modified existing B-tree sectors directly to eliminate syntax errors, loop conditions, and bad pointers. If the Catalog File suffered catastrophic corruption—such as an entirely unreadable root node or extensive physical sector degradation—Disk First Aid would report that the drive could not be repaired, requiring full directory-rebuilding utilities or a volume reformat.