| 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 |
| 212 | .B http://pobox.com/~djb/proto/maildir.html |
| 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) |