Nothing inside an AppleDouble header file names its data file (except version 1’s entry 100), so the two are paired by their names, derived from the file’s real name. Apple’s developer note gives the rules for each file system; macOS follows a convention of its own.
AppleSingle file names
| File system | AppleSingle file |
|---|---|
| ProDOS | The name with illegal characters replaced or removed, cut to ProDOS’s 15 characters |
| MS-DOS | The name with illegal characters replaced or removed, cut to 8 characters, then the MS-DOS extension that suits the contents, such as .TXT for plain text |
| Unix and NFS | The name, escaped by one of the three conventions below |
AppleDouble file names
| File system | Data file | Header file |
|---|---|---|
| ProDOS | The name with illegal characters replaced or removed, cut to 13 characters, two fewer than ProDOS allows | R. (upper-case R, full stop) and the data file’s name |
| MS-DOS | The name cut to 8 characters, with the extension that suits the contents, such as .TXT | The same 8 characters with the extension .ADF (AppleDouble file) |
| Unix and NFS | The name, escaped by one of the three conventions below | % and the data file’s name |
| macOS | The name unchanged | ._ and the data file’s name |
On Unix and NFS, a header file and an AppleSingle or data file whose own name starts with
% are told apart by the magic number. For example, a ProDOS data file
THIS.IS.A.FOO. has the header file R.THIS.IS.A.FOO.. The
._ prefix is macOS’s own convention, outside Apple’s note; the Finder also puts
such files in a ZIP archive’s __MACOSX folder.
Nothing stops one file of a pair being renamed, moved or deleted without the other. The note gives the rules so that users and programs can see which files belong together. When the file is renamed on its home file system, the foreign names are derived again.
Escaping on Unix and NFS
Unix and NFS file systems use one of three conventions, the most complete one the file
system can hold, and the same one across a whole volume. Each must allow names of at least
93 characters. An escaped character is written as % and its two hexadecimal
digits.
| Convention | Characters kept | Characters escaped |
|---|---|---|
| 8-bit | All 8-bit characters | Slash (2F), NUL (00) and percent (25) |
| 7-bit ASCII | All 7-bit ASCII characters | Slash, NUL and percent, and every character from 80 to FF |
| 7-bit alphanumeric | Letters and digits, underscore (5F), and the last full stop (2E) | Slash, NUL and percent, and every other character |
Apple’s example is the Macintosh name Cañada return - 20%, in which
ñ is 96 in Mac OS Roman:
| Convention | Name on Unix or NFS |
|---|---|
| 8-bit | Cañada return - 20%25 |
| 7-bit ASCII | Ca%96ada return - 20%25 |
| 7-bit alphanumeric | Ca%96ada%20return%20%2d%2020%25 |
Escaping lengthens names, so some systems cannot hold a full 31-character Macintosh name; the note leaves that case undefined.
Version 1’s names
The version 1 note (File Type Note $E0/$0002) differs on Unix: illegal characters become
underscores and names are not cut short except by the system itself. A/UX puts
% in front of the data file’s name for the header file, dropping the last
character if the name would be too long. Other Unix systems may instead keep all the header
files in a .AppleDouble/ folder beside the data files, as Netatalk does. ProDOS
and MS-DOS names follow the same rules as above.
%RootInfo
AFP servers give each folder a directory ID, kept in entry 15 of the folder’s header file,
when the folder is created or when a folder’s header file without one is found. The next
unused ID is kept in %RootInfo, an AppleDouble header file in the root folder
of the volume, with entries 3, 4, 8, 9 and 15: real name, comment, the volume’s dates,
Finder info and the next file ID. It must be locked while it is updated.
Folders
Folders that a program creates are stored as AppleDouble files too, whose Finder info is the folder form.
Rules for writing and reading
- Programs may write either format but must understand both. They should read version 1 but write only version 2.
- Every entry is optional. A reader works with the entries its own file system uses and treats the rest as opaque data; it ignores entries it does not know, and keeps them when it moves or copies the file.
- Entries 1, 3 and 8 are usually written for every file; 2 only for Macintosh and ProDOS files; 4, 5, 6, 9 and 10 only for Macintosh files; 11 only for ProDOS, 12 only for MS-DOS; and 13, 14 and 15 only by AFP servers.
- Each entry is one contiguous block. Holes may be left for an entry to grow into, such as room for a comment to reach its 200-byte maximum.
- In an AppleSingle file, the data fork goes last, as the entry most often extended; the entries read most (Finder info, file dates, Macintosh file info) go near the header; and the resource fork is allotted space in blocks of 4K, so it can grow without the file being rearranged.
- In an AppleDouble header file, the resource fork goes last.
- An AppleSingle file, or an AppleDouble header file, is locked while it is in use.
- No header file is made for an existing foreign file or folder unless there is an entry to store.
- File servers neither create nor read the real name entry; they show the foreign name mapped back.
- AFP servers derive short names (entry 13) that start with
!, unique within the folder, and AFP clients may not open foreign files whose names start with it. - An AFP server sets the backup-needed attribute (entry 14) whenever the file is changed, or when the foreign file’s modification time is later than the one in entry 8.