Provided by:
qmail_1.06-4_i386 
NAME
maildir - directory for incoming mail messages
INTRODUCTION
maildir is a structure for directories of incoming mail messages. It
solves the reliability problems that plague mbox files and mh folders.
RELIABILITY ISSUES
A machine may crash while it is delivering a message. For both mbox
files and mh folders this means that the message will be silently
truncated. Even worse: for 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 maildir, every message is guaranteed complete upon delivery.
A machine may have two programs simultaneously delivering mail to the
same user. The mbox and 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 mbox
and mh locking mechanisms, none of which work portably and reliably.
In contrast, in 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 mbox and mh formats, the
user's mail-reading program must know what locking mechanism the mail-
delivery programs use. In contrast, in maildir, any delivered message
can be safely updated or deleted by a mail-reading program.
Many sites use Sun's Network Failure 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 any reliable locking mechanism. With mbox and 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.
maildir works without trouble over NFS.
THE MAILDIR STRUCTURE
A directory in maildir format has three subdirectories, all on the same
filesystem: tmp, new, and cur.
Each file in new is a newly delivered mail message. The modification
time of the file is the delivery date of the message. The message is
delivered without an extra UUCP-style From_ line, without any >From
quoting, and without an extra blank line at the end. The message is
normally in RFC 822 format, starting with a Return-Path line and a
Delivered-To line, but it could contain arbitrary binary data. It
might not even end with a newline.
Files in cur are just like files in new. The big difference is that
files in cur are no longer new mail: they have been seen by the user's
mail-reading program.
HOW A MESSAGE IS DELIVERED
The tmp directory is used to ensure reliable delivery, as discussed
here.
A program delivers a mail message in six steps. First, it chdir()s to
the maildir directory. Second, it stat()s the name tmp/time.pid.host,
where time is the number of seconds since the beginning of 1970 GMT,
pid is the program's process ID, and host is the host name. Third, if
stat() returned anything other than ENOENT, the program sleeps for two
seconds, updates time, and tries the stat() again, a limited number of
times. Fourth, the program creates tmp/time.pid.host. Fifth, the
program NFS-writes the message to the file. Sixth, the program link()s
the file to new/time.pid.host. At that instant the message has been
successfully delivered.
The delivery program is required to start a 24-hour timer before
creating tmp/time.pid.host, and to abort the delivery if the timer
expires. Upon error, timeout, or normal completion, the delivery
program may attempt to unlink() tmp/time.pid.host.
NFS-writing means (1) as usual, checking the number of bytes returned
from each write() call; (2) calling fsync() and checking its return
value; (3) calling close() and checking its return value. (Standard
NFS implementations handle fsync() incorrectly but make up for it by
abusing close().)
HOW A MESSAGE IS READ
A mail reader operates as follows.
It looks through the new directory for new messages. Say there is a
new message, new/unique. The reader may freely display the contents of
new/unique, delete new/unique, or rename new/unique as cur/unique:info.
See http://pobox.com/~djb/proto/maildir.html for the meaning of info.
The reader is also expected to look through the tmp directory and to
clean up any old files found there. A file in 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 new and cur
starting with a dot. Other than this, readers should not attempt to
parse filenames.
ENVIRONMENT VARIABLES
Mail readers supporting maildir use the MAILDIR environment variable as
the name of the user's primary mail directory.
SEE ALSO
mbox(5), qmail-local(8)
maildir(5)