| 1 |
'\" t |
| 2 |
.\" -*-nroff-*- |
| 3 |
.\" |
| 4 |
.\" Copyright (C) 2000 Thomas Roessler <[email protected]> |
| 5 |
.\" |
| 6 |
.\" This document is in the public domain and may be distributed and |
| 7 |
.\" changed arbitrarily. |
| 8 |
.\" |
| 9 |
.TH mbox 5 "February 19th, 2002" Unix "User Manuals" |
| 10 |
.\" |
| 11 |
.SH NAME |
| 12 |
mbox \- Format for mail message storage. |
| 13 |
.\" |
| 14 |
.SH DESCRIPTION |
| 15 |
This document describes the format traditionally used by Unix hosts |
| 16 |
to store mail messages locally. |
| 17 |
.B mbox |
| 18 |
files typically reside in the system's mail spool, under various |
| 19 |
names in users' Mail directories, and under the name |
| 20 |
.B mbox |
| 21 |
in users' home directories. |
| 22 |
.PP |
| 23 |
An |
| 24 |
.B mbox |
| 25 |
is a text file containing an arbitrary number of e-mail messages. |
| 26 |
Each message consists of a postmark, followed by an e-mail message |
| 27 |
formatted according to \fBRFC822\fP, \fBRFC2822\fP. The file format |
| 28 |
is line-oriented. Lines are separated by line feed characters (ASCII 10). |
| 29 |
.PP |
| 30 |
A postmark line consists of the four characters "From", followed by |
| 31 |
a space character, followed by the message's envelope sender |
| 32 |
address, followed by whitespace, and followed by a time stamp. This |
| 33 |
line is often called From_ line. |
| 34 |
.PP |
| 35 |
The sender address is expected to be |
| 36 |
.B addr-spec |
| 37 |
as defined in \fBRFC2822\fP 3.4.1. The date is expected to be |
| 38 |
.B date-time |
| 39 |
as output by |
| 40 |
.BR asctime (3). |
| 41 |
For compatibility reasons with legacy software, two-digit years |
| 42 |
greater than or equal to 70 should be interpreted as the years |
| 43 |
1970+, while two-digit years less than 70 should be interpreted as |
| 44 |
the years 2000-2069. Software reading files in this format should |
| 45 |
also be prepared to accept non-numeric timezone information such as |
| 46 |
"CET DST" for Central European Time, daylight saving time. |
| 47 |
.PP |
| 48 |
Example: |
| 49 |
.IP "" 1 |
| 50 |
>From [email protected] Fri Jun 23 02:56:55 2000 |
| 51 |
.PP |
| 52 |
In order to avoid misinterpretation of lines in message bodies |
| 53 |
which begin with the four characters "From", followed by a space |
| 54 |
character, the mail delivery agent must quote any occurrence |
| 55 |
of "From " at the start of a body line. |
| 56 |
.sp |
| 57 |
There are two different quoting schemes, the first (\fBMBOXO\fP) only |
| 58 |
quotes plain "From " lines in the body by prepending a '>' to the |
| 59 |
line; the second (\fBMBOXRD\fP) also quotes already quoted "From " |
| 60 |
lines by prepending a '>' (i.e. ">From ", ">>From ", ...). The later |
| 61 |
has the advantage that lines like |
| 62 |
.IP "" 1 |
| 63 |
>From the command line you can use the '\-p' option |
| 64 |
.PP |
| 65 |
aren't dequoted wrongly as a \fBMBOXRD\fP-MDA would turn the line |
| 66 |
into |
| 67 |
.IP "" 1 |
| 68 |
>>From the command line you can use the '\-p' option |
| 69 |
.PP |
| 70 |
before storing it. Besides \fBMBOXO\fP and \fBMBOXRD\fP there is also |
| 71 |
\fBMBOXCL\fP which is \fBMBOXO\fP with a "Content-Length:"\-field with the |
| 72 |
number of bytes in the message body; some MUAs (like |
| 73 |
.BR mutt (1)) |
| 74 |
do automatically transform \fBMBOXO\fP mailboxes into \fBMBOXCL\fP ones when |
| 75 |
ever they write them back as \fBMBOXCL\fP can be read by any \fBMBOXO\fP-MUA |
| 76 |
without any problems. |
| 77 |
.PP |
| 78 |
If the modification-time (usually determined via |
| 79 |
.BR stat (2)) |
| 80 |
of a nonempty |
| 81 |
.B mbox |
| 82 |
file is greater than the access-time the file has new mail. Many MUAs |
| 83 |
place a Status: header in each message to indicate which messages have |
| 84 |
already been read. |
| 85 |
.\" |
| 86 |
.SH LOCKING |
| 87 |
Since |
| 88 |
.B mbox |
| 89 |
files are frequently accessed by multiple programs in parallel, |
| 90 |
.B mbox |
| 91 |
files should generally not be accessed without locking. |
| 92 |
.PP |
| 93 |
Three different locking mechanisms (and combinations thereof) are in |
| 94 |
general use: |
| 95 |
.IP "\(bu" |
| 96 |
.BR fcntl (2) |
| 97 |
locking is mostly used on recent, POSIX-compliant systems. Use of |
| 98 |
this locking method is, in particular, advisable if |
| 99 |
.B mbox |
| 100 |
files are accessed through the Network File System (NFS), since it |
| 101 |
seems the only way to reliably invalidate NFS clients' caches. |
| 102 |
.IP "\(bu" |
| 103 |
.BR flock (2) |
| 104 |
locking is mostly used on BSD-based systems. |
| 105 |
.IP "\(bu" |
| 106 |
Dotlocking is used on all kinds of systems. In order to lock an |
| 107 |
.B mbox |
| 108 |
file named \fIfolder\fR, an application first creates a temporary file |
| 109 |
with a unique name in the directory in which the |
| 110 |
\fIfolder\fR resides. The application then tries to use the |
| 111 |
.BR link (2) |
| 112 |
system call to create a hard link named \fIfolder.lock\fR |
| 113 |
to the temporary file. The success of the |
| 114 |
.BR link (2) |
| 115 |
system call should be additionally verified using |
| 116 |
.BR stat (2) |
| 117 |
calls. If the link has succeeded, the mail folder is considered |
| 118 |
dotlocked. The temporary file can then safely be unlinked. |
| 119 |
.IP "" |
| 120 |
In order to release the lock, an application just unlinks the |
| 121 |
\fIfolder.lock\fR file. |
| 122 |
.PP |
| 123 |
If multiple methods are combined, implementors should make sure to |
| 124 |
use the non-blocking variants of the |
| 125 |
.BR fcntl (2) |
| 126 |
and |
| 127 |
.BR flock (2) |
| 128 |
system calls in order to avoid deadlocks. |
| 129 |
.PP |
| 130 |
If multiple methods are combined, an |
| 131 |
.B mbox |
| 132 |
file must not be considered to have been successfully locked before |
| 133 |
all individual locks were obtained. When one of the individual |
| 134 |
locking methods fails, an application should release all locks it |
| 135 |
acquired successfully, and restart the entire locking procedure from |
| 136 |
the beginning, after a suitable delay. |
| 137 |
.PP |
| 138 |
The locking mechanism used on a particular system is a matter of |
| 139 |
local policy, and should be consistently used by all applications |
| 140 |
installed on the system which access |
| 141 |
.B mbox |
| 142 |
files. Failure to do so may result in loss of e-mail data, and in |
| 143 |
corrupted |
| 144 |
.B mbox |
| 145 |
files. |
| 146 |
.\" |
| 147 |
.SH FILES |
| 148 |
.IR /var/spool/mail/$LOGNAME |
| 149 |
.RS |
| 150 |
\fB$LOGNAME\fP's incoming mail folder. |
| 151 |
.RE |
| 152 |
.PP |
| 153 |
.IR $HOME/mbox |
| 154 |
.RS |
| 155 |
user's archived mail messages, in his \fB$HOME\fP directory. |
| 156 |
.RE |
| 157 |
.PP |
| 158 |
.IR $HOME/Mail/ |
| 159 |
.RS |
| 160 |
A directory in user's \fB$HOME\fP directory which is commonly used to hold |
| 161 |
.B mbox |
| 162 |
format folders. |
| 163 |
.RE |
| 164 |
.PP |
| 165 |
.\" |
| 166 |
.SH "SEE ALSO" |
| 167 |
.BR mutt (1), |
| 168 |
.BR fcntl (2), |
| 169 |
.BR flock (2), |
| 170 |
.BR link (2), |
| 171 |
.BR stat (2), |
| 172 |
.BR asctime (3), |
| 173 |
.BR maildir (5), |
| 174 |
.BR mmdf (5), |
| 175 |
.BR RFC822 , |
| 176 |
.BR RFC976 , |
| 177 |
.BR RFC2822 |
| 178 |
.\" |
| 179 |
.SH AUTHOR |
| 180 |
Thomas Roessler <[email protected]>, Urs Janssen <[email protected]> |
| 181 |
.\" |
| 182 |
.SH HISTORY |
| 183 |
The |
| 184 |
.B mbox |
| 185 |
format occurred in Version 6 AT&T Unix. |
| 186 |
.br |
| 187 |
A variant of this format was documented in \fBRFC976\fP. |