mdw@git.distorted.org.uk Git - qmail/blob - mbox.5

   1 .TH mbox 5
   2 .SH "NAME"
   3 mbox \- file containing mail messages
   4 .SH "INTRODUCTION"
   5 The most common format for storage of mail messages is
   6 .I mbox
   7 format.
   8 An
   9 .I mbox
  10 is a single file containing zero or more mail messages.
  11 .SH "MESSAGE FORMAT"
  12 A message encoded in
  13 .I mbox
  14 format begins with a
  15 .B From_
  16 line, continues with a series of
  17 .B \fRnon-\fBFrom_
  18 lines,
  19 and ends with a blank line.
  20 A
  21 .B From_
  22 line means any line that begins with the characters
  23 F, r, o, m, space:
  24
  25 .EX
  26      From god@heaven.af.mil Sat Jan  3 01:05:34 1996
  27 .br
  28      Return-Path: <god@heaven.af.mil>
  29 .br
  30      Delivered-To: djb@silverton.berkeley.edu
  31 .br
  32      Date: 3 Jan 1996 01:05:34 -0000
  33 .br
  34      From: God <god@heaven.af.mil>
  35 .br
  36      To: djb@silverton.berkeley.edu (D. J. Bernstein)
  37 .br
  38
  39 .br
  40      How's that mail system project coming along?
  41 .br
  42
  43 .EE
  44
  45 The final line is a completely blank line (no spaces or tabs).
  46 Notice that blank lines may also appear elsewhere in the message.
  47
  48 The
  49 .B From_
  50 line always looks like
  51 .B From
  52 .I envsender
  53 .I date
  54 .IR moreinfo .
  55 .I envsender
  56 is one word, without spaces or tabs;
  57 it is usually the envelope sender of the message.
  58 .I date
  59 is the delivery date of the message.
  60 It always contains exactly 24 characters in
  61 .B asctime
  62 format.
  63 .I moreinfo
  64 is optional; it may contain arbitrary information.
  65
  66 Between the
  67 .B From_
  68 line and the blank line is a message in RFC 822 format,
  69 as described in
  70 .BR qmail-header(5) ,
  71 subject to
  72 .B >From quoting
  73 as described below.
  74 .SH "HOW A MESSAGE IS DELIVERED"
  75 Here is how a program appends a message to an
  76 .I mbox
  77 file.
  78
  79 It first creates a
  80 .B From_
  81 line given the message's envelope sender and the current date.
  82 If the envelope sender is empty (i.e., if this is a bounce message),
  83 the program uses
  84 .B MAILER-DAEMON
  85 instead.
  86 If the envelope sender contains spaces, tabs, or newlines,
  87 the program replaces them with hyphens.
  88
  89 The program then copies the message, applying
  90 .B >From quoting
  91 to each line.
  92 .B >From quoting
  93 ensures that the resulting lines are not
  94 .B From_
  95 lines:
  96 the program prepends a
  97 .B >
  98 to any
  99 .B From_
 100 line,
 101 .B >From_
 102 line,
 103 .B >>From_
 104 line,
 105 .B >>>From_
 106 line,
 107 etc.
 108
 109 Finally the program appends a blank line to the message.
 110 If the last line of the message was a partial line,
 111 it writes two newlines;
 112 otherwise it writes one.
 113 .SH "HOW A MESSAGE IS READ"
 114 A reader scans through an
 115 .I mbox
 116 file looking for
 117 .B From_
 118 lines.
 119 Any
 120 .B From_
 121 line marks the beginning of a message.
 122 The reader should not attempt to take advantage of the fact that every
 123 .B From_
 124 line (past the beginning of the file)
 125 is preceded by a blank line.
 126
 127 Once the reader finds a message,
 128 it extracts a (possibly corrupted) envelope sender
 129 and delivery date out of the
 130 .B From_
 131 line.
 132 It then reads until the next
 133 .B From_
 134 line or end of file, whichever comes first.
 135 It strips off the final blank line
 136 and
 137 deletes the
 138 quoting of
 139 .B >From_
 140 lines and
 141 .B >>From_
 142 lines and so on.
 143 The result is an RFC 822 message.
 144 .SH "COMMON MBOX VARIANTS"
 145 There are many variants of
 146 .I mbox
 147 format.
 148 The variant described above is
 149 .I mboxrd
 150 format, popularized by Rahul Dhesi in June 1995.
 151
 152 The original
 153 .I mboxo
 154 format quotes only
 155 .B From_
 156 lines, not
 157 .B >From_
 158 lines.
 159 As a result it is impossible to tell whether
 160
 161 .EX
 162      From: djb@silverton.berkeley.edu (D. J. Bernstein)
 163 .br
 164      To: god@heaven.af.mil
 165 .br
 166
 167 .br
 168      >From now through August I'll be doing beta testing.
 169 .br
 170      Thanks for your interest.
 171 .EE
 172
 173 was quoted in the original message.
 174 An
 175 .I mboxrd
 176 reader will always strip off the quoting.
 177
 178 .I mboxcl
 179 format is like
 180 .I mboxo
 181 format, but includes a Content-Length field with the
 182 number of bytes in the message.
 183 .I mboxcl2
 184 format is like
 185 .I mboxcl
 186 but has no
 187 .B >From
 188 quoting.
 189 These formats are used by SVR4 mailers.
 190 .I mboxcl2
 191 cannot be read safely by
 192 .I mboxrd
 193 readers.
 194 .SH "UNSPECIFIED DETAILS"
 195 There are many locking mechanisms for
 196 .I mbox
 197 files.
 198 .B qmail-local
 199 always uses
 200 .B flock
 201 on systems that have it, otherwise
 202 .BR lockf .
 203
 204 The delivery date in a
 205 .B From_
 206 line does not specify a time zone.
 207 .B qmail-local
 208 always creates the delivery date in GMT
 209 so that
 210 .I mbox
 211 files can be safely transported from one time zone to another.
 212
 213 If the mtime on a nonempty
 214 .I mbox
 215 file is greater than the atime,
 216 the file has new mail.
 217 If the mtime is smaller than the atime,
 218 the new mail has been read.
 219 If the atime equals the mtime,
 220 there is no way to tell whether the file has new mail,
 221 since
 222 .B qmail-local
 223 takes much less than a second to run.
 224 One solution is for a mail reader to artificially set the
 225 atime to the mtime plus 1.
 226 Then the file has new mail if and only if the atime is
 227 less than or equal to the mtime.
 228
 229 Some mail readers place
 230 .B Status
 231 fields in each message to indicate which messages have been read.
 232 .SH "SEE ALSO"
 233 maildir(5),
 234 qmail-header(5),
 235 qmail-local(8)