.TH maildir 5.SH "NAME"maildir \- directory for incoming mail messages.SH "INTRODUCTION".I maildiris a structure fordirectories of incoming mail messages.It solves the reliability problems that plague.I mboxfiles and.I mhfolders..SH "RELIABILITY ISSUES"A machine may crash while it is delivering a message.For both.I mboxfiles and.I mhfolders this means that the message will be silently truncated.Even worse: for.I mboxformat, 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.IR maildir ,every message is guaranteed complete upon delivery.A machine may have two programs simultaneously delivering mailto the same user.The.I mboxand.I mhformats 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.I mboxand.I mhlocking mechanisms,none of which work portably and reliably.In contrast, in.IR 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 samemoment that the machine delivers a new message.For.I mboxand.I mhformats, the user's mail-reading program must knowwhat locking mechanism the mail-delivery programs use.In contrast, in.IR maildir ,any delivered messagecan be safely updated or deleted by a mail-reading program.Many sites use Sun's .B Network F\fPa\fBil\fPur\fBe System(NFS),presumably because the operating system vendor does not offeranything else.NFS exacerbates all of the above problems.Some NFS implementations don't provide.B anyreliable locking mechanism.With .I mboxand.I mhformats,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..I maildirworks without trouble over NFS..SH "THE MAILDIR STRUCTURE"A directory in.I maildirformat has three subdirectories,all on the same filesystem:.BR tmp ,.BR new ,and.BR cur .Each file in.B newis a newly delivered mail message.The modification time of the file is the delivery date of the message.The message is delivered.I withoutan extra UUCP-style.B From_line,.I withoutany.B >Fromquoting,and.I withoutan extra blank line at the end.The message is normally in RFC 822 format,starting with a.B Return-Pathline and a.B Delivered-Toline,but it could contain arbitrary binary data.It might not even end with a newline.Files in.B curare just like files in.BR new .The big difference is that files in.B curare no longer new mail:they have been seen by the user's mail-reading program..SH "HOW A MESSAGE IS DELIVERED"The.B tmpdirectory is used to ensure reliable delivery,as discussed here.A program delivers a mail message in six steps.First, it.B chdir()\fPsto the.I maildirdirectory.Second, it .B stat()sthe name.BR tmp/\fItime.pid.host ,where.I timeis the number of seconds since the beginning of 1970 GMT,.I pidis the program's process ID,and.I hostis the host name.Third, if.B stat()returned anything other than ENOENT,the program sleeps for two seconds, updates.IR time ,and tries the.B stat()again, a limited number of times.Fourth, the programcreates.BR tmp/\fItime.pid.host .Fifth, the program.I NFS-writesthe message to the file.Sixth, the program.BR link() sthe file to.BR new/\fItime.pid.host .At that instant the message has been successfully delivered.The delivery program is required to start a 24-hour timer beforecreating.BR tmp/\fItime.pid.host ,and to abort the deliveryif the timer expires.Upon error, timeout, or normal completion,the delivery program may attempt to.B unlink().BR tmp/\fItime.pid.host ..I NFS-writingmeans(1) as usual, checking the number of bytes returned from each.B write()call;(2) calling.B fsync()and checking its return value;(3) calling.B close()and checking its return value.(Standard NFS implementations handle.B fsync()incorrectlybut make up for it by abusing.BR close() .).SH "HOW A MESSAGE IS READ"A mail reader operates as follows.It looks through the.B newdirectory for new messages.Say there is a new message,.BR new/\fIunique .The reader may freely display the contents of.BR new/\fIunique ,delete.BR new/\fIunique ,or rename.B new/\fIuniqueas.BR cur/\fIunique:info .See.B http://pobox.com/~djb/proto/maildir.htmlfor the meaning of.IR info .The reader is also expected to look through the.B tmpdirectory and to clean up any old files found there.A file in.B tmpmay be safely removed if ithas not been accessed in 36 hours.It is a good idea for readers to skip all filenames in.B newand.B curstarting with a dot.Other than this, readers should not attempt to parse filenames..SH "ENVIRONMENT VARIABLES"Mail readers supporting.I maildiruse the.B MAILDIRenvironment variableas the name of the user's primary mail directory..SH "SEE ALSO"mbox(5),qmail-local(8)