doc/mbox.man

   1 '\" t
   2 .\" -*-nroff-*-
   3 .\"
   4 .\"     Copyright (C) 2000 Thomas Roessler <roessler@does-not-exist.org>
   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 example@example.com 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 <roessler@does-not-exist.org>, Urs Janssen <urs@tin.org>
 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.