Commit | Line | Data |
---|---|---|
2117e02e MW |
1 | .TH maildir 5 |
2 | .SH "NAME" | |
3 | maildir \- directory for incoming mail messages | |
4 | .SH "INTRODUCTION" | |
5 | .I maildir | |
6 | is a structure for | |
7 | directories of incoming mail messages. | |
8 | It solves the reliability problems that plague | |
9 | .I mbox | |
10 | files and | |
11 | .I mh | |
12 | folders. | |
13 | .SH "RELIABILITY ISSUES" | |
14 | A machine may crash while it is delivering a message. | |
15 | For both | |
16 | .I mbox | |
17 | files and | |
18 | .I mh | |
19 | folders this means that the message will be silently truncated. | |
20 | Even worse: for | |
21 | .I mbox | |
22 | format, if the message is truncated in the middle of a line, | |
23 | it will be silently joined to the next message. | |
24 | The mail transport agent will try again later to deliver the message, | |
25 | but it is unacceptable that a corrupted message should show up at all. | |
26 | In | |
27 | .IR maildir , | |
28 | every message is guaranteed complete upon delivery. | |
29 | ||
30 | A machine may have two programs simultaneously delivering mail | |
31 | to the same user. | |
32 | The | |
33 | .I mbox | |
34 | and | |
35 | .I mh | |
36 | formats require the programs to update a single central file. | |
37 | If the programs do not use some locking mechanism, | |
38 | the central file will be corrupted. | |
39 | There are several | |
40 | .I mbox | |
41 | and | |
42 | .I mh | |
43 | locking mechanisms, | |
44 | none of which work portably and reliably. | |
45 | In contrast, in | |
46 | .IR maildir , | |
47 | no locks are ever necessary. | |
48 | Different delivery processes never touch the same file. | |
49 | ||
50 | A user may try to delete messages from his mailbox at the same | |
51 | moment that the machine delivers a new message. | |
52 | For | |
53 | .I mbox | |
54 | and | |
55 | .I mh | |
56 | formats, the user's mail-reading program must know | |
57 | what locking mechanism the mail-delivery programs use. | |
58 | In contrast, in | |
59 | .IR maildir , | |
60 | any delivered message | |
61 | can be safely updated or deleted by a mail-reading program. | |
62 | ||
63 | Many sites use Sun's | |
64 | .B Network F\fPa\fBil\fPur\fBe System | |
65 | (NFS), | |
66 | presumably because the operating system vendor does not offer | |
67 | anything else. | |
68 | NFS exacerbates all of the above problems. | |
69 | Some NFS implementations don't provide | |
70 | .B any | |
71 | reliable locking mechanism. | |
72 | With | |
73 | .I mbox | |
74 | and | |
75 | .I mh | |
76 | formats, | |
77 | if two machines deliver mail to the same user, | |
78 | or if a user reads mail anywhere except the delivery machine, | |
79 | the user's mail is at risk. | |
80 | .I maildir | |
81 | works without trouble over NFS. | |
82 | .SH "THE MAILDIR STRUCTURE" | |
83 | A directory in | |
84 | .I maildir | |
85 | format has three subdirectories, | |
86 | all on the same filesystem: | |
87 | .BR tmp , | |
88 | .BR new , | |
89 | and | |
90 | .BR cur . | |
91 | ||
92 | Each file in | |
93 | .B new | |
94 | is a newly delivered mail message. | |
95 | The modification time of the file is the delivery date of the message. | |
96 | The message is delivered | |
97 | .I without | |
98 | an extra UUCP-style | |
99 | .B From_ | |
100 | line, | |
101 | .I without | |
102 | any | |
103 | .B >From | |
104 | quoting, | |
105 | and | |
106 | .I without | |
107 | an extra blank line at the end. | |
108 | The message is normally in RFC 822 format, | |
109 | starting with a | |
110 | .B Return-Path | |
111 | line and a | |
112 | .B Delivered-To | |
113 | line, | |
114 | but it could contain arbitrary binary data. | |
115 | It might not even end with a newline. | |
116 | ||
117 | Files in | |
118 | .B cur | |
119 | are just like files in | |
120 | .BR new . | |
121 | The big difference is that files in | |
122 | .B cur | |
123 | are no longer new mail: | |
124 | they have been seen by the user's mail-reading program. | |
125 | .SH "HOW A MESSAGE IS DELIVERED" | |
126 | The | |
127 | .B tmp | |
128 | directory is used to ensure reliable delivery, | |
129 | as discussed here. | |
130 | ||
131 | A program delivers a mail message in six steps. | |
132 | First, it | |
133 | .B chdir()\fPs | |
134 | to the | |
135 | .I maildir | |
136 | directory. | |
137 | Second, it | |
138 | .B stat()s | |
139 | the name | |
140 | .BR tmp/\fItime.pid.host , | |
141 | where | |
142 | .I time | |
143 | is the number of seconds since the beginning of 1970 GMT, | |
144 | .I pid | |
145 | is the program's process ID, | |
146 | and | |
147 | .I host | |
148 | is the host name. | |
149 | Third, if | |
150 | .B stat() | |
151 | returned anything other than ENOENT, | |
152 | the program sleeps for two seconds, updates | |
153 | .IR time , | |
154 | and tries the | |
155 | .B stat() | |
156 | again, a limited number of times. | |
157 | Fourth, the program | |
158 | creates | |
159 | .BR tmp/\fItime.pid.host . | |
160 | Fifth, the program | |
161 | .I NFS-writes | |
162 | the message to the file. | |
163 | Sixth, the program | |
164 | .BR link() s | |
165 | the file to | |
166 | .BR new/\fItime.pid.host . | |
167 | At that instant the message has been successfully delivered. | |
168 | ||
169 | The delivery program is required to start a 24-hour timer before | |
170 | creating | |
171 | .BR tmp/\fItime.pid.host , | |
172 | and to abort the delivery | |
173 | if the timer expires. | |
174 | Upon error, timeout, or normal completion, | |
175 | the delivery program may attempt to | |
176 | .B unlink() | |
177 | .BR tmp/\fItime.pid.host . | |
178 | ||
179 | .I NFS-writing | |
180 | means | |
181 | (1) as usual, checking the number of bytes returned from each | |
182 | .B write() | |
183 | call; | |
184 | (2) calling | |
185 | .B fsync() | |
186 | and checking its return value; | |
187 | (3) calling | |
188 | .B close() | |
189 | and checking its return value. | |
190 | (Standard NFS implementations handle | |
191 | .B fsync() | |
192 | incorrectly | |
193 | but make up for it by abusing | |
194 | .BR close() .) | |
195 | .SH "HOW A MESSAGE IS READ" | |
196 | A mail reader operates as follows. | |
197 | ||
198 | It looks through the | |
199 | .B new | |
200 | directory for new messages. | |
201 | Say there is a new message, | |
202 | .BR new/\fIunique . | |
203 | The reader may freely display the contents of | |
204 | .BR new/\fIunique , | |
205 | delete | |
206 | .BR new/\fIunique , | |
207 | or rename | |
208 | .B new/\fIunique | |
209 | as | |
210 | .BR cur/\fIunique:info . | |
211 | See | |
212b6f5d | 212 | .B http://pobox.com/~djb/proto/maildir.html |
2117e02e MW |
213 | for the meaning of |
214 | .IR info . | |
215 | ||
216 | The reader is also expected to look through the | |
217 | .B tmp | |
218 | directory and to clean up any old files found there. | |
219 | A file in | |
220 | .B tmp | |
221 | may be safely removed if it | |
222 | has not been accessed in 36 hours. | |
223 | ||
224 | It is a good idea for readers to skip all filenames in | |
225 | .B new | |
226 | and | |
227 | .B cur | |
228 | starting with a dot. | |
229 | Other than this, readers should not attempt to parse filenames. | |
230 | .SH "ENVIRONMENT VARIABLES" | |
231 | Mail readers supporting | |
232 | .I maildir | |
233 | use the | |
234 | .B MAILDIR | |
235 | environment variable | |
236 | as the name of the user's primary mail directory. | |
237 | .SH "SEE ALSO" | |
238 | mbox(5), | |
239 | qmail-local(8) |