Provided by: qmail_1.06-4_i386 bug

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)

                                                                    maildir(5)