diff options
Diffstat (limited to 'sqmail-4.3.07/man/maildir.5')
| -rw-r--r-- | sqmail-4.3.07/man/maildir.5 | 239 |
1 files changed, 239 insertions, 0 deletions
diff --git a/sqmail-4.3.07/man/maildir.5 b/sqmail-4.3.07/man/maildir.5 new file mode 100644 index 0000000..49b2b23 --- /dev/null +++ b/sqmail-4.3.07/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) |