How Mac OS 9 Handled Long File Names

Mac OS 9 bridged the gap between legacy computing and modern operating system capabilities by implementing structural and architectural changes to handle long file names. While the underlying HFS Plus (Hierarchical File System Plus) format supported file names up to 255 Unicode characters, decades of older applications were hardcoded to expect names capped at 31 characters. Mac OS 9 preserved backward compatibility by decoupling file identification from file names, deploying an updated API layer, and dynamically truncating names for older software.

The 31-Character Bottleneck

In the original HFS implementation, file names were stored as Pascal strings limited to 31 characters (Str31) in legacy character encodings, such as Mac OS Roman. Older system APIs, particularly routines using the FSSpec (File System Specification) record, stored the file name directly inside the data structure. Because the structure had a fixed size in memory, changing the string field to accommodate longer names would break memory layouts and immediately crash legacy software.

Transitioning from FSSpec to FSRef

To resolve the architectural limitation of FSSpec, Mac OS 9 made extensive use of modern File Manager APIs centered around the FSRef (File System Reference). Unlike FSSpec, an FSRef is an 80-byte opaque structure that identifies a file by its unique catalog node ID and volume reference rather than its literal string name.

Applications updated for Mac OS 9 and Carbon could query the full 255-character UTF-16 Unicode name stored in the HFS Plus catalog file using FSRef-based APIs. Legacy applications that continued using FSSpec could still target files, but the operating system had to intervene whenever a file name exceeded the 31-character limit.

Name Mangling and Short-Name Generation

When an older program requested file information using legacy APIs, Mac OS 9 generated a shortened alias, a process often referred to as name mangling.

  1. Truncation: The file system took the beginning of the long file name and truncated it.
  2. Uniqueness Token: It appended an internal identifier (similar to a hash or incremented index) and preserved the file extension if possible, ensuring the total length remained under 31 characters.
  3. Session Consistency: The mapping between the shortened name and the actual catalog record remained consistent within the running session, allowing the legacy application to open, read, edit, and save the file without corrupting the full name on disk.

Text Encoding Conversion

HFS Plus saved long file names natively in Unicode (specifically a decomposed form of UTF-16), whereas older Mac OS environments depended on the localized Script Manager encodings. Mac OS 9 used the Text Encoding Converter (TEC) subsystem during file operations. When a legacy application interacted with a file, the system converted Unicode characters into the nearest equivalent within the active Mac script system. If a character could not be translated into the legacy system's character set, fallback substitution characters were used to prevent data faults.

Through the combination of FSRef identifiers, automated name mangling for FSSpec calls, and robust text encoding translation, Mac OS 9 allowed long-named files to exist seamlessly on the same disk as legacy applications that were completely unaware of them.