maildir(5)                                                      File Formats Manual                                                     maildir(5)

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 fold-
       ers.

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 mes-
       sage.  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  exac-
       erbates  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)