Manual Reference Pages - MAILDIR (5)
maildir - directory for incoming mail messages
maildir is a structure for
directories of incoming mail messages.
It solves the reliability problems that plague
mbox files and
A machine may crash while it is delivering a message.
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.
maildir, every message is guaranteed complete upon delivery.
A machine may have two programs simultaneously delivering mail
to the same user.
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
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.
mh formats, the users 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 Suns
Network Failure System (NFS),
presumably because the operating system vendor does not offer
NFS exacerbates all of the above problems.
Some NFS implementations dont provide
any reliable locking mechanism.
if two machines deliver mail to the same user,
or if a user reads mail anywhere except the delivery machine,
the users 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:
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
without an extra blank line at the end.
The message is normally in RFC 822 format,
starting with a
Return-Path line and a
but it could contain arbitrary binary data.
It might not even end with a newline.
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 users mail-reading program.
HOW A MESSAGE IS DELIVERED
tmp directory is used to ensure reliable delivery,
as discussed here.
A program delivers a mail message in six steps.
chdir()s to the
stat()s the name
time is the number of seconds since the beginning of 1970 GMT,
pid is the programs process ID,
host is the host name.
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
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
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
(1) as usual, checking the number of bytes returned from each
fsync() and checking its return value;
close() and checking its return value.
(Standard NFS implementations handle
but make up for it by abusing
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, or rename
http://pobox.com/~djb/proto/maildir.html for the meaning of
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
cur starting with a dot.
Other than this, readers should not attempt to parse filenames.
Mail readers supporting
maildir use the
MAILDIR environment variable
as the name of the users primary mail directory.
Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.