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)