Start

1 files changed, 109 insertions, 0 deletions

diff --git a/doc/doc-misc/Ext-maildir b/doc/doc-misc/Ext-maildir
new file mode 100644
index 000000000..b523dee4a
--- /dev/null
+++ b/doc/doc-misc/Ext-maildir
@@ -0,0 +1,109 @@
+The following information is from the maildir man page of qmail.
+
+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  mes-
+       sage,  but  it  is  unacceptable  that a corrupted message
+       should show up at all.  In maildir, every message is guar-
+       anteed 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 pro-
+       grams 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.  Dif-
+       ferent 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), presum-
+       ably 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  lock-
+       ing  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  differ-
+       ence  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 sec-
+       onds 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 mes-
+       sage 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 deliv-
+       ery 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/maildir.html   for  the  meaning  of
+       info.
+
+       The reader is also expected to look through the tmp direc-
+       tory 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.
+###