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 ...
  46 .br
  47 ^A^A^A^A
  48 .br
  49 ^A^A^A^A
  50 .br
  51 From: example@example.com
  52 .br
  53 To: example@example.org
  54 .br
  55 Subject: test 2
  56 .br
  57 .sp
  58 .br
  59 bar
  60 .br
  61 ^A^A^A^A
  62 .fi
  63 .RE
  64 .PP
  65 In contrast to most other single file mailbox formats like
  66 MBOXO and MBOXRD (see
  67 .BR mbox (5))
  68 there is no need to quote/dequote "From "-lines in
  69 .B MMDF
  70 mailboxes as such lines have no special meaning in this format.
  71 .PP
  72 If the modification-time (usually determined via
  73 .BR stat (2))
  74 of a nonempty mailbox file is greater than the access-time
  75 the file has new mail. Many MUAs place a Status: header in
  76 each message to indicate which messages have already been
  77 read.
  78 .\"
  79 .SH LOCKING
  80 Since
  81 .B MMDF
  82 files are frequently accessed by multiple programs in parallel,
  83 .B MMDF
  84 files should generally not be accessed without locking.
  85 .PP
  86 Three different locking mechanisms (and combinations thereof) are in
  87 general use:
  88 .IP "\(bu"
  89 .BR fcntl (2)
  90 locking is mostly used on recent, POSIX-compliant systems. Use of
  91 this locking method is, in particular, advisable if
  92 .B MMDF
  93 files are accessed through the Network File System (NFS), since it
  94 seems the only way to reliably invalidate NFS clients' caches.
  95 .IP "\(bu"
  96 .BR flock (2)
  97 locking is mostly used on BSD-based systems.
  98 .IP "\(bu"
  99 Dotlocking is used on all kinds of systems. In order to lock an
 100 .B MMDF
 101 file named \fIfolder\fR, an application first creates a temporary file
 102 with a unique name in the directory in which the
 103 \fIfolder\fR resides. The application then tries to use the
 104 .BR link (2)
 105 system call to create a hard link named \fIfolder.lock\fR
 106 to the temporary file. The success of the
 107 .BR link (2)
 108 system call should be additionally verified using
 109 .BR stat (2)
 110 calls. If the link has succeeded, the mail folder is considered
 111 dotlocked. The temporary file can then safely be unlinked.
 112 .IP ""
 113 In order to release the lock, an application just unlinks the
 114 \fIfolder.lock\fR file.
 115 .PP
 116 If multiple methods are combined, implementors should make sure to
 117 use the non-blocking variants of the
 118 .BR fcntl (2)
 119 and
 120 .BR flock (2)
 121 system calls in order to avoid deadlocks.
 122 .PP
 123 If multiple methods are combined, an
 124 .B MMDF
 125 file must not be considered to have been successfully locked before
 126 all individual locks were obtained. When one of the individual
 127 locking methods fails, an application should release all locks it
 128 acquired successfully, and restart the entire locking procedure from
 129 the beginning, after a suitable delay.
 130 .PP
 131 The locking mechanism used on a particular system is a matter of
 132 local policy, and should be consistently used by all applications
 133 installed on the system which access
 134 .B MMDF
 135 files. Failure to do so may result in loss of e-mail data, and in
 136 corrupted
 137 .B MMDF
 138 files.
 139 .\"
 140 .\" .SH FILES
 141 .\" /usr/spool/mmdf/lock/home
 142 .\" $HOME/Mail/
 143 .\"
 144 .\" .SH SECURITY
 145 .\"
 146 .SH "CONFORMING TO"
 147 .B MMDF
 148 is not part of any currently supported standard.
 149 .\"
 150 .SH HISTORY
 151 .B MMDF
 152 was developed at the University of Delaware by Dave Crocker.
 153 .\"
 154 .SH "SEE ALSO"
 155 .BR scomail (1),
 156 .BR fcntl (2),
 157 .BR flock (2),
 158 .BR link (2),
 159 .BR stat (2),
 160 .BR mbox (5),
 161 .BR RFC822 ,
 162 .BR RFC2822
 163
 164 .SH AUTHOR
 165 Urs Janssen <urs@tin.org>