Commit | Line | Data |
---|---|---|
e05f33e0 PH |
1 | The following information is from the maildir man page of qmail. |
2 | ||
3 | INTRODUCTION | |
4 | maildir is a structure for directories of incoming mail | |
5 | messages. It solves the reliability problems that plague | |
6 | mbox files and mh folders. | |
7 | ||
8 | RELIABILITY ISSUES | |
9 | A machine may crash while it is delivering a message. For | |
10 | both mbox files and mh folders this means that the message | |
11 | will be silently truncated. Even worse: for mbox format, | |
12 | if the message is truncated in the middle of a line, it | |
13 | will be silently joined to the next message. The mail | |
14 | transport agent will try again later to deliver the mes- | |
15 | sage, but it is unacceptable that a corrupted message | |
16 | should show up at all. In maildir, every message is guar- | |
17 | anteed complete upon delivery. | |
18 | ||
19 | A machine may have two programs simultaneously delivering | |
20 | mail to the same user. The mbox and mh formats require | |
21 | the programs to update a single central file. If the pro- | |
22 | grams do not use some locking mechanism, the central file | |
23 | will be corrupted. There are several mbox and mh locking | |
24 | mechanisms, none of which work portably and reliably. In | |
25 | contrast, in maildir, no locks are ever necessary. Dif- | |
26 | ferent delivery processes never touch the same file. | |
27 | ||
28 | A user may try to delete messages from his mailbox at the | |
29 | same moment that the machine delivers a new message. For | |
30 | mbox and mh formats, the user's mail-reading program must | |
31 | know what locking mechanism the mail-delivery programs | |
32 | use. In contrast, in maildir, any delivered message can | |
33 | be safely updated or deleted by a mail-reading program. | |
34 | ||
35 | Many sites use Sun's Network Failure System (NFS), presum- | |
36 | ably because the operating system vendor does not offer | |
37 | anything else. NFS exacerbates all of the above problems. | |
38 | Some NFS implementations don't provide any reliable lock- | |
39 | ing mechanism. With mbox and mh formats, if two machines | |
40 | deliver mail to the same user, or if a user reads mail | |
41 | anywhere except the delivery machine, the user's mail is | |
42 | at risk. maildir works without trouble over NFS. | |
43 | ||
44 | THE MAILDIR STRUCTURE | |
45 | A directory in maildir format has three subdirectories, | |
46 | all on the same filesystem: tmp, new, and cur. | |
47 | ||
48 | Each file in new is a newly delivered mail message. The | |
49 | modification time of the file is the delivery date of the | |
50 | message. The message is delivered without an extra UUCP- | |
51 | style From_ line, without any >From quoting, and without | |
52 | an extra blank line at the end. The message is normally | |
53 | in RFC 822 format, starting with a Return-Path line and a | |
54 | Delivered-To line, but it could contain arbitrary binary | |
55 | data. It might not even end with a newline. | |
56 | ||
57 | Files in cur are just like files in new. The big differ- | |
58 | ence is that files in cur are no longer new mail: they | |
59 | have been seen by the user's mail-reading program. | |
60 | ||
61 | HOW A MESSAGE IS DELIVERED | |
62 | The tmp directory is used to ensure reliable delivery, as | |
63 | discussed here. | |
64 | ||
65 | A program delivers a mail message in six steps. First, it | |
66 | chdir()s to the maildir directory. Second, it stat()s the | |
67 | name tmp/time.pid.host, where time is the number of sec- | |
68 | onds since the beginning of 1970 GMT, pid is the program's | |
69 | process ID, and host is the host name. Third, if stat() | |
70 | returned anything other than ENOENT, the program sleeps | |
71 | for two seconds, updates time, and tries the stat() again, | |
72 | a limited number of times. Fourth, the program creates | |
73 | tmp/time.pid.host. Fifth, the program NFS-writes the mes- | |
74 | sage to the file. Sixth, the program link()s the file to | |
75 | new/time.pid.host. At that instant the message has been | |
76 | successfully delivered. | |
77 | ||
78 | The delivery program is required to start a 24-hour timer | |
79 | before creating tmp/time.pid.host, and to abort the deliv- | |
80 | ery if the timer expires. Upon error, timeout, or normal | |
81 | completion, the delivery program may attempt to unlink() | |
82 | tmp/time.pid.host. | |
83 | ||
84 | NFS-writing means (1) as usual, checking the number of | |
85 | bytes returned from each write() call; (2) calling fsync() | |
86 | and checking its return value; (3) calling close() and | |
87 | checking its return value. (Standard NFS implementations | |
88 | handle fsync() incorrectly but make up for it by abusing | |
89 | close().) | |
90 | ||
91 | HOW A MESSAGE IS READ | |
92 | A mail reader operates as follows. | |
93 | ||
94 | It looks through the new directory for new messages. Say | |
95 | there is a new message, new/unique. The reader may freely | |
96 | display the contents of new/unique, delete new/unique, or | |
97 | rename new/unique as cur/unique:info. See | |
98 | http://pobox.com/~djb/maildir.html for the meaning of | |
99 | info. | |
100 | ||
101 | The reader is also expected to look through the tmp direc- | |
102 | tory and to clean up any old files found there. A file in | |
103 | tmp may be safely removed if it has not been accessed in | |
104 | 36 hours. | |
105 | ||
106 | It is a good idea for readers to skip all filenames in new | |
107 | and cur starting with a dot. Other than this, readers | |
108 | should not attempt to parse filenames. | |
109 | ### |