RFC 1740
MIME Encapsulation of Macintosh Files - MacMIME
MIME Encapsulation of Macintosh files - MacMIME 🎀
Okay bestie, RFC 1740 is all about how to send Macintosh files through MIME email so Mac people get everything and everyone else gets the actual data. 🦋
- Network Working Group 🌸
- Number and title: RFC 1740, MIME Encapsulation of Macintosh files - MacMIME
- Authors: Patrik Faltstrom (Royal Institute of Technology), Dave Crocker (Brandenburg Consulting), and Erik E. Fair (Apple Computer Inc.)
- Category: Standards Track
- Date: December 1994
- Obsoletes and updates: the title block doesn't list either one 💅
Status of This Memo ✨
So this is an Internet standards track protocol, and they're literally asking the community for discussion and suggestions 💖 For the current standardization state and status, check the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited 🌈
Abstract 🦋
This memo explains the format you use when sending Apple Macintosh files via MIME [BORE93]. It's compatible with the existing ways people already distribute Macintosh files, and it also lets non-Macintosh systems access the data in standardized formats. It's giving compatibility and inclusivity 🫶
2. Introduction ✨
Okay so a Macintosh file is actually two pieces, called forks 🧚
- Data fork: the actual data in the file. On a non-Macintosh computer, this is usually the only part that's meaningful. Like, if a Mac user wants to send a data file to someone on an IBM-PC, she would only send the Data fork 💅
- Resource fork: holds a collection of arbitrary attribute/value pairs, like program segments, icon bitmaps, and parametric values 🔥
The Finder also stores extra info about Mac files in a hidden file called the "Desktop Database" 🙈
Storing the parts of a Mac file on a non-Macintosh filesystem is messy, since those filesystems only handle consecutive data in one part. So it's super common to convert the Mac file into some other format before sending it over the network 😭
The two styles of use are [APPL90]:
- AppleSingle: Apple's standard format for encoding Macintosh files as one byte stream.
- AppleDouble: Similar to AppleSingle, except the Data fork gets separated from the Macintosh-specific parts by the AppleDouble encoding.
AppleDouble is the preferred format for a Macintosh file going into an Internet mail message. Mac recipients get the entire thing, icons and other Mac-specific info included, while everyone else can easily pull out the Data fork, since it's been separated from the AppleDouble encoding. Main character energy 👑
2. MIME format for Apple/Macintosh-specific file information ✨
2a. APPLICATION/APPLEFILE 🍓
MIME type-name: APPLICATION
MIME subtype name: APPLEFILE
Required parameters: none
Optional parameters: NAME, which must be a "value" as
defined in RFC-1521 [BORE93].
Encoding considerations: The presence of binary data will
typically require use of
Content-Transfer-Encoding: BASE64
Security considerations: See separate section in the document
Published specification: Apple-single & Apple-double [APPL90]
Rationale: Permits MIME-based transmission of
data with Apple/Macintosh specific
information, while allowing general
access to non-specific user data.2b. MULTIPART/APPLEDOUBLE 🧚
MIME type-name: MULTIPART
MIME subtype name: APPLEDOUBLE
Required parameters: none
Optional parameters: NAME, which must be a "value" as
defined in RFC-1521 [BORE93].
Encoding considerations: none
Security considerations: See separate section in the document
Published specification: Apple-single & Apple-double [APPL90]
Rationale: Permits MIME-based transmission of
data with Apple/Macintosh specific
information, while allowing general
access to non-specific user data.2c. Detail specific to MIME-based usage 💖
Not every Macintosh document needs the special treatment. Documents with well-known MIME types and non-existent or trivial resource forks can go out as regular MIME body parts, no AppleSingle or AppleDouble required 🌸
Documents that lack a data fork must be sent as AppleSingle. ⭐
Unless there are strong reasons not to, everything else should normally be sent as AppleDouble. That covers documents with non-trivial resource forks, and documents without a matching well-known MIME type 🔥
It may be valuable in some cases to let the user pick one format over the other. Maybe they disagree with the implementor's idea of "trivial" resource forks, or they just have reasons of their own 🌈
Part 2 picks up with AppleSingle, and it's about to get so good 🧚✨ to be continued
Appendix A. The AppleSingle format 🎀
okay so the AppleSingle format is giving everything in one file 💅 Both forks of a Macintosh file, the Finder info, and an associated comment all sit together in a single file in the foreign file system. The structure is simple, which I love 🥹
An AppleSingle file is a header followed by one or more data entries. The header is a few fixed fields plus a list of entry descriptors, and each descriptor points to a data entry. Every entry is optional, so any given entry may or may not show up in the file ✨
AppleSingle file header
Field Length
Magic number 4 bytes
Version number 4 bytes
Filler 16 bytes
Number of entries 2 bytesEntry descriptor for each entry
Entry ID 4 bytes
Offset 4 bytes
Length 4 bytesBytes are ordered the MC68000 way, with the most significant byte first 🧠 The header fields follow the conventions in the sections below.
Magic number
This field is modelled after the UNIX magic number feature, and it tells you the file's format. Apple's magic number for AppleSingle is $00051600 or 0x00051600 🔥
Version number
This field tells you which version of the AppleSingle format is in use, in case the format evolves and more fields get added to the header. The version described here is $00020000 or 0x00020000 🌸
Filler
This field is all zeros: $00 or 0x00 🫶
Number of entries
This field says how many entries are in the file. It's an unsigned 16-bit number. If it's anything other than 0, that many entry descriptors come right after it 📋
Entry descriptors
Each entry descriptor is made of three fields:
- Entry ID: an unsigned 32-bit number that says what the entry is. Entry IDs run from 1 to
$FFFFFFFF, and Entry ID 0 is invalid 🙈 - Offset: an unsigned 32-bit number giving the offset from the beginning of the file to the start of the entry's data.
- Length: an unsigned 32-bit number giving the length of the data in bytes. The length can be 0.
Predefined entry IDs
Apple has a list of predefined entry IDs and their values:
Data Fork 1 Data fork
Resource Fork 2 Resource fork
Real Name 3 File's name as created on home file
system
Comment 4 Standard Macintosh comment
Icon, B&W 5 Standard Macintosh black and white icon
Icon, Colour 6 Macintosh colour icon
File Dates Info 8 File creation date, modification date,
and so on
Finder Info 9 Standard Macintosh Finder information
Macintosh File Info 10 Macintosh file information, attributes
and so on
ProDOS File Info 11 ProDOS file information, attributes and
so on
MS-DOS File Info 12 MS-DOS file information, attributes and
so on
Short Name 13 AFP short name
AFP File Info 14 AFP file, information, attributes and so
on
Directory ID 15 AFP directory IDApple reserves entry IDs 1 through $7FFFFFFF. The rest of the range is up for applications to define their own entries. Apple doesn't arbitrate how that rest of the range gets used 🦋
Appendix B. The AppleDouble format 🌈
AppleDouble splits things across two files 👯 The AppleDouble Data file holds the data fork, and the AppleDouble Header file holds the resource fork.
The AppleDouble Data file is just the standard Macintosh data fork, with no extra header. The AppleDouble Header file uses exactly the same format as an AppleSingle file, except it has no Data fork entry 💖
Here's the clever bit: the AppleDouble Header file has a different magic number from the AppleSingle one. That way, an application can tell right away whether it needs to look in another file for the data fork 🧚 The AppleDouble magic number is $00051607 or 0x00051607.
Entries in the AppleDouble Header file can show up in any order. That said, the resource fork gets extended the most (after the data fork), so Apple recommends putting the resource fork entry last in the file. The data fork is easy to extend anyway, since it lives all by itself in the AppleDouble Data file 🍓
Appendix C. applefile.h 🧚
This is an example C header file for parsing the data in either an AppleSingle file or an AppleDouble header ✨
The file is written by Lee Jones. Distribution is unlimited 🫶
/* applefile.h - Data structures used by AppleSingle/AppleDouble
* file format
*
* Written by Lee Jones, 22-Oct-1993
*
* For definitive information, see "AppleSingle/AppleDouble
* Formats for Foreign Files Developer's Note"; Apple Computer
* Inc.; (c) 1990.
*
* Other details were added from:
* Inside Macintosh [old version], volumes II to VI,
* Apple include files supplied with Think C 5.0.1,
* Microsoft MS-DOS Programmer's Reference, version 5, and
* Microsoft C 6.00a's dos.h include file.
*
* I don't have ProDOS or AFP Server documentation so related
* entries may be a bit skimpy.
*
* Edit history:
*
* when who why
* --------- --- ------------------------------------------
* 22-Oct-93 LMJ Pull together from Inside Macintosh,
* Developer's Note, etc
* 26-Oct-93 LMJ Finish writing first version and list
* references
* 06-Feb-94 EEF Very minor cleanup
*/
/* Following items define machine specific size (for porting). */
typedef char xchar8; /* 8-bit field */
typedef char schar8; /* signed 8-bit field */
typedef unsigned char uchar8; /* unsigned 8-bit field */
typedef short xint16; /* 16-bit field */
typedef unsigned short uint16; /* unsigned 16-bit field */
typedef long xint32; /* 32-bit field */
typedef long sint32; /* signed 32-bit field */
typedef unsigned long uint32; /* unsigned 32-bit field */
/* REMINDER: the Motorola 680x0 is a big-endian architecture! */
typedef uint32 OSType; /* 32 bit field */
/* In the QuickDraw coordinate plane, each coordinate is
* -32767..32767. Each point is at the intersection of a
* horizontal grid line and a vertical grid line. Horizontal
* coordinates increase from left to right. Vertical
* coordinates increase from top to bottom. This is the way
* both a TV screen and page of English text are scanned:
* from top left to bottom right.
*/
struct Point /* spot in QuickDraw 2-D grid */
{
xint16 v; /* vertical coordinate */
xint16 h; /* horizontal coordinate */
}; /* Point */
typedef struct Point Point;
/* See older Inside Macintosh, Volume II page 84 or Volume IV
* page 104.
*/
struct FInfo /* Finder information */
{
OSType fdType; /* File type, 4 ASCII chars */
OSType fdCreator; /* File's creator, 4 ASCII chars */
uint16 fdFlags; /* Finder flag bits */
Point fdLocation; /* file's location in folder */
xint16 fdFldr; /* file 's folder (aka window) */
}; /* FInfo */
typedef struct FInfo FInfo;
/*
* Masks for finder flag bits (field fdFlags in struct
* FInfo).
*/
#define F_fOnDesk 0x0001 /* file is on desktop (HFS only) */
#define F_maskColor 0x000E /* color coding (3 bits) */
/* 0x0010 /* reserved (System 7) */
#define F_fSwitchLaunch 0x0020 /* reserved (System 7) */
#define F_fShared 0x0040 /* appl available to multiple users */
#define F_fNoINITs 0x0080 /* file contains no INIT resources */
#define F_fBeenInited 0x0100 /* Finder has loaded bundle res. */
/* 0x0200 /* reserved (System 7) */
#define F_fCustomIcom 0x0400 /* file contains custom icon */
#define F_fStationary 0x0800 /* file is a stationary pad */
#define F_fNameLocked 0x1000 /* file can't be renamed by Finder */
#define F_fHasBundle 0x2000 /* file has a bundle */
#define F_fInvisible 0x4000 /* file's icon is invisible */
#define F_fAlias 0x8000 /* file is an alias file (System 7) */
/* See older Inside Macintosh, Volume IV, page 105.
*/
struct FXInfo /* Extended finder information */
{
xint16 fdIconID; /* icon ID number */
xint16 fdUnused[3]; /* spare */
schar8 fdScript; /* scrip flag and code */
schar8 fdXFlags; /* reserved */
xint16 fdComment; /* comment ID number */
xint32 fdPutAway; /* home directory ID */
}; /* FXInfo */
typedef struct FXInfo FXInfo;
/* Pieces used by AppleSingle & AppleDouble (defined later). */
struct ASHeader /* header portion of AppleSingle */
{
/* AppleSingle = 0x00051600; AppleDouble = 0x00051607 */
uint32 magicNum; /* internal file type tag */
uint32 versionNum; /* format version: 2 = 0x00020000 */
uchar8 filler[16]; /* filler, currently all bits 0 */
uint16 numEntries; /* number of entries which follow */
}; /* ASHeader */
typedef struct ASHeader ASHeader;
struct ASEntry /* one AppleSingle entry descriptor */
{
uint32 entryID; /* entry type: see list, 0 invalid */
uint32 entryOffset; /* offset, in octets, from beginning */
/* of file to this entry's data */
uint32 entryLength; /* length of data in octets */
}; /* ASEntry */
typedef struct ASEntry ASEntry;
/* Apple reserves the range of entry IDs from 1 to 0x7FFFFFFF.
* Entry ID 0 is invalid. The rest of the range is available
* for applications to define their own entry types. "Apple does
* not arbitrate the use of the rest of the range."
*/
#define AS_DATA 1 /* data fork */
#define AS_RESOURCE 2 /* resource fork */
#define AS_REALNAME 3 /* File's name on home file system */
#define AS_COMMENT 4 /* standard Mac comment */
#define AS_ICONBW 5 /* Mac black & white icon */
#define AS_ICONCOLOR 6 /* Mac color icon */
/* 7 /* not used */
#define AS_FILEDATES 8 /* file dates; create, modify, etc */
#define AS_FINDERINFO 9 /* Mac Finder info & extended info */
#define AS_MACINFO 10 /* Mac file info, attributes, etc */
#define AS_PRODOSINFO 11 /* Pro-DOS file info, attrib., etc */
#define AS_MSDOSINFO 12 /* MS-DOS file info, attributes, etc */
#define AS_AFPNAME 13 /* Short name on AFP server */
#define AS_AFPINFO 14 /* AFP file info, attrib., etc */
#define AS_AFPDIRID 15 /* AFP directory ID */Okay bestie, this is the cheat sheet 🧚 It's the C header that lays out every byte of the AppleSingle and AppleDouble formats, so the structs have to match exactly. Here's the entry matrix first, then each entry type in order 💖
/* matrix of entry types and their usage:
*
* Macintosh Pro-DOS MS-DOS AFP server
* --------- ------- ------ ----------
* 1 AS_DATA xxx xxx xxx xxx
* 2 AS_RESOURCE xxx xxx
* 3 AS_REALNAME xxx xxx xxx xxx
*
* 4 AS_COMMENT xxx
* 5 AS_ICONBW xxx
* 6 AS_ICONCOLOR xxx
*
* 8 AS_FILEDATES xxx xxx xxx xxx
* 9 AS_FINDERINFO xxx
* 10 AS_MACINFO xxx
*
* 11 AS_PRODOSINFO xxx
* 12 AS_MSDOSINFO xxx
*
* 13 AS_AFPNAME xxx
* 14 AS_AFPINFO xxx
* 15 AS_AFPDIRID xxx
*/
/* entry ID 1, data fork of file - arbitrary length octet string */
/* entry ID 2, resource fork - arbitrary length opaque octet string;
* as created and managed by Mac O.S. resoure manager
*/
/* entry ID 3, file's name as created on home file system - arbitrary
* length octet string; usually short, printable ASCII
*/
/* entry ID 4, standard Macintosh comment - arbitrary length octet
* string; printable ASCII, claimed 200 chars or less
*/
/* This is probably a simple duplicate of the 128 octet bitmap
* stored as the 'ICON' resource or the icon element from an 'ICN#'
* resource.
*/
struct ASIconBW /* entry ID 5, standard Mac black and white icon */
{
uint32 bitrow[32]; /* 32 rows of 32 1-bit pixels */
}; /* ASIconBW */
typedef struct ASIconBW ASIconBW;
/* entry ID 6, "standard" Macintosh color icon - several competing
* color icons are defined. Given the copyright dates
* of the Inside Macintosh volumes, the 'cicn' resource predominated
* when the AppleSingle Developer's Note was written (most probable
* candidate). See Inside Macintosh, Volume V, pages 64 & 80-81 for
* a description of 'cicn' resources.
*
* With System 7, Apple introduced icon families. They consist of:
* large (32x32) B&W icon, 1-bit/pixel, type 'ICN#',
* small (16x16) B&W icon, 1-bit/pixel, type 'ics#',
* large (32x32) color icon, 4-bits/pixel, type 'icl4',
* small (16x16) color icon, 4-bits/pixel, type 'ics4',
* large (32x32) color icon, 8-bits/pixel, type 'icl8', and
* small (16x16) color icon, 8-bits/pixel, type 'ics8'.
* If entry ID 6 is one of these, take your pick. See Inside
* Macintosh, Volume VI, pages 2-18 to 2-22 and 9-9 to 9-13, for
* descriptions.
*/
/* entry ID 7, not used */
/* Times are stored as a "signed number of seconds before of after
* 12:00 a.m. (midnight), January 1, 2000 Greenwich Mean Time (GMT).
* Applications must convert to their native date and time
* conventions." Any unknown entries are set to 0x80000000
* (earliest reasonable time).
*/
struct ASFileDates /* entry ID 8, file dates info */
{
sint32 create; /* file creation date/time */
sint32 modify; /* last modification date/time */
sint32 backup; /* last backup date/time */
sint32 access; /* last access date/time */
}; /* ASFileDates */
typedef struct ASFileDates ASFileDates;
/* See older Inside Macintosh, Volume II, page 115 for
* PBGetFileInfo(), and Volume IV, page 155, for PBGetCatInfo().
*/
/* entry ID 9, Macintosh Finder info & extended info */
struct ASFinderInfo
{
FInfo ioFlFndrInfo; /* PBGetFileInfo() or PBGetCatInfo() */
FXInfo ioFlXFndrInfo; /* PBGetCatInfo() (HFS only) */
}; /* ASFinderInfo */
typedef struct ASFinderInfo ASFinderInfo;
struct ASMacInfo /* entry ID 10, Macintosh file information */
{
uchar8 filler[3]; /* filler, currently all bits 0 */
uchar8 ioFlAttrib; /* PBGetFileInfo() or PBGetCatInfo() */
}; /* ASMacInfo */
typedef struct ASMacInfo ASMacInfo;
#define AS_PROTECTED 0x0002 /* protected bit */
#define AS_LOCKED 0x0001 /* locked bit */
/* NOTE: ProDOS-16 and GS/OS use entire fields. ProDOS-8 uses low
* order half of each item (low byte in access & filetype, low word
* in auxtype); remainder of each field should be zero filled.
*/
struct ASProdosInfo /* entry ID 11, ProDOS file information */
{
uint16 access; /* access word */
uint16 filetype; /* file type of original file */
uint32 auxtype; /* auxiliary type of the orig file */
}; /* ASProDosInfo */
typedef struct ASProdosInfo ASProdosInfo;
/* MS-DOS file attributes occupy 1 octet; since the Developer Note
* is unspecific, I've placed them in the low order portion of the
* field (based on example of other ASMacInfo & ASProdosInfo).
*/
struct ASMsdosInfo /* entry ID 12, MS-DOS file information */
{
uchar8 filler; /* filler, currently all bits 0 */
uchar8 attr; /* _dos_getfileattr(), MS-DOS */
/* interrupt 21h function 4300h */
}; /* ASMsdosInfo */
typedef struct ASMsdosInfo ASMsdosInfo;
#define AS_DOS_NORMAL 0x00 /* normal file (all bits clear) */
#define AS_DOS_READONLY 0x01 /* file is read-only */
#define AS_DOS_HIDDEN 0x02 /* hidden file (not shown by DIR) */
#define AS_DOS_SYSTEM 0x04 /* system file (not shown by DIR) */
#define AS_DOS_VOLID 0x08 /* volume label (only in root dir) */
#define AS_DOS_SUBDIR 0x10 /* file is a subdirectory */
#define AS_DOS_ARCHIVE 0x20 /* new or modified (needs backup) */
/* entry ID 13, short file name on AFP server - arbitrary length
* octet string; usualy printable ASCII starting with
* '!' (0x21)
*/
struct ASAfpInfo /* entry ID 12, AFP server file information */
{
uchar8 filler[3]; /* filler, currently all bits 0 */
uchar8 attr; /* file attributes */
}; /* ASAfpInfo */
typedef struct ASAfpInfo ASAfpInfo;
#define AS_AFP_Invisible 0x01 /* file is invisible */
#define AS_AFP_MultiUser 0x02 /* simultaneous access allowed */
#define AS_AFP_System 0x04 /* system file */
#define AS_AFP_BackupNeeded 0x40 /* new or modified (needs backup) */
struct ASAfpDirId /* entry ID 15, AFP server directory ID */
{
uint32 dirid; /* file's directory ID on AFP server */
}; /* ASAfpDirId */
typedef struct ASAfpDirId ASAfpDirId;
/*
* The format of an AppleSingle/AppleDouble header
*/
struct AppleSingle /* format of disk file */
{
ASHeader header; /* AppleSingle header part */
ASEntry entry[1]; /* array of entry descriptors */
/* uchar8 filedata[]; /* followed by rest of file */
}; /* AppleSingle */
typedef struct AppleSingle AppleSingle;
/*
* FINAL REMINDER: the Motorola 680x0 is a big-endian architecture!
*/
/* End of applefile.h */That's the whole header, bestie! 🌈 The big-endian reminder at the bottom is iconic, and the matrix up top is how you check which entry types each platform actually uses 🎀
📦 where this page comes from
- ietf: rfc1740 1994-12
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms