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)