doc/mmdf.man

   1 .\" Project   : tin
   2 .\" Module    : mmdf.5
   3 .\" Author    : U. Janssen
   4 .\" Created   : 2002-02-18
   5 .\" Updated   :
   6 .\" Notes     : needs a lot of work
   7 .\"
   8 .TH mmdf 5 "February 18th, 2002" "Unix" "User Manuals"
   9 .\"
  10 .SH NAME
  11 MMDF \- Multi\-channel Memorandum Distribution Facility mailbox format
  12 .\"
  13 .SH DESCRIPTION
  14 This document describes the
  15 .B MMDF
  16 mailbox format used by some MTAs and MUAs (i.e.
  17 .BR scomail (1))
  18 to store mail messages locally.
  19 .PP
  20 An
  21 .B MMDF
  22 mailbox is a text file containing an arbitrary number of e-mail messages.
  23 Each message consists of a postmark, followed by an e-mail message formatted
  24 according to \fBRFC822\fP / \fBRFC2822\fP, followed by a postmark. The file
  25 format is line-oriented. Lines are separated by line feed characters (ASCII
  26 10). A postmark line consists of the four characters "^A^A^A^A" (Control-A;
  27 ASCII 1).
  28 .TP
  29 Example of a \fBMMDF\fP mailbox holding two mails:
  30 .RS
  31 .nf
  32 .sp
  33 ^A^A^A^A
  34 .br
  35 From: example@example.com
  36 .br
  37 To: example@example.org
  38 .br
  39 Subject: test
  40 .br
  41 .sp
  42 .br
  43 >From what I learned about the MMDF-format:
  44 .br
  45 .br
  46 ^A^A^A^A
  47 .br
  48 ^A^A^A^A
  49 .br
  50 From: example@example.com
  51 .br
  52 To: example@example.org
  53 .br
  54 Subject: test 2
  55 .br
  56 .sp
  57 .br
  58 bar
  59 .br
  60 ^A^A^A^A
  61 .fi
  62 .RE
  63 .PP
  64 In contrast to most other single file mailbox formats like
  65 MBOXO and MBOXRD (see
  66 .BR mbox (5))
  67 there is no need to quote/dequote "From "\-lines in
  68 .B MMDF
  69 mailboxes as such lines have no special meaning in this format.
  70 .PP
  71 If the modification-time (usually determined via
  72 .BR stat (2))
  73 of a nonempty mailbox file is greater than the access-time
  74 the file has new mail. Many MUAs place a Status: header in
  75 each message to indicate which messages have already been
  76 read.
  77 .\"
  78 .SH LOCKING
  79 Since
  80 .B MMDF
  81 files are frequently accessed by multiple programs in parallel,
  82 .B MMDF
  83 files should generally not be accessed without locking.
  84 .PP
  85 Three different locking mechanisms (and combinations thereof) are in
  86 general use:
  87 .IP "\(bu"
  88 .BR fcntl (2)
  89 locking is mostly used on recent, POSIX-compliant systems. Use of
  90 this locking method is, in particular, advisable if
  91 .B MMDF
  92 files are accessed through the Network File System (NFS), since it
  93 seems the only way to reliably invalidate NFS clients' caches.
  94 .IP "\(bu"
  95 .BR flock (2)
  96 locking is mostly used on BSD-based systems.
  97 .IP "\(bu"
  98 Dotlocking is used on all kinds of systems. In order to lock an
  99 .B MMDF
 100 file named \fIfolder\fR, an application first creates a temporary file
 101 with a unique name in the directory in which the
 102 \fIfolder\fR resides. The application then tries to use the
 103 .BR link (2)
 104 system call to create a hard link named \fIfolder.lock\fR
 105 to the temporary file. The success of the
 106 .BR link (2)
 107 system call should be additionally verified using
 108 .BR stat (2)
 109 calls. If the link has succeeded, the mail folder is considered
 110 dotlocked. The temporary file can then safely be unlinked.
 111 .IP ""
 112 In order to release the lock, an application just unlinks the
 113 \fIfolder.lock\fR file.
 114 .PP
 115 If multiple methods are combined, implementors should make sure to
 116 use the non-blocking variants of the
 117 .BR fcntl (2)
 118 and
 119 .BR flock (2)
 120 system calls in order to avoid deadlocks.
 121 .PP
 122 If multiple methods are combined, an
 123 .B MMDF
 124 file must not be considered to have been successfully locked before
 125 all individual locks were obtained. When one of the individual
 126 locking methods fails, an application should release all locks it
 127 acquired successfully, and restart the entire locking procedure from
 128 the beginning, after a suitable delay.
 129 .PP
 130 The locking mechanism used on a particular system is a matter of
 131 local policy, and should be consistently used by all applications
 132 installed on the system which access
 133 .B MMDF
 134 files. Failure to do so may result in loss of e-mail data, and in
 135 corrupted
 136 .B MMDF
 137 files.
 138 .\"
 139 .\" .SH FILES
 140 .\" /usr/spool/mmdf/lock/home
 141 .\" $HOME/Mail/
 142 .\"
 143 .\" .SH SECURITY
 144 .\"
 145 .SH "CONFORMING TO"
 146 .B MMDF
 147 is not part of any currently supported standard.
 148 .\"
 149 .SH HISTORY
 150 .B MMDF
 151 was developed at the University of Delaware by Dave Crocker.
 152 .\"
 153 .SH "SEE ALSO"
 154 .BR scomail (1),
 155 .BR fcntl (2),
 156 .BR flock (2),
 157 .BR link (2),
 158 .BR stat (2),
 159 .BR mbox (5),
 160 .BR RFC822 ,
 161 .BR RFC2822
 162
 163 .SH AUTHOR
 164 Urs Janssen <urs@tin.org>