path: root/maildir.5
diff options
Diffstat (limited to 'maildir.5')
1 files changed, 239 insertions, 0 deletions
diff --git a/maildir.5 b/maildir.5
new file mode 100644
index 0000000..5da9573
--- /dev/null
+++ b/maildir.5
@@ -0,0 +1,239 @@
+.TH maildir 5
+maildir \- directory for incoming mail messages
+.I maildir
+is a structure for
+directories of incoming mail messages.
+It solves the reliability problems that plague
+.I mbox
+files and
+.I mh
+A machine may crash while it is delivering a message.
+For both
+.I mbox
+files and
+.I mh
+folders this means that the message will be silently truncated.
+Even worse: for
+.I mbox
+format, if the message is truncated in the middle of a line,
+it will be silently joined to the next message.
+The mail transport agent will try again later to deliver the message,
+but it is unacceptable that a corrupted message should show up at all.
+.IR maildir ,
+every message is guaranteed complete upon delivery.
+A machine may have two programs simultaneously delivering mail
+to the same user.
+.I mbox
+.I mh
+formats require the programs to update a single central file.
+If the programs do not use some locking mechanism,
+the central file will be corrupted.
+There are several
+.I mbox
+.I mh
+locking mechanisms,
+none of which work portably and reliably.
+In contrast, in
+.IR maildir ,
+no locks are ever necessary.
+Different delivery processes never touch the same file.
+A user may try to delete messages from his mailbox at the same
+moment that the machine delivers a new message.
+.I mbox
+.I mh
+formats, the user's mail-reading program must know
+what locking mechanism the mail-delivery programs use.
+In contrast, in
+.IR maildir ,
+any delivered message
+can be safely updated or deleted by a mail-reading program.
+Many sites use Sun's
+.B Network F\fPa\fBil\fPur\fBe System
+presumably because the operating system vendor does not offer
+anything else.
+NFS exacerbates all of the above problems.
+Some NFS implementations don't provide
+.B any
+reliable locking mechanism.
+.I mbox
+.I mh
+if two machines deliver mail to the same user,
+or if a user reads mail anywhere except the delivery machine,
+the user's mail is at risk.
+.I maildir
+works without trouble over NFS.
+A directory in
+.I maildir
+format has three subdirectories,
+all on the same filesystem:
+.BR tmp ,
+.BR new ,
+.BR cur .
+Each file in
+.B new
+is a newly delivered mail message.
+The modification time of the file is the delivery date of the message.
+The message is delivered
+.I without
+an extra UUCP-style
+.B From_
+.I without
+.B >From
+.I without
+an extra blank line at the end.
+The message is normally in RFC 822 format,
+starting with a
+.B Return-Path
+line and a
+.B Delivered-To
+but it could contain arbitrary binary data.
+It might not even end with a newline.
+Files in
+.B cur
+are just like files in
+.BR new .
+The big difference is that files in
+.B cur
+are no longer new mail:
+they have been seen by the user's mail-reading program.
+.B tmp
+directory is used to ensure reliable delivery,
+as discussed here.
+A program delivers a mail message in six steps.
+First, it
+.B chdir()\fPs
+to the
+.I maildir
+Second, it
+.B stat()s
+the name
+.BR tmp/\ ,
+.I time
+is the number of seconds since the beginning of 1970 GMT,
+.I pid
+is the program's process ID,
+.I host
+is the host name.
+Third, if
+.B stat()
+returned anything other than ENOENT,
+the program sleeps for two seconds, updates
+.IR time ,
+and tries the
+.B stat()
+again, a limited number of times.
+Fourth, the program
+.BR tmp/\ .
+Fifth, the program
+.I NFS-writes
+the message to the file.
+Sixth, the program
+.BR link() s
+the file to
+.BR new/\ .
+At that instant the message has been successfully delivered.
+The delivery program is required to start a 24-hour timer before
+.BR tmp/\ ,
+and to abort the delivery
+if the timer expires.
+Upon error, timeout, or normal completion,
+the delivery program may attempt to
+.B unlink()
+.BR tmp/\ .
+.I NFS-writing
+(1) as usual, checking the number of bytes returned from each
+.B write()
+(2) calling
+.B fsync()
+and checking its return value;
+(3) calling
+.B close()
+and checking its return value.
+(Standard NFS implementations handle
+.B fsync()
+but make up for it by abusing
+.BR close() .)
+A mail reader operates as follows.
+It looks through the
+.B new
+directory for new messages.
+Say there is a new message,
+.BR new/\fIunique .
+The reader may freely display the contents of
+.BR new/\fIunique ,
+.BR new/\fIunique ,
+or rename
+.B new/\fIunique
+.BR cur/\fIunique:info .
+for the meaning of
+.IR info .
+The reader is also expected to look through the
+.B tmp
+directory and to clean up any old files found there.
+A file in
+.B tmp
+may be safely removed if it
+has not been accessed in 36 hours.
+It is a good idea for readers to skip all filenames in
+.B new
+.B cur
+starting with a dot.
+Other than this, readers should not attempt to parse filenames.
+Mail readers supporting
+.I maildir
+use the
+environment variable
+as the name of the user's primary mail directory.