diff --git a/meli/docs/historical-manpages/maildir.5.en.gz b/meli/docs/historical-manpages/maildir.5.en.gz new file mode 100644 index 00000000..c0b9e1b9 --- /dev/null +++ b/meli/docs/historical-manpages/maildir.5.en.gz @@ -0,0 +1,354 @@ +'\" t +.\" +.\" +.\" Title: maildir +.\" Author: Sam Varshavchik +.\" Generator: DocBook XSL Stylesheets vsnapshot +.\" 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 diff --git a/meli/docs/historical-manpages/mbox.5.en.gz b/meli/docs/historical-manpages/mbox.5.en.gz new file mode 100644 index 00000000..740c584d --- /dev/null +++ b/meli/docs/historical-manpages/mbox.5.en.gz @@ -0,0 +1,187 @@ +'\" t +.\" -*-nroff-*- +.\" +.\" Copyright (C) 2000 Thomas Roessler +.\" +.\" 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 , Urs Janssen +.\" +.SH HISTORY +The +.B mbox +format occurred in Version 6 AT&T Unix. +.br +A variant of this format was documented in \fBRFC976\fP. diff --git a/meli/docs/historical-manpages/mbox.5qmail.en.gz b/meli/docs/historical-manpages/mbox.5qmail.en.gz new file mode 100644 index 00000000..de1f837c --- /dev/null +++ b/meli/docs/historical-manpages/mbox.5qmail.en.gz @@ -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: +.br + Delivered-To: djb@silverton.berkeley.edu +.br + Date: 3 Jan 1996 01:05:34 -0000 +.br + From: God +.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) diff --git a/meli/docs/historical-manpages/qmail-maildir.5.gz b/meli/docs/historical-manpages/qmail-maildir.5.gz new file mode 100644 index 00000000..5da9573c --- /dev/null +++ b/meli/docs/historical-manpages/qmail-maildir.5.gz @@ -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)