maildir(5)         Headers, Tables, and Macros         maildir(5)



NAME
     maildir - directory for incoming mail messages

INTRODUCTION
     maildir is a structure for directories of incoming mail mes-
     sages.   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  mechan-
     isms,  none  of  which  work portably and reliably.  In con-
     trast, 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),  presum-
     ably because the operating system vendor does not offer any-
     thing 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 any-
     where 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



SunOS 5.5                 Last change:                          1






maildir(5)         Headers, Tables, and Macros         maildir(5)



     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 pro-
     cess 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  mes-
     sage  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  com-
     pletion,  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/maildir.html for the meaning of info.

     The reader is also expected to look through the  tmp  direc-
     tory  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.




SunOS 5.5                 Last change:                          2






maildir(5)         Headers, Tables, and Macros         maildir(5)



     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)













































SunOS 5.5                 Last change:                          3