24-Aug-87 13:38:41-PDT,14289;000000000001 Return-Path: Received: from sdcsvax.UCSD.EDU by SUMEX-AIM.STANFORD.EDU with TCP; Mon, 24 Aug 87 13:37:48 PDT Received: by sdcsvax.UCSD.EDU (5.57/5.0) id AA13723 for info-mac@sumex-aim.stanford.edu; Mon, 24 Aug 87 12:35:53 PST To: comp-sys-mac-digest Path: sdcsvax!jww From: jww@sdcsvax.ucsd.edu (Joel West) Newsgroups: comp.sys.mac.digest Subject: Remote Macintosh file representation Message-Id: <3712@sdcsvax.UCSD.EDU> Date: 24 Aug 87 20:35:51 GMT Organization: Palomar Software, Inc., Vista, CA Lines: 300 For those of you who don't normally follow the INFO-APPLETALK newsgroup, Apple has made an important proposal that affects all Macintosh programs in hetereogeneous computing environments. A copy of the proposal is being included for the INFO-MAC archives. Apple proposes two file formats, AppleSingle and AppleDouble, which represent a file on another file system (e.g. UNIX or MS-DOS) as either one file, or two files, respectively. In the two-file mode, the data fork is in a separate file that should be locally readable. Further comments should be sent to INFO-APPLETALK@ANDREW.CMU.EDU. If you want to be added to the mailing list, of course, send mail to INFO-APPLETALK-REQUEST@ANDREW.CMU.EDU. Joel West Palomar Software, Inc., P.O. Box 2635, Vista, CA 92083 ihnp4!crash!palomar!joel joel@palomar.cts.com (Dwayne: you might archive this as APPLEDOUBLE.TXT) From andrews@apple.UUCP Sat Aug 22 15:36:51 1987 Path: sdcsvax!ames!aurora!labrea!decwrl!nsc!voder!apple!andrews From: andrews@apple.UUCP (Richard Andrews) Newsgroups: comp.protocols.appletalk Subject: Mac File Representation Message-ID: <1587@apple.UUCP> Date: 22 Aug 87 22:36:51 GMT Reply-To: andrews@apple.UUCP (Richard Andrews) Distribution: usa Organization: Apple Computer Inc., Cupertino, USA Lines: 265 Here is our first attempt at a proposal for representing Mac files on other file systems. Please circulate it freely. I welcome comments and suggestions, with the following caveat: PLEASE KEEP YOUR COMMENTS BRIEF AND CONCISE. I EXPECT A LOT OF FEEDBACK AND I CAN'T POSSIBLY WADE THROUGH A WHOLE LOT OF MATERIAL. I CANNOT REPLY TO EVERYONE PERSONALLY. Please send useful comments and suggestions directly to me. Look to this bulletin board for further drafts. -------------------------------------------------------------------- AppleSingle and AppleDouble formats for file representation A Draft Proposal from Apple Computer, Inc. 21 August, 1987 Apple Computer is proposing two standards for representing Macintosh files on non-Macintosh file systems, with the goal of preserving all attributes characteristic of Macintosh files (Finder info, icons, comments) on file systems that do not support such attributes ("foriegn" file systems). Experience seemed to indicate that a single format could not be devised that would be adequate for all cases, but that with two closely-related formats most needs could be served. A secondary goal in designing these formats was to make them general enough so that they could be used to represent a file from any file system on any other file system. Note that this is a draft and is subject to change. The two formats are called AppleSingle and AppleDouble. In AppleSingle format, all contents and attributes of a Macintosh file are kept in a single file on the foriegn file system. Both forks, Finder info, icons, etc. are arranged in a single file with a simple structure. This format is intended to be used primarily as a storage format; i.e., for those cases in which the Macintosh file must be stored on a foriegn file system and later reconstructed into a true Macintosh file. For those applications in which the users of the foriegn file system wish to access and perhaps modify the contents of the Macintosh file, AppleDouble format would be more appropriate. Since most Macintosh applications keep the file "data" in the data fork, AppleDouble format saves the contents of the data fork in a separate foriegn file. All other file attributes are kept in another file. Specifically, Apple's proposal does not rule out the possibility of building applications that wish to access and modify MacSingle-format files. Nor does it preclude using AppleDouble format for simple storage of Macintosh files. We merely present them as alternatives. The only assumption we have made is that each file system on which these file formats will be supported allows the creation of a simple file; an uninterpreted stream of bytes. We have ruled out designing a format that relied on the creation of subdirectories, since some file systems do not support them. Before getting into the discussion of the formats, some terms will be defined. The term home file system will be used to mean the file system for which the file's contents were created. A Unix application could create an AppleSingle file that holds a resource and data fork in which is contained a MacWrite-formatted document. The home file system for such a file will be Macintosh Hierarchical File System (HFS). In most cases, where a file is created and used on the same file system, the home file system will be that system. An AppleSingle or AppleDouble file is usually another representation of the file's contents on a foriegn file system. AppleSingle An AppleSingle file contains a header followed by data. The header is composed of several fixed fields and a list of entry descriptors, each pointing to an "entry". Standard entries that Apple will define include: Data Fork, Resource Fork, Real Name (name in the home file system), Comment, Icon, File Info, etc. Each entry would be optional and may or may not appear in the file. Header: Magic Number (4 bytes) Version Number (2 bytes) Home File System (4 bytes, ASCII encoded) Number of entries (2 bytes) / Entry ID (2 bytes) for each entry: | Offset (4 bytes) \ Length (4 bytes) The "Magic Number" field is modeled after the feature in Unix. It is intended to be used in whatever way each foriegn file system desires to distinguish this file as one in AppleSingle format. The Magic Number for AppleSingle format is $00051600 or 0x00051600. The "Version Number" field is used to denote the version of AppleSingle format in case the format evolves (perhaps more fields would be added to the header). The version described here is version $0001 or 0x1. The "Home File System" is explained above. For Macintosh files, the value of this field is 'mac ' or $6D616320 or 6D616320. Others are shown below: Macintosh 'mac ' or $6D616320 or 0x6D616320 ProDOS 'pdos' or $70646F73 or 0x70646F73 MS-DOS 'mdos' or $6D646F73 or 0x6D646F73. Unix 'unix' or $756E6978 or 0x756E6978. We welcome suggestions for other file systems that should be included in this list. The "Number of entries" field tells how many different entries are included in the file. It is an unsigned 16-bit number, and may be zero. If non-zero, then that number of entry descriptors will immediately follow this field. For each entry, the entry descriptor indicates just what the entry is, where the entry is located in the file, and how big the entry is. Apple will define a set of Entry IDs and their values: Data Fork 1 (standard Mac Data Fork) Resource Fork 2 (standard Mac Resource Fork) Real Name 3 (the file's name in the home file system) Comment 4 (standard Mac comment) Icon, B&W 5 (standard Mac Black & White Icon) Icon, Color 6 (standard Mac color icon) File Info 7 (file information) Dates 8 (Create, Modification, and Backup dates) Apple reserves the range of Entry IDs from 0 to 32767 ($7FFF or 0x7FFF) for future use. Apple will not arbitrate the use of the rest of the range; these values can be used by other systems to define their own types of entries. The File Info entry will be different for each home file system. For Macintosh HFS, the entry is 32 bytes long and consists of the standard Finder Info and Extended Finder Info fields. [To be defined: formats for MS-DOS, Unix, and ProDOS, etc.] Icon entries will probably not appear in most files since they are typically stored as a bundle in the application file's resource fork. The actual data representing the entry must be in a single contiguous block. It is pointed to by the offset field, which is an unsigned 32-bit number indicating the byte offset from the start of the file to the start of the entry. The entry length is also an unsigned 32-bit number representing the length in bytes. The length may be zero. After some number of entry descriptors, the actual entry data would appear. The entries could appear in any order, but since the data fork is the entry that would be most commonly extended, Apple strongly recommends that the data fork entry always be kept last in the file to facilitate its extension. It is possible to have holes in the file (unused space between entries). To find where the holes are, one must take the list of entry descriptors and sort them into increasing offset order. If the offset field of an entry is greater that the offset plus length of the previous entry, then a hole exists between the entries. This may be used to one's advantage; for example: if a file's comment is 10 bytes long, one 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 AppleSingle file may contain holes, every entry must be found by getting its offset from its entry descriptor - not by assuming that it begins after the previous entry. Byte ordering in the file will follow 68xxx convention. This is somewhat of a religious issue, but it was decided that picking one format was better than adding a flag to the file to indicate which ordering was being used, so that applications wouldn't have to have code to handle both cases. AppleDouble AppleDouble format is now easily described: it is the same as AppleSingle format except that the data fork is kept in a separate foriegn file. The file containing the data fork will be called the AppleDouble Data File, and the other file will be called the AppleDouble Header File. The AppleDouble Data File consists of just the standard Macintosh Data Fork with no extra header at all. The AppleDouble Header File has exactly the same format as the AppleSingle file, except that it does not contain a data fork entry. The Magic Number of an AppleDouble Header File differs from that of an AppleSingle file so that applications can tell whether or not they need to look elsewhere for the data fork. The Magic Number for AppleDouble format is $00051607 or 0x00051607. The entries in the Header File could appear in any order, but since the resource fork (in this case) is the entry that would be most commonly extended, Apple strongly recommends that the resource fork entry always be kept last in the file to facilitate its extension. The data fork is easily extended since it resides by itself in the Data File. If it is possible on the foriegn file system, one could create a new type of entry that "pointed" to the AppleDouble Data File to make it easy to find. ----------------------- AppleSingle format specifically will not include an algorithm for generating the AppleSingle file name from the "real" Macintosh name. This was done because the foriegn file systems of interest differ quite a bit in the area of file name syntax, and since the file's real name can be kept as an entry within the AppleSingle file. The same is true for AppleDouble Data File names, yet we would like to propose a standard for deriving the AppleDouble Header File name from the AppleDouble Data File name. Again, due to differing file name syntax, a standard per foriegn file system is proposed. For example: On Unix systems, take the file's real name and by character substitution, deletion, or truncation, derive an AppleDouble Data File name that is at least one character less than the maximum file name length. The AppleDouble Header File name will be the same as the AppleDouble Data File name with a preceding percent sign '%'. On ProDOS systems, take the file's real name and by character substitution, deletion, or truncation, derive an AppleDouble Data File name that is at least two characters less than the maximum file name length. The AppleDouble Header File name will be the same as the AppleDouble Data File name with a preceding 'R.' (ASCII-R, period). On MS-DOS systems, take the file's real name and by character substitution, deletion, or truncation, derive a name that is at most eight characters long. The AppleDouble Header File name will be the derived name plus an extension of '.ADF' (AppleDouble File). The AppleDouble Data File name will be the derived name plus whatever extension is most appropriate in the MS-DOS world. If the data fork is pure text (CR, LF) the the Data File extension would be '.TXT'. If the data fork conformed to some other standard MS-DOS file format, it would be given the appropriate extension. This would have to be decided by whatever application created the AppleDouble files. And so on. AppleDouble name derivations, to coin a term, would be defined for all the file systems of interest. This would allow applications running on the foriegn file system (and human users as well) to easily see which files are AppleDouble pairs. Knowledgeable users, if they know the derivation, could even rename the files in such a way so as to preserve the connection between the two. There is no way to prevent one file of the pair from being inconsistently renamed, moved or deleted.