Archives/meli
2
0
Fork 0
mirror of https://git.meli.delivery/meli/meli synced 2024-11-17 03:26:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add historical-manpages dir

Browse Source 
Add some old manpages that may be of interest to users:

- maildir (5)
- mbox (5)
- mbox (5qmail)
- qmail-maildir (5)

Under meli/docs/historical-manpages/

Signed-off-by: Manos Pitsidianakis <manos@pitsidianak.is>
This commit is contained in:
Manos Pitsidianakis 2024-04-11 21:19:15 +03:00
parent ae96038fbf
commit c5e9e67604
No known key found for this signature in database
GPG Key ID: 7729C7707F7E09D0
4 changed files with 1015 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

354
meli/docs/historical-manpages/maildir.5.en.gz Normal file
View File

@ -0,0 +1,354 @@
'\" t
.\"<!-- Copyright 1998 - 2007 Double Precision, Inc. See COPYING for -->
.\"<!-- distribution information. -->
.\" Title: maildir
.\" Author: Sam Varshavchik
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\" Date: 07/24/2017
.\" Manual: Double Precision, Inc.
.\" Source: Courier Mail Server
.\" Language: English
.\"
.TH "MAILDIR" "5" "07/24/2017" "Courier Mail Server" "Double Precision, Inc\&."
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
maildir \- E\-mail directory
.SH "SYNOPSIS"
.sp
$HOME/Maildir
.SH "DESCRIPTION"
.PP
A
\(lqMaildir\(rq
is a structured directory that holds E\-mail messages\&. Maildirs were first implemented by the
Qmail
mail server\&. Qmail\*(Aqs maildirs were a simple data structure, nothing more than a single collection of E\-mail messages\&. The
Courier
mail server builds upon
Qmail\*(Aqs maildirs to provide extended functionality, such as folders and quotas\&. This document describes the
Courier
mail server\*(Aqs extended maildirs, without explicitly identifying The
Courier
mail server\-specific extensions\&. See
\fBmaildir\fR(5)
in Qmail\*(Aqs documentation for the original definition of maildirs\&.
.PP
Traditionally, E\-mail folders were saved as plain text files, called
\(lqmboxes\(rq\&. Mboxes have known limitations\&. Only one application can use an mbox at the same time\&. Locking is required in order to allow simultaneous concurrent access by different applications\&. Locking is often problematic, and not very reliable in network\-based filesystem requirements\&. Some network\-based filesystems don\*(Aqt offer any reliable locking mechanism at all\&. Furthermore, even bulletproof locking won\*(Aqt prevent occasional mbox corruption\&. A process can be killed or terminated in the middle of updating an mbox\&. This will likely result in corruption, and a loss of most messages in the mbox\&.
.PP
Maildirs allow multiple concurrent access by different applications\&. Maildirs do not require locking\&. Multiple applications can update a maildir at the same time, without stepping on each other\*(Aqs feet\&.
.SS "Maildir contents"
.PP
A
\(lqmaildir\(rq
is a directory that\*(Aqs created by
\m[blue]\fB\fBmaildirmake\fR(1)\fR\m[]\&\s-2\u[1]\d\s+2\&. Naturally, maildirs should not have any group or world permissions, unless you want other people to read your mail\&. A maildir contains three subdirectories:
tmp,
new, and
cur\&. These three subdirectories comprise the primary folder, where new mail is delivered by the system\&.
.PP
Folders are additional subdirectories in the maildir whose names begin with a period: such as
\&.Drafts
or
\&.Sent\&. Each folder itself contains the same three subdirectories,
tmp,
new, and
cur, and an additional zero\-length file named
maildirfolder, whose purpose is to inform any mail delivery agent that it\*(Aqs really delivering to a folder, and that the mail delivery agent should look in the parent directory for any maildir\-related information\&.
.PP
Folders are not physically nested\&. A folder subdirectory, such as
\&.Sent
does not itself contain any subfolders\&. The main maildir contains a single, flat list of subfolders\&. These folders are logically nested, and periods serve to separate folder hierarchies\&. For example,
\&.Sent\&.2002
is considered to be a subfolder called
\(lq2002\(rq
which is a subfolder of
\(lqSent\(rq\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBFolder name encoding\fR
.RS 4
.PP
Folder names can contain any Unicode character, except for control characters\&. US\-ASCII characters, U+0x0020 \- U+0x007F, except for the period, forward\-slash, and ampersand characters (U+0x002E, U+0x002F, and U+0x0026) represent themselves\&. The ampersand is represent by the two character sequence
\(lq&\-\(rq\&. The period, forward slash, and non US\-ASCII Unicode characters are represented using the UTF\-7 character set, and encoded with a modified form of base64\-encoding\&.
.PP
The
\(lq&\(rq
character starts the modified base64\-encoded sequence; the sequence is terminated by the
\(lq\-\(rq
character\&. The sequence of 16\-bit Unicode characters is written in big\-endian order, and encoded using the base64\-encoding method described in section 5\&.2 of
\m[blue]\fBRFC 1521\fR\m[]\&\s-2\u[2]\d\s+2, with the following modifications:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The
\(lq=\(rq
padding character is omitted\&. When decoding, an incomplete 16\-bit character is discarded\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The comma character,
\(lq,\(rq
is used in place of the
\(lq/\(rq
character in the base64 alphabet\&.
.RE
.PP
For example, the word
\(lqResume\(rq
with both "e"s being the e\-acute character, U+0x00e9, is encoded as
\(lqR&AOk\-sum&AOk\-\(rq
(so a folder of that name would be a maildir subdirectory called
\(lq\&.R&AOk\-sum&AOk\-\(rq)\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBOther maildir contents\fR
.RS 4
.PP
Software that uses maildirs may also create additional files besides the
tmp,
new, and
cur
subdirectories \-\- in the main maildir or a subfolder \-\- for its own purposes\&.
.RE
.SS "Messages"
.PP
E\-mail messages are stored in separate, individual files, one E\-mail message per file\&. The
tmp
subdirectory temporarily stores E\-mail messages that are in the process of being delivered to this maildir\&.
tmp
may also store other kinds of temporary files, as long as they are created in the same way that message files are created in
tmp\&. The
new
subdirectory stores messages that have been delivered to this maildir, but have not yet been seen by any mail application\&. The
cur
subdirectory stores messages that have already been seen by mail applications\&.
.SS "Adding new mail to maildirs"
.PP
The following process delivers a new message to the maildir:
.PP
A new unique filename is created using one of two possible forms:
\(lqtime\&.MusecPpid\&.host\(rq, or
\(lqtime\&.MusecPpid_unique\&.host\(rq\&.
\(lqtime\(rq
and
\(lqusec\(rq
is the current system time, obtained from
\fBgettimeofday\fR(2)\&.
\(lqpid\(rq
is the process number of the process that is delivering this message to the maildir\&.
\(lqhost\(rq
is the name of the machine where the mail is being delivered\&. In the event that the same process creates multiple messages, a suffix unique to each message is appended to the process id; preferrably an underscore, followed by an increasing counter\&. This applies whether messages created by a process are all added to the same, or different, maildirs\&. This protocol allows multiple processes running on multiple machines on the same network to simultaneously create new messages without stomping on each other\&.
.PP
The filename created in the previous step is checked for existence by executing the
\fBstat\fR(2)
system call\&. If
\fBstat\fR(2)
results in ANYTHING OTHER than the system error
ENOENT, the process must sleep for two seconds, then go back and create another unique filename\&. This is an extra step to insure that each new message has a completely unique filename\&.
.PP
Other applications that wish to use
tmp
for temporary storage should observe the same protocol (but see READING MAIL FROM MAILDIRS below, because old files in
tmp
will be eventually deleted)\&.
.PP
If the
\fBstat\fR(2)
system call returned
ENOENT, the process may proceed to create the file in the
tmp
subdirectory, and save the entire message in the new file\&. The message saved MUST NOT have the
\(lqFrom_\(rq
header that is used to mboxes\&. The message also MUST NOT have any
\(lqFrom_\(rq
lines in the contents of the message prefixed by the
\(lq>\(rq
character\&.
.PP
When saving the message, the number of bytes returned by the
\fBwrite\fR(2)
system call must be checked, in order to make sure that the complete message has been written out\&.
.PP
After the message is saved, the file descriptor is
\fBfstat\fR(2)\-ed\&. The file\*(Aqs device number, inode number, and the its byte size, are saved\&. The file is closed and is then immediately moved/renamed into the
new
subdirectory\&. The name of the file in
new
should be
\(lqtime\&.MusecPpidVdevIino\&.host,S=\fIcnt\fR\(rq, or
\(lqtime\&.MusecPpidVdevIino_unique\&.host,S=\fIcnt\fR\(rq\&.
\(lqdev\(rq
is the message\*(Aqs device number,
\(lqino\(rq
is the message\*(Aqs inode number (from the previous
\fBfstat\fR(2)
call); and
\(lqcnt\(rq
is the message\*(Aqs size, in bytes\&.
.PP
The
\(lq,S=\fIcnt\fR\(rq
part optimizes the
\m[blue]\fBCourier\fR\m[]\&\s-2\u[3]\d\s+2
mail server\*(Aqs maildir quota enhancement; it allows the size of all the mail stored in the maildir to be added up without issuing the
\fBstat\fR(2)
system call for each individual message (this can be quite a performance drain with certain network filesystems)\&.
.SS "READING MAIL FROM MAILDIRS"
.PP
Applications that read mail from maildirs should do it in the following order:
.PP
When opening a maildir or a maildir folder, read the
tmp
subdirectory and delete any files in there that are at least 36 hours old\&.
.PP
Look for new messages in the
new
subdirectory\&. Rename
\fInew/filename\fR, as
\fIcur/filename:2,info\fR\&. Here,
\fIinfo\fR
represents the state of the message, and it consists of zero or more boolean flags chosen from the following:
\(lqD\(rq
\- this is a \*(Aqdraft\*(Aq message,
\(lqR\(rq
\- this message has been replied to,
\(lqS\(rq
\- this message has been viewed (seen),
\(lqT\(rq
\- this message has been marked to be deleted (trashed), but is not yet removed (messages are removed from maildirs simply by deleting their file),
\(lqF\(rq
\- this message has been marked by the user, for some purpose\&. These flags must be stored in alphabetical order\&. New messages contain only the
:2,
suffix, with no flags, indicating that the messages were not seen, replied, marked, or deleted\&.
.PP
Maildirs may have maximum size quotas defined, but these quotas are purely voluntary\&. If you need to implement mandatory quotas, you should use any quota facilities provided by the underlying filesystem that is used to store the maildirs\&. The maildir quota enhancement is designed to be used in certain situations where filesystem\-based quotas cannot be used for some reason\&. The implementation is designed to avoid the use of any locking\&. As such, at certain times the calculated quota may be imprecise, and certain anomalous situations may result in the maildir actually going over the stated quota\&. One such situation would be when applications create messages without updating the quota estimate for the maildir\&. Eventually it will be precisely recalculated, but wherever possible new messages should be created in compliance with the voluntary quota protocol\&.
.PP
The voluntary quota protocol involves some additional procedures that must be followed when creating or deleting messages within a given maildir or its subfolders\&. The
\m[blue]\fB\fBdeliverquota\fR(8)\fR\m[]\&\s-2\u[4]\d\s+2
command is a tiny application that delivers a single message to a maildir using the voluntary quota protocol, and hopefully it can be used as a measure of last resort\&. Alternatively, applications can use the
libmaildir\&.a
library to handle all the low\-level dirty details for them\&. The voluntary quota enhancement is described in the
\m[blue]\fB\fBmaildirquota\fR(7)\fR\m[]\&\s-2\u[5]\d\s+2
man page\&.
.SS "Maildir Quotas"
.PP
This is a voluntary mechanism for enforcing "loose" quotas on the maximum sizes of maildirs\&. This mechanism is enforced in software, and not by the operating system\&. Therefore it is only effective as long as the maildirs themselves are not directly accessible by their users, since this mechanism is trivially disabled\&.
.PP
If possible, operating system\-enforced quotas are preferrable\&. Where operating system quota enforcement is not available, or not possible, this voluntary quota enforcement mechanism might be an acceptable compromise\&. Since it\*(Aqs enforced in software, all software that modifies or accesses the maildirs is required to voluntary obey and enforce a quota\&. The voluntary quota implementation is flexible enough to allow non quota\-aware applications to also access the maildirs, without any drastic consequences\&. There will be some non\-drastic consequences, though\&. Of course, non quota\-aware applications will not enforce any defined quotas\&. Furthermore, this voluntary maildir quota mechanism works by estimating the current size of the maildir, with periodic exact recalculation\&. Obviously non quota\-aware maildir applications will not update the maildir size estimation, so the estimate will be thrown off for some period of time, until the next recalculation\&.
.PP
This voluntary quota mechanism is designed to be a reasonable compromise between effectiveness, and performance\&. The entire purpose of using maildir\-based mail storage is to avoid any kind of locking, and to permit parallel access to mail by multiple applications\&. In order to compute the exact size of a maildir, the maildir must be locked somehow to prevent any modifications while its contents are added up\&. Obviously something like that defeats the original purpose of using maildirs, therefore the voluntary quota mechanism does not use locking, and that\*(Aqs why the current recorded maildir size is always considered to be an estimate\&. Regular size recalculations will compensate for any occasional race conditions that result in the estimate to be thrown off\&.
.PP
A quota for an existing maildir is installed by running maildirmake with the
\-q
option, and naming an existing maildir\&. The
\-q
option takes a parameter,
\fIquota\fR, which is a comma\-separated list of quota specifications\&. A quota specification consists of a number followed by either \*(AqS\*(Aq, indicating the maximum message size in bytes, or \*(AqC\*(Aq, maximum number of messages\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
\fBmaildirmake \-q 5000000S,1000C \&./Maildir\fR
.fi
.if n \{\
.RE
.\}
.PP
This sets the quota to 5,000,000 bytes or 1000 messages, whichever comes first\&.
.sp
.if n \{\
.RS 4
.\}
.nf
\fBmaildirmake \-q 1000000S \&./Maildir\fR
.fi
.if n \{\
.RE
.\}
.PP
This sets the quota to 1,000,000 bytes, without limiting the number of messages\&.
.PP
A quota of an existing maildir can be changed by rerunning the
\fBmaildirmake\fR
command with a new
\-q
option\&. To delete a quota entirely, delete the
\fIMaildir\fR/maildirsize
file\&.
.SH "SEE ALSO"
.PP
\m[blue]\fB\fBmaildirmake\fR(1)\fR\m[]\&\s-2\u[1]\d\s+2\&.
.SH "AUTHOR"
.PP
\fBSam Varshavchik\fR
.RS 4
Author
.RE
.SH "NOTES"
.IP " 1." 4
\fBmaildirmake\fR(1)
.RS 4
\%http://www.courier-mta.org/maildirmake.html
.RE
.IP " 2." 4
RFC 1521
.RS 4
\%http://www.rfc-editor.org/rfc/rfc1521.txt
.RE
.IP " 3." 4
Courier
.RS 4
\%http://www.courier-mta.org
.RE
.IP " 4." 4
\fBdeliverquota\fR(8)
.RS 4
\%http://www.courier-mta.org/deliverquota.html
.RE
.IP " 5." 4
\fBmaildirquota\fR(7)
.RS 4
\%http://www.courier-mta.org/maildirquota.html
.RE

187
meli/docs/historical-manpages/mbox.5.en.gz Normal file
View File

@ -0,0 +1,187 @@
'\" t
.\" -*-nroff-*-
.\"
.\" Copyright (C) 2000 Thomas Roessler <roessler@does-not-exist.org>
.\"
.\" This document is in the public domain and may be distributed and
.\" changed arbitrarily.
.\"
.TH mbox 5 "February 19th, 2002" Unix "User Manuals"
.\"
.SH NAME
mbox \- Format for mail message storage.
.\"
.SH DESCRIPTION
This document describes the format traditionally used by Unix hosts
to store mail messages locally.
.B mbox
files typically reside in the system's mail spool, under various
names in users' Mail directories, and under the name
.B mbox
in users' home directories.
.PP
An
.B mbox
is a text file containing an arbitrary number of e-mail messages.
Each message consists of a postmark, followed by an e-mail message
formatted according to \fBRFC822\fP, \fBRFC2822\fP. The file format
is line-oriented. Lines are separated by line feed characters (ASCII 10).
.PP
A postmark line consists of the four characters "From", followed by
a space character, followed by the message's envelope sender
address, followed by whitespace, and followed by a time stamp. This
line is often called From_ line.
.PP
The sender address is expected to be
.B addr-spec
as defined in \fBRFC2822\fP 3.4.1. The date is expected to be
.B date-time
as output by
.BR asctime (3).
For compatibility reasons with legacy software, two-digit years
greater than or equal to 70 should be interpreted as the years
1970+, while two-digit years less than 70 should be interpreted as
the years 2000-2069. Software reading files in this format should
also be prepared to accept non-numeric timezone information such as
"CET DST" for Central European Time, daylight saving time.
.PP
Example:
.IP "" 1
>From example@example.com Fri Jun 23 02:56:55 2000
.PP
In order to avoid misinterpretation of lines in message bodies
which begin with the four characters "From", followed by a space
character, the mail delivery agent must quote any occurrence
of "From " at the start of a body line.
.sp
There are two different quoting schemes, the first (\fBMBOXO\fP) only
quotes plain "From " lines in the body by prepending a '>' to the
line; the second (\fBMBOXRD\fP) also quotes already quoted "From "
lines by prepending a '>' (i.e. ">From ", ">>From ", ...). The later
has the advantage that lines like
.IP "" 1
>From the command line you can use the '\-p' option
.PP
aren't dequoted wrongly as a \fBMBOXRD\fP-MDA would turn the line
into
.IP "" 1
>>From the command line you can use the '\-p' option
.PP
before storing it. Besides \fBMBOXO\fP and \fBMBOXRD\fP there is also
\fBMBOXCL\fP which is \fBMBOXO\fP with a "Content-Length:"\-field with the
number of bytes in the message body; some MUAs (like
.BR mutt (1))
do automatically transform \fBMBOXO\fP mailboxes into \fBMBOXCL\fP ones when
ever they write them back as \fBMBOXCL\fP can be read by any \fBMBOXO\fP-MUA
without any problems.
.PP
If the modification-time (usually determined via
.BR stat (2))
of a nonempty
.B mbox
file is greater than the access-time the file has new mail. Many MUAs
place a Status: header in each message to indicate which messages have
already been read.
.\"
.SH LOCKING
Since
.B mbox
files are frequently accessed by multiple programs in parallel,
.B mbox
files should generally not be accessed without locking.
.PP
Three different locking mechanisms (and combinations thereof) are in
general use:
.IP "\(bu"
.BR fcntl (2)
locking is mostly used on recent, POSIX-compliant systems. Use of
this locking method is, in particular, advisable if
.B mbox
files are accessed through the Network File System (NFS), since it
seems the only way to reliably invalidate NFS clients' caches.
.IP "\(bu"
.BR flock (2)
locking is mostly used on BSD-based systems.
.IP "\(bu"
Dotlocking is used on all kinds of systems. In order to lock an
.B mbox
file named \fIfolder\fR, an application first creates a temporary file
with a unique name in the directory in which the
\fIfolder\fR resides. The application then tries to use the
.BR link (2)
system call to create a hard link named \fIfolder.lock\fR
to the temporary file. The success of the
.BR link (2)
system call should be additionally verified using
.BR stat (2)
calls. If the link has succeeded, the mail folder is considered
dotlocked. The temporary file can then safely be unlinked.
.IP ""
In order to release the lock, an application just unlinks the
\fIfolder.lock\fR file.
.PP
If multiple methods are combined, implementors should make sure to
use the non-blocking variants of the
.BR fcntl (2)
and
.BR flock (2)
system calls in order to avoid deadlocks.
.PP
If multiple methods are combined, an
.B mbox
file must not be considered to have been successfully locked before
all individual locks were obtained. When one of the individual
locking methods fails, an application should release all locks it
acquired successfully, and restart the entire locking procedure from
the beginning, after a suitable delay.
.PP
The locking mechanism used on a particular system is a matter of
local policy, and should be consistently used by all applications
installed on the system which access
.B mbox
files. Failure to do so may result in loss of e-mail data, and in
corrupted
.B mbox
files.
.\"
.SH FILES
.IR /var/spool/mail/$LOGNAME
.RS
\fB$LOGNAME\fP's incoming mail folder.
.RE
.PP
.IR $HOME/mbox
.RS
user's archived mail messages, in his \fB$HOME\fP directory.
.RE
.PP
.IR $HOME/Mail/
.RS
A directory in user's \fB$HOME\fP directory which is commonly used to hold
.B mbox
format folders.
.RE
.PP
.\"
.SH "SEE ALSO"
.BR mutt (1),
.BR fcntl (2),
.BR flock (2),
.BR link (2),
.BR stat (2),
.BR asctime (3),
.BR maildir (5),
.BR mmdf (5),
.BR RFC822 ,
.BR RFC976 ,
.BR RFC2822
.\"
.SH AUTHOR
Thomas Roessler <roessler@does-not-exist.org>, Urs Janssen <urs@tin.org>
.\"
.SH HISTORY
The
.B mbox
format occurred in Version 6 AT&T Unix.
.br
A variant of this format was documented in \fBRFC976\fP.

235
meli/docs/historical-manpages/mbox.5qmail.en.gz Normal file
View File

@ -0,0 +1,235 @@
.TH mbox 5
.SH "NAME"
mbox \- file containing mail messages
.SH "INTRODUCTION"
The most common format for storage of mail messages is
.I mbox
format.
An
.I mbox
is a single file containing zero or more mail messages.
.SH "MESSAGE FORMAT"
A message encoded in
.I mbox
format begins with a
.B From_
line, continues with a series of
.B \fRnon-\fBFrom_
lines,
and ends with a blank line.
A
.B From_
line means any line that begins with the characters
F, r, o, m, space:
.EX
From god@heaven.af.mil Sat Jan 3 01:05:34 1996
.br
Return-Path: <god@heaven.af.mil>
.br
Delivered-To: djb@silverton.berkeley.edu
.br
Date: 3 Jan 1996 01:05:34 -0000
.br
From: God <god@heaven.af.mil>
.br
To: djb@silverton.berkeley.edu (D. J. Bernstein)
.br
.br
How's that mail system project coming along?
.br
.EE
The final line is a completely blank line (no spaces or tabs).
Notice that blank lines may also appear elsewhere in the message.
The
.B From_
line always looks like
.B From
.I envsender
.I date
.IR moreinfo .
.I envsender
is one word, without spaces or tabs;
it is usually the envelope sender of the message.
.I date
is the delivery date of the message.
It always contains exactly 24 characters in
.B asctime
format.
.I moreinfo
is optional; it may contain arbitrary information.
Between the
.B From_
line and the blank line is a message in RFC 822 format,
as described in
.BR qmail-header(5) ,
subject to
.B >From quoting
as described below.
.SH "HOW A MESSAGE IS DELIVERED"
Here is how a program appends a message to an
.I mbox
file.
It first creates a
.B From_
line given the message's envelope sender and the current date.
If the envelope sender is empty (i.e., if this is a bounce message),
the program uses
.B MAILER-DAEMON
instead.
If the envelope sender contains spaces, tabs, or newlines,
the program replaces them with hyphens.
The program then copies the message, applying
.B >From quoting
to each line.
.B >From quoting
ensures that the resulting lines are not
.B From_
lines:
the program prepends a
.B >
to any
.B From_
line,
.B >From_
line,
.B >>From_
line,
.B >>>From_
line,
etc.
Finally the program appends a blank line to the message.
If the last line of the message was a partial line,
it writes two newlines;
otherwise it writes one.
.SH "HOW A MESSAGE IS READ"
A reader scans through an
.I mbox
file looking for
.B From_
lines.
Any
.B From_
line marks the beginning of a message.
The reader should not attempt to take advantage of the fact that every
.B From_
line (past the beginning of the file)
is preceded by a blank line.
Once the reader finds a message,
it extracts a (possibly corrupted) envelope sender
and delivery date out of the
.B From_
line.
It then reads until the next
.B From_
line or end of file, whichever comes first.
It strips off the final blank line
and
deletes the
quoting of
.B >From_
lines and
.B >>From_
lines and so on.
The result is an RFC 822 message.
.SH "COMMON MBOX VARIANTS"
There are many variants of
.I mbox
format.
The variant described above is
.I mboxrd
format, popularized by Rahul Dhesi in June 1995.
The original
.I mboxo
format quotes only
.B From_
lines, not
.B >From_
lines.
As a result it is impossible to tell whether
.EX
From: djb@silverton.berkeley.edu (D. J. Bernstein)
.br
To: god@heaven.af.mil
.br
.br
>From now through August I'll be doing beta testing.
.br
Thanks for your interest.
.EE
was quoted in the original message.
An
.I mboxrd
reader will always strip off the quoting.
.I mboxcl
format is like
.I mboxo
format, but includes a Content-Length field with the
number of bytes in the message.
.I mboxcl2
format is like
.I mboxcl
but has no
.B >From
quoting.
These formats are used by SVR4 mailers.
.I mboxcl2
cannot be read safely by
.I mboxrd
readers.
.SH "UNSPECIFIED DETAILS"
There are many locking mechanisms for
.I mbox
files.
.B qmail-local
always uses
.B flock
on systems that have it, otherwise
.BR lockf .
The delivery date in a
.B From_
line does not specify a time zone.
.B qmail-local
always creates the delivery date in GMT
so that
.I mbox
files can be safely transported from one time zone to another.
If the mtime on a nonempty
.I mbox
file is greater than the atime,
the file has new mail.
If the mtime is smaller than the atime,
the new mail has been read.
If the atime equals the mtime,
there is no way to tell whether the file has new mail,
since
.B qmail-local
takes much less than a second to run.
One solution is for a mail reader to artificially set the
atime to the mtime plus 1.
Then the file has new mail if and only if the atime is
less than or equal to the mtime.
Some mail readers place
.B Status
fields in each message to indicate which messages have been read.
.SH "SEE ALSO"
maildir(5),
qmail-header(5),
qmail-local(8)

239
meli/docs/historical-manpages/qmail-maildir.5.gz Normal file
View File

@ -0,0 +1,239 @@
.TH maildir 5
.SH "NAME"
maildir \- directory for incoming mail messages
.SH "INTRODUCTION"
.I maildir
is a structure for
directories of incoming mail messages.
It solves the reliability problems that plague
.I mbox
files and
.I mh
folders.
.SH "RELIABILITY ISSUES"
A machine may crash while it is delivering a message.
For both
.I mbox
files and
.I mh
folders this means that the message will be silently truncated.
Even worse: for
.I mbox
format, if the message is truncated in the middle of a line,
it will be silently joined to the next message.
The mail transport agent will try again later to deliver the message,
but it is unacceptable that a corrupted message should show up at all.
In
.IR maildir ,
every message is guaranteed complete upon delivery.
A machine may have two programs simultaneously delivering mail
to the same user.
The
.I mbox
and
.I mh
formats require the programs to update a single central file.
If the programs do not use some locking mechanism,
the central file will be corrupted.
There are several
.I mbox
and
.I mh
locking mechanisms,
none of which work portably and reliably.
In contrast, in
.IR maildir ,
no locks are ever necessary.
Different delivery processes never touch the same file.
A user may try to delete messages from his mailbox at the same
moment that the machine delivers a new message.
For
.I mbox
and
.I mh
formats, the user's mail-reading program must know
what locking mechanism the mail-delivery programs use.
In contrast, in
.IR maildir ,
any delivered message
can be safely updated or deleted by a mail-reading program.
Many sites use Sun's
.B Network F\fPa\fBil\fPur\fBe System
(NFS),
presumably because the operating system vendor does not offer
anything else.
NFS exacerbates all of the above problems.
Some NFS implementations don't provide
.B any
reliable locking mechanism.
With
.I mbox
and
.I mh
formats,
if two machines deliver mail to the same user,
or if a user reads mail anywhere except the delivery machine,
the user's mail is at risk.
.I maildir
works without trouble over NFS.
.SH "THE MAILDIR STRUCTURE"
A directory in
.I maildir
format has three subdirectories,
all on the same filesystem:
.BR tmp ,
.BR new ,
and
.BR cur .
Each file in
.B new
is a newly delivered mail message.
The modification time of the file is the delivery date of the message.
The message is delivered
.I without
an extra UUCP-style
.B From_
line,
.I without
any
.B >From
quoting,
and
.I without
an extra blank line at the end.
The message is normally in RFC 822 format,
starting with a
.B Return-Path
line and a
.B Delivered-To
line,
but it could contain arbitrary binary data.
It might not even end with a newline.
Files in
.B cur
are just like files in
.BR new .
The big difference is that files in
.B cur
are no longer new mail:
they have been seen by the user's mail-reading program.
.SH "HOW A MESSAGE IS DELIVERED"
The
.B tmp
directory is used to ensure reliable delivery,
as discussed here.
A program delivers a mail message in six steps.
First, it
.B chdir()\fPs
to the
.I maildir
directory.
Second, it
.B stat()s
the name
.BR tmp/\fItime.pid.host ,
where
.I time
is the number of seconds since the beginning of 1970 GMT,
.I pid
is the program's process ID,
and
.I host
is the host name.
Third, if
.B stat()
returned anything other than ENOENT,
the program sleeps for two seconds, updates
.IR time ,
and tries the
.B stat()
again, a limited number of times.
Fourth, the program
creates
.BR tmp/\fItime.pid.host .
Fifth, the program
.I NFS-writes
the message to the file.
Sixth, the program
.BR link() s
the file to
.BR new/\fItime.pid.host .
At that instant the message has been successfully delivered.
The delivery program is required to start a 24-hour timer before
creating
.BR tmp/\fItime.pid.host ,
and to abort the delivery
if the timer expires.
Upon error, timeout, or normal completion,
the delivery program may attempt to
.B unlink()
.BR tmp/\fItime.pid.host .
.I NFS-writing
means
(1) as usual, checking the number of bytes returned from each
.B write()
call;
(2) calling
.B fsync()
and checking its return value;
(3) calling
.B close()
and checking its return value.
(Standard NFS implementations handle
.B fsync()
incorrectly
but make up for it by abusing
.BR close() .)
.SH "HOW A MESSAGE IS READ"
A mail reader operates as follows.
It looks through the
.B new
directory for new messages.
Say there is a new message,
.BR new/\fIunique .
The reader may freely display the contents of
.BR new/\fIunique ,
delete
.BR new/\fIunique ,
or rename
.B new/\fIunique
as
.BR cur/\fIunique:info .
See
.B http://pobox.com/~djb/proto/maildir.html
for the meaning of
.IR info .
The reader is also expected to look through the
.B tmp
directory and to clean up any old files found there.
A file in
.B tmp
may be safely removed if it
has not been accessed in 36 hours.
It is a good idea for readers to skip all filenames in
.B new
and
.B cur
starting with a dot.
Other than this, readers should not attempt to parse filenames.
.SH "ENVIRONMENT VARIABLES"
Mail readers supporting
.I maildir
use the
.B MAILDIR
environment variable
as the name of the user's primary mail directory.
.SH "SEE ALSO"
mbox(5),
qmail-local(8)