--- name: "maildir" section: "5" platform: "linux" package: "qmail" version: "1.06-6.2~deb10u1" release: "Debian 10 (Buster)" platforms: ["linux"] url: "https://new.carta.tech/maildir" --- # maildir(5) directory for incoming mail messages ## 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)](/mbox/5.md), [qmail-local(8)](/qmail-local/8.md)