| Current File : //var/qmail/man/cat5/maildir.0 |
Standards, Environments, and Macros maildir(5)
NNNNAAAAMMMMEEEE
maildir - directory for incoming mail messages
IIIINNNNTTTTRRRROOOODDDDUUUUCCCCTTTTIIIIOOOONNNN
_m_a_i_l_d_i_r is a structure for directories of incoming mail mes-
sages. It solves the reliability problems that plague _m_b_o_x
files and _m_h folders.
RRRREEEELLLLIIIIAAAABBBBIIIILLLLIIIITTTTYYYY IIIISSSSSSSSUUUUEEEESSSS
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 truncated. 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 mechanism, the central file will be
corrupted. There are several _m_b_o_x and _m_h locking mechan-
isms, none of which work portably and reliably. In con-
trast, 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 NNNNeeeettttwwwwoooorrrrkkkk FFFFaiiiillllureeee SSSSyyyysssstttteeeemmmm (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 aaaannnnyyyy 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.
TTTTHHHHEEEE MMMMAAAAIIIILLLLDDDDIIIIRRRR SSSSTTTTRRRRUUUUCCCCTTTTUUUURRRREEEE
A directory in _m_a_i_l_d_i_r format has three subdirectories, all
on the same filesystem: ttttmmmmpppp, nnnneeeewwww, and ccccuuuurrrr.
Each file in nnnneeeewwww 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 FFFFrrrroooommmm____ line, _w_i_t_h_o_u_t any >>>>FFFFrrrroooommmm quoting, and _w_i_t_h_o_u_t an
SunOS 5.11 Last change: 1
Standards, Environments, and Macros maildir(5)
extra blank line at the end. The message is normally in RFC
822 format, starting with a RRRReeeettttuuuurrrrnnnn----PPPPaaaatttthhhh line and a
DDDDeeeelllliiiivvvveeeerrrreeeedddd----TTTToooo line, but it could contain arbitrary binary
data. It might not even end with a newline.
Files in ccccuuuurrrr are just like files in nnnneeeewwww. The big difference
is that files in ccccuuuurrrr are no longer new mail: they have been
seen by the user's mail-reading program.
HHHHOOOOWWWW AAAA MMMMEEEESSSSSSSSAAAAGGGGEEEE IIIISSSS DDDDEEEELLLLIIIIVVVVEEEERRRREEEEDDDD
The ttttmmmmpppp directory is used to ensure reliable delivery, as
discussed here.
A program delivers a mail message in six steps. First, it
cccchhhhddddiiiirrrr(((())))s to the _m_a_i_l_d_i_r directory. Second, it ssssttttaaaatttt(((())))ssss the
name ttttmmmmpppp////_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 pro-
cess ID, and _h_o_s_t is the host name. Third, if ssssttttaaaatttt(((())))
returned anything other than ENOENT, the program sleeps for
two seconds, updates _t_i_m_e, and tries the ssssttttaaaatttt(((()))) again, a
limited number of times. Fourth, the program creates
ttttmmmmpppp////_t_i_m_e._p_i_d._h_o_s_t. Fifth, the program _N_F_S-_w_r_i_t_e_s the mes-
sage to the file. Sixth, the program lllliiiinnnnkkkk(((())))s the file to
nnnneeeewwww////_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 creating ttttmmmmpppp////_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 com-
pletion, the delivery program may attempt to uuuunnnnlllliiiinnnnkkkk(((())))
ttttmmmmpppp////_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 wwwwrrrriiiitttteeee(((()))) call; (2) calling ffffssssyyyynnnncccc(((()))) and
checking its return value; (3) calling cccclllloooosssseeee(((()))) and checking
its return value. (Standard NFS implementations handle
ffffssssyyyynnnncccc(((()))) incorrectly but make up for it by abusing cccclllloooosssseeee(((()))).)
HHHHOOOOWWWW AAAA MMMMEEEESSSSSSSSAAAAGGGGEEEE IIIISSSS RRRREEEEAAAADDDD
A mail reader operates as follows.
It looks through the nnnneeeewwww directory for new messages. Say
there is a new message, nnnneeeewwww////_u_n_i_q_u_e. The reader may freely
display the contents of nnnneeeewwww////_u_n_i_q_u_e, delete nnnneeeewwww////_u_n_i_q_u_e, or
rename nnnneeeewwww////_u_n_i_q_u_e as ccccuuuurrrr////_u_n_i_q_u_e:_i_n_f_o. See
hhhhttttttttpppp::::////////ppppoooobbbbooooxxxx....ccccoooommmm////~~~~ddddjjjjbbbb////pppprrrroooottttoooo////mmmmaaaaiiiillllddddiiiirrrr....hhhhttttmmmmllll for the meaning of
_i_n_f_o.
The reader is also expected to look through the ttttmmmmpppp direc-
tory and to clean up any old files found there. A file in
ttttmmmmpppp may be safely removed if it has not been accessed in 36
hours.
SunOS 5.11 Last change: 2
Standards, Environments, and Macros maildir(5)
It is a good idea for readers to skip all filenames in nnnneeeewwww
and ccccuuuurrrr starting with a dot. Other than this, readers
should not attempt to parse filenames.
EEEENNNNVVVVIIIIRRRROOOONNNNMMMMEEEENNNNTTTT VVVVAAAARRRRIIIIAAAABBBBLLLLEEEESSSS
Mail readers supporting _m_a_i_l_d_i_r use the MMMMAAAAIIIILLLLDDDDIIIIRRRR environment
variable as the name of the user's primary mail directory.
SSSSEEEEEEEE AAAALLLLSSSSOOOO
mbox(5), qmail-local(8)
SunOS 5.11 Last change: 3