Files of these types and auxiliary types contain file data in AppleDouble format.
Changes since March 1990: Added information about AppleDouble 2.0.
AppleDouble is one of two standards (the other is AppleSingle) put forth by Apple Computer, Inc. for representing files on foreign file systems while preserving all attributes of the file's home system on file systems that do not support the same attributes.
Experience indicated that a single format would be inadequate to cover all cases. Two closely related formats, however, can serve most needs. Although the primary impetus for developing these formats is storing extended files (files with both resource and data forks) on file systems that do not support the notion of two forks, the proposed formats are general enough that they can be used to represent a file from any file system on any other file system.
AppleDouble keeps the data fork as a separate file from the file attributes and the resource fork, and this Note describes this file format. AppleSingle keeps all attributes and the contents of both forks in a single file in the foreign file system, and is described in the File Type Note for File Type $E0, Auxiliary Type $0001.
AppleSingle is intended to be used primarily as a storage format, especially for cases where you must store an extended file on a foreign file system and later reconstruct the extended file. AppleDouble is more appropriate for applications where the users of the foreign file system might want to modify the contents of the file. Since most applications keep file data in the data fork, AppleDouble format saves the contents of the data fork in one file. All other file attributes, including the resource fork, are kept in a separate file.
There are several reasons for supporting an interchange format between file systems. Perhaps the most germane is one of the least obvious: handling extended files on foreign file systems which do not support extended files.
For example, the ProDOS FST in GS/OS can create an extended file on a ProDOS disk. However, ProDOS 8 is unable to operate on the file, since it sees it as having an unsupported storage type. If a telecommunications program or other utility capable of transferring files is operating under ProDOS 8 and attempts to receive an extended file, it is unable to create the file.
At this point, the application could use READ_BLOCK and WRITE_BLOCK commands, along with a knowledge of the ProDOS file system, to create the file on its own. However, this is strongly discouraged. The ProDOS file system format for extended files is not documented and could change in the future. In addition, the program could be running on a eight-bit system. If the disk is only used on an eight-bit system, the extended files would not only be unwanted, but also unremovable without using the disk on an Apple IIGS or later system running GS/OS.
However, if the application is aware of the AppleDouble format, it can quickly store an extended file in AppleDouble, leaving the conversion back to the extended file to GS/OS, or another operating system. This is the recommended way for ProDOS 8 applications to create and handle extended files. Use either AppleSingle or AppleDouble.
AppleDouble consists of two files, an AppleDouble Header File and an AppleDouble Data File. The AppleDouble Header file contains a header followed by data. The header consists of several fixed fields and a list of entry descriptors, each pointing to an entry. Apple defines these standard entries: Resource Fork, Real Name (name in the home file system), Comment, Icon and File Info. Each entry is optional, so it may not appear in the file. We also define the new entry Data Pathname, pointing to the pathname of the AppleDouble Data File. The Header File has exactly the same format as an AppleSingle file, except it has no data fork entry. The AppleDouble Data File consists of just the data fork of the file, with no extra header at all.
Note: All numeric entries, including entries representing ProDOS data structures (such as file type and auxiliary type) are Reverse ordered. This is provided so any host CPU can attempt to interpret entries in the header without having to know the standard byte-ordering of the home file system. Therefore, in this Note you see descriptive entries like "Rev. 4 Bytes." This serves as a reminder that all header fields are stored high byte first, even though the notation Bytes does not imply any specific ordering in other File Type Notes.
Also note that ASCII strings are not stored in reverse order, just non-ASCII constants.
The Real Name entry indicates the file's original filename in the host file system. This is not a Pascal or C string; it is just ASCII data. The length is indicated by the Entry Length field for the Real Name entry.
The File Info entry (Entry ID = 7) is different for each home file system. For ProDOS files, the entry is 16 bytes long and consists of the creation date and time and the modification date and time in ProDOS 8 (ProDOS 16/class zero GS/OS) form, the access word, a two-byte file type and four-byte auxiliary type. This is detailed in standard format below, along with defined File Info entries for some other file systems.
Note: Although the ProDOS Access field, File Type and Auxiliary Type are the same length as found in ProDOS 16 and GS/OS structures, the Create and Modification Dates and Times are stored in two-byte (albeit byte-reversed) ProDOS 8 format, not eight-byte Apple IIGS format.
The Finder Info entry (Entry ID = 9) is for files where the host file system is Macintosh. It consists of 16 bytes of Finder Info followed by 16 bytes of Extended Finder Info. These are the fields ioFlFndrInfo followed by ioFlXFndrInfo, as described in Inside Macintosh, Volume IV-183. Newly created files have zeroes in all Finder Info subfields. If you are creating an AppleDouble file whose home system is Macintosh, you may zero all unknown fields, but you may want to set the fdType and fdCreator subfields.
The Data Pathname entry (Entry ID = 100) is defined for the first time in this Note. It consists of a class one GS/OS input string noting the pathname of the AppleDouble Data File as originally created:
For strategies on using this segment (or not using it) to find the AppleDouble Data File, see the section "Finding the AppleDouble Data File."
The entries themselves follow the header field and the entry descriptors. The actual data representing each entry must be in a single, contiguous block. The offset field in that entry's descriptor points to it. The entries could appear in any order, but since the data fork is the entry that is most commonly extended, Apple strongly recommends that the data fork always be kept last in the file to facilitate its extension. Apple also recommends that those entries that are most often read, such as Real Name, File Info (and Finder Info if present) be kept as close as possible to the header to maximize the probability that a read of the first few blocks of the file retrieves these entries.
It is possible to have holes in the file (unused space between entries). To find the holes, you must take the list of entry descriptors and sort them into increasing offset order. If the offset field of an entry is greater than the offset plus the length of the previous entry (sorted), then a hole exists between the entries. You can make use of such holes; for example, if a file's comment is ten bytes long, you could create a hole of 190 bytes after the comment field to easily allow for the comment to later expand to its maximum length of 200 bytes. Because an AppleDouble file may contain holes, you must find each entry by getting its offset from its entry descriptor, not by assuming that it begins after the previous entry.
Byte ordering in file header fields follows 68000 convention, and each header field has been so noted by the Reverse operator.
The AppleDouble Data File is simply the data fork of the original file contained in a file of its own. You may create it with a File Type and Auxiliary Type assignment best suited to it, if desired. For example, if the program creating the AppleDouble Data File knows that the data fork contains strictly ASCII text, it could create the file with File Type $04 (Text File) so that other applications can deal with it accordingly.
If the creating program wishes to make no assumptions about the content of the data fork, it is encouraged to create the AppleDouble Data File with file type $E0 and auxiliary type $0003. This identifies the file as an AppleDouble Data File.
As this is an interchange format, from a ProDOS directory entry there is no way to guarantee which files are AppleDouble files. Apple has allocated File Type $E0, Auxiliary Type $0002 for files which are AppleDouble Header Files, and File Type $E0, Auxiliary Type $0003 for files which are AppleDouble Data Files. We strongly encourage ProDOS 8 and GS/OS applications to use these file type and auxiliary type assignments when creating AppleDouble files.
AppleDouble files which do not have file type $E0 and auxiliary type $0002 or $0003 can most easily be identified by opening them and attempting to interpret them. If it is not an AppleDouble Header File, the Magic Number is not contained in the first four bytes of the file. The chances that the file would begin with those four bytes and not be an AppleDouble Header File, on a purely random basis, are 4,294,967,295 to 1. The chances that both the Magic Number and the Version bytes would be the same in a non-AppleSingle file are roughly 1.8 x 10^19 to 1.
Since the AppleDouble Data File can be stored anywhere, with any file type and auxiliary type, a program may have to make an effort to find it. We recommend the following steps:
Apple proposes the following standard for identifying AppleDouble Header File names and AppleDouble Data File names from the file's real name.
To generate the AppleDouble Data File name, use character substitution or deletion to remove illegal characters, and use truncation if necessary to reduce the length of the name to two characters less than the maximum file name length. This would be a maximum of 13, since the maximum file name length is 15.
To generate the AppleDouble Header File name, prefix the AppleDouble DataFile name with the characters "R." (uppercase R period).
For example, the file name "This is a Foo File" could translate to an AppleDouble Data File Name of "THIS.IS.A.FOO." The AppleDouble Header File name would then be "R.THIS.IS.A.FOO."
To generate the AppleDouble Data File name, use character substitution to replace any illegal characters with an underscore (_). Since different Unix systems have different requirements on maximum file name length, do not explicitly truncate the name to a specific length. Rather, allow the truncation to be done by the Unix functions create(), open(), etc.
To generate the AppleDouble Header File name, A/UX (Apple's implementation of Unix for Macintosh computers) prefixes a percent sign (%) to the AppleDouble Data File name. If necessary, truncate the last character to keep the file name within the legal length range. Other Unix systems may prefix a directory name (e.g., ".AppleDouble/") to the AppleDouble Data File name to create the name of the AppleDouble Header File. In this scheme, all AppleDouble Header Files corresponding to AppleDouble Data files are kept together in a single subdirectory.
To generate the AppleDouble Data File name, use character substitution or deletion to remove illegal characters, and use truncation if necessary to reduce the length of the name to eight characters. Then add the MS-DOS extension that is most appropriate to the file (such as "TXT" for a pure text file).
To generate the AppleDouble Header File name, add the extension ".ADF" to the eight-character file name.
In any instance, most programs probably wish to display the names being used for both AppleDouble files, so that the user may keep track of them on disk.
AppleDouble name derivations will be defined for all other file systems of interest. This allows applications running on the foreign file system (and users as well) to see easily which files are AppleDouble pairs. Knowledgeable users, if they know the derivation, could rename or move the files so as to preserve the connection between the two. However, there is no guaranteed way to prevent one file of the pair from being inconsistently renamed, moved, or deleted.
AppleDouble 2.0 is a revision to the original AppleDouble specification described in this Note. AppleDouble 2.0 comes closer to the ideal of an interchange format by allowing file information for multiple file systems in the same AppleDouble file.
AppleDouble 2.0 basically replaces the File Info entry (ID = 7) with a File Dates entry (ID = 8) and one or more host file system entries, such as a Macintosh File Info entry (ID = 10), a ProDOS File Info entry (ID = 11), or an MS-DOS File Info entry (ID = 12). Information on these entries and AppleDouble 2.0 can be found in the AppleSingle/AppleDouble Formats for Foreign Files Developer's Note, available from APDA, AppleLink, and the Developer CD series.
This and all of the other Apple II Technical Notes have been converted to HTML by Aaron Heiss as a public service to the Apple II community, with permission by Apple Computer, Inc. Any and all trademarks, registered and otherwise, are properties of their owners.