maildir(5) maildir(5) NNAAMMEE maildir - directory for incoming mail messages IINNTTRROODDUUCCTTIIOONN _m_a_i_l_d_i_r is a structure for directories of incoming mail messages. It solves the reliability problems that plague _m_b_o_x files and _m_h folders. RREELLIIAABBIILLIITTYY IISSSSUUEESS A machine may crash while it is delivering a message. For both _m_b_o_x files and _m_h folders this means that the message will be silently trun- cated. Even worse: for _m_b_o_x 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 _m_a_i_l_d_i_r, every message is guaranteed complete upon delivery. A machine may have two programs simultaneously delivering mail to the same user. The _m_b_o_x and _m_h formats require the programs to update a single central file. If the programs do not use some locking mecha- nism, the central file will be corrupted. There are several _m_b_o_x and _m_h locking mechanisms, none of which work portably and reliably. In contrast, in _m_a_i_l_d_i_r, 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 _m_b_o_x and _m_h formats, the user’s mail-reading program must know what locking mechanism the mail- delivery programs use. In contrast, in _m_a_i_l_d_i_r, any delivered message can be safely updated or deleted by a mail-reading program. Many sites use Sun’s NNeettwwoorrkk FFaiilluree SSyysstteemm (NFS), presumably because the operating system vendor does not offer anything else. NFS exacer- bates all of the above problems. Some NFS implementations don’t pro- vide aannyy reliable locking mechanism. With _m_b_o_x and _m_h 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. _m_a_i_l_d_i_r works without trouble over NFS. TTHHEE MMAAIILLDDIIRR SSTTRRUUCCTTUURREE A directory in _m_a_i_l_d_i_r format has three subdirectories, all on the same filesystem: ttmmpp, nneeww, and ccuurr. Each file in nneeww is a newly delivered mail message. The modification time of the file is the delivery date of the message. The message is delivered _w_i_t_h_o_u_t an extra UUCP-style FFrroomm__ line, _w_i_t_h_o_u_t any >>FFrroomm quoting, and _w_i_t_h_o_u_t an extra blank line at the end. The message is normally in RFC 822 format, starting with a RReettuurrnn--PPaatthh line and a DDeelliivveerreedd--TToo line, but it could contain arbitrary binary data. It might not even end with a newline. Files in ccuurr are just like files in nneeww. The big difference is that files in ccuurr are no longer new mail: they have been seen by the user’s mail-reading program. HHOOWW AA MMEESSSSAAGGEE IISS DDEELLIIVVEERREEDD The ttmmpp directory is used to ensure reliable delivery, as discussed here. A program delivers a mail message in six steps. First, it cchhddiirr(())s to the _m_a_i_l_d_i_r directory. Second, it ssttaatt(())ss the name ttmmpp//_t_i_m_e_._p_i_d_._h_o_s_t, where _t_i_m_e is the number of seconds since the beginning of 1970 GMT, _p_i_d is the program’s process ID, and _h_o_s_t is the host name. Third, if ssttaatt(()) returned anything other than ENOENT, the program sleeps for two seconds, updates _t_i_m_e, and tries the ssttaatt(()) again, a limited number of times. Fourth, the program creates ttmmpp//_t_i_m_e_._p_i_d_._h_o_s_t. Fifth, the pro- gram _N_F_S_-_w_r_i_t_e_s the message to the file. Sixth, the program lliinnkk(())s the file to nneeww//_t_i_m_e_._p_i_d_._h_o_s_t. At that instant the message has been successfully delivered. The delivery program is required to start a 24-hour timer before creat- ing ttmmpp//_t_i_m_e_._p_i_d_._h_o_s_t, and to abort the delivery if the timer expires. Upon error, timeout, or normal completion, the delivery program may attempt to uunnlliinnkk(()) ttmmpp//_t_i_m_e_._p_i_d_._h_o_s_t. _N_F_S_-_w_r_i_t_i_n_g means (1) as usual, checking the number of bytes returned from each wwrriittee(()) call; (2) calling ffssyynncc(()) and checking its return value; (3) calling cclloossee(()) and checking its return value. (Standard NFS implementations handle ffssyynncc(()) incorrectly but make up for it by abusing cclloossee(()).) HHOOWW AA MMEESSSSAAGGEE IISS RREEAADD A mail reader operates as follows. It looks through the nneeww directory for new messages. Say there is a new message, nneeww//_u_n_i_q_u_e. The reader may freely display the contents of nneeww//_u_n_i_q_u_e, delete nneeww//_u_n_i_q_u_e, or rename nneeww//_u_n_i_q_u_e as ccuurr//_u_n_i_q_u_e_:_i_n_f_o. See hhttttpp::////ppoobbooxx..ccoomm//~~ddjjbb//pprroottoo//mmaaiillddiirr..hhttmmll for the meaning of _i_n_f_o. The reader is also expected to look through the ttmmpp directory and to clean up any old files found there. A file in ttmmpp 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 nneeww and ccuurr starting with a dot. Other than this, readers should not attempt to parse filenames. EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS Mail readers supporting _m_a_i_l_d_i_r use the MMAAIILLDDIIRR environment variable as the name of the user’s primary mail directory. SSEEEE AALLSSOO mbox(5), qmail-local(8) maildir(5)