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)