maildir.5 (5178B)
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 https://cr.yp.to/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)