mdw@git.distorted.org.uk Git - qmail/blob - maildir.5

   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)