240 lines
5.1 KiB
Plaintext
240 lines
5.1 KiB
Plaintext
.TH 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)
|