1 files changed, 239 insertions, 0 deletions
diff --git a/man/maildir.5 b/man/maildir.5
new file mode 100644
index 0000000..49b2b23
--- /dev/null
+++ b/man/maildir.5
@@ -0,0 +1,239 @@
+.TH s/qmail: maildir 5
+.SH "NAME"
+maildir \- directory for incoming mail messages
+.SH "INTRODUCTION"
+.I maildir
+is a structure for
+directories of incoming mail messages.
+It solves the reliability problems that plague
+.I mbox
+files and
+.I mh
+folders.
+.SH "RELIABILITY ISSUES"
+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.
+In
+.IR maildir ,
+every message is guaranteed complete upon delivery.
+
+A machine may have two programs simultaneously delivering mail
+to the same user.
+The
+.I mbox
+and
+.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
+and
+.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.
+For
+.I mbox
+and
+.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
+(NFS),
+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.
+With 
+.I mbox
+and
+.I mh
+formats,
+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.
+.SH "THE MAILDIR STRUCTURE"
+A directory in
+.I maildir
+format has three subdirectories,
+all on the same filesystem:
+.BR tmp ,
+.BR new ,
+and
+.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_
+line,
+.I without
+any
+.B >From
+quoting,
+and
+.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
+line,
+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.
+.SH "HOW A MESSAGE IS DELIVERED"
+The
+.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
+directory.
+Second, it 
+.B stat()s
+the name
+.BR tmp/\fItime.pid.host ,
+where
+.I time
+is the number of seconds since the beginning of 1970 GMT,
+.I pid
+is the program's process ID,
+and
+.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
+creates
+.BR tmp/\fItime.pid.host .
+Fifth, the program
+.I NFS-writes
+the message to the file.
+Sixth, the program
+.BR link() s
+the file to
+.BR new/\fItime.pid.host .
+At that instant the message has been successfully delivered.
+
+The delivery program is required to start a 24-hour timer before
+creating
+.BR tmp/\fItime.pid.host ,
+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/\fItime.pid.host .
+
+.I NFS-writing
+means
+(1) as usual, checking the number of bytes returned from each
+.B write()
+call;
+(2) calling
+.B fsync()
+and checking its return value;
+(3) calling
+.B close()
+and checking its return value.
+(Standard NFS implementations handle
+.B fsync()
+incorrectly
+but make up for it by abusing
+.BR close() .)
+.SH "HOW A MESSAGE IS READ"
+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 ,
+delete
+.BR new/\fIunique ,
+or rename
+.B new/\fIunique
+as
+.BR cur/\fIunique:info .
+See
+.B http://pobox.com/~djb/proto/maildir.html
+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
+and
+.B cur
+starting with a dot.
+Other than this, readers should not attempt to parse filenames.
+.SH "ENVIRONMENT VARIABLES"
+Mail readers supporting
+.I maildir
+use the
+.B MAILDIR
+environment variable
+as the name of the user's primary mail directory.
+.SH "SEE ALSO"
+mbox(5),
+qmail-local(8)