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)