--- /dev/null
+/* ========================================================================
+ * Copyright 1988-2006 University of Washington
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *
+ * ========================================================================
+ */
+
+ c-client Driver Characteristics
+ Mark Crispin
+ 11 December 2006
+
+
+ Drivers are code modules that support different mailbox storage
+technologies. A mailbox storage technology may be implemented by
+ 1) files and directories on the local system
+ 2) a database
+ 3) a network protocol.
+
+ In the case of files and directories on the local system, a
+driver supports a particular mailbox format. Mailbox formats are
+discussed in more detail in the file formats.txt.
+
+ As of the date this document was written, there was no bundled
+support for any databases in c-client. However, it should not be
+particularly difficult to write a driver that communicates with a
+database.
+
+ Network protocols supported by c-client drivers are the Internet
+Mail Access Protocol (all versions: IMAP4rev1, IMAP4, IMAP2bis, and
+IMAP2); the Post Office Protocol (version 3); and the Network News
+Transport Protocol (NNTP). In addition, c-client also supports NNTP
+and the Simple Mail Transport Protocol (SMTP) for mailbox transport.
+
+ By default, all drivers are enabled. There is little benefit to
+be gained by disabling a driver, with one exception. The mbox driver
+implements the behavior of automatically moving new mail from the
+spool directory to the "mbox" file on the user's home directory, if
+and *only* if the "mbox" exists and is in mailbox format. The mbox
+driver is listed under EXTRADRIVERS; if you wish to disable it just
+remove it from that list and rebuild.
+
+I. Special name "INBOX"
+
+The following rules to select INBOX and its format apply in
+the order given if "black box mode" is not in effect:
+ 1) mbox format is selected if file ~/mbox exists, and is in unix
+ format or is zero-length.
+ 2) mx format is selected if file ~/INBOX/.mxindex exists.
+ 3) mbx format is selected if file ~/INBOX exists and is in mbx format.
+ 4) tenex format is selected if:
+ a) file ~/mail.txt exists, and is in tenex format or is zero-length.
+ b) file ~/INBOX exists and is in tenex format.
+ 5) mtx format is selected if:
+ a) file ~/INBOX.MTX exists, and is in mtx format or is zero-length.
+ b) file ~/INBOX exists and is in mtx format.
+ 6) mmdf format is selected if the spool directory file exists and is
+ in mmdf format.
+ 7) unix format is selected if the spool directory file exists and is
+ in unix format.
+ 8) the dummy driver is selected if the spool directory file does not
+ exist, or exists and is empty.
+
+If "black box mode" is not in effect, messages are automatically
+transferred ("snarfed") from the spool directory to an INBOX in mbox,
+mx, mbx, tenex, and mtx formats.
+
+The following rules to select INBOX and its format apply in the order
+given if "black box mode" is in effect:
+ 1) mx format is selected if file ~/INBOX/.mxindex exists.
+ 2) mbx format is selected if file ~/INBOX exists and is in mbx format.
+ 3) tenex format is selected if file ~/INBOX exists and is in tenex format.
+ 4) mtx format is selected if file ~/INBOX exists and is in mtx format.
+ 5) mmdf format is selected if file ~/INBOX exists and is in mmdf format.
+ 6) unix format is selected if file ~/INBOX exists and is in unix format.
+ 7) the dummy driver is selected if ~/INBOX does not exist, or exists
+ and is empty.
+\f
+II. Special Name #mhinbox
+
+#mhinbox always refers to the directory "inbox" in the MH path, which
+is declared in the ~/.mh_profile file. Messages are automatically
+transferred from the spool directory to #mhinbox mailbox.
+
+
+III. Special Prefix "#mh/"
+
+Any name prefixed with "#mh/" always refers to a directory in the MH
+path, which is declared in the ~/.mh_profile file. For example, the name
+"#mh/foo" refers to directory "foo" in the MH path.
+
+
+IV. Special prefix "#news."
+
+Any name prefixed with "#news" always refers to a newsgroup. For
+example, the name "#news.comp.mail.misc" refers to newsgroup
+"comp.mail.misc".
+
+
+V. All Other Names
+
+The driver is selected by generating a file name from the mailbox
+name, and then examining the data of the object with the resulting
+name. The formats are checked in order: mx, mbx, tenex, mtx, mmdf,
+unix, and phile. The dummy driver is selected if the file is empty.
+
+The file name is generated according to certain rules, based upon the
+prefix of the mailbox name. On UNIX, the following rules apply:
+
+Prefix Interpretation of Suffix
+------ ------------------------
+/ [black box] preceeds a user name; "/foo/bar" means
+ "black box user foo's mailbox bar"
+ [not black box] preceeds an absolute path name.
+~ [not black box] preceeds a user name; "~foo/bar" means
+ "UNIX user foo's mailbox bar"
+#ftp/ preceeds UNIX user ftp's mailbox name
+#public/ preceeds UNIX user imappublic's mailbox name
+#shared/ preceeds UNIX user imapshared's mailbox name
+
+All other names are interpreted in the context of the UNIX user's home
+directory (not black box), the black box user's black box directory
+(black box), or UNIX user ftp's home directory (anonymous).
+
+The strings "..", "//", and /~ are forbidden in names in:
+ black box mode
+ #ftp, #public, or #shared names
+ anonymous users
+
+Anonymous users may only access:
+ INBOX (belonging to UNIX user ftp)
+ files in or below UNIX user ftp's home directory
+ #ftp, #news, and #public namespace
+\f
+VI. Driver Comparison
+
+The following information about the local file drivers is an
+elaboration of a table compiled by Osma Ahvenlampi.
+
+Driver CA CE UID Kwd Sub NFS Performance Layout
+------ -- -- --- --- --- --- ----------- ------
+unix no no yes yes no limited fair file
+ ;;; traditional UNIX format
+mbox no no yes yes no limited fair file
+ ;;; traditional UNIX format, INBOX only, using ~/mbox with automatic
+ ;;; moving from the mail spool directory.
+mmdf no no yes yes no limited fair file
+ ;;; default on SCO systems
+mbx yes yes yes yes no no very good prefile
+ ;;; best performing local file driver; preferred format at UW
+tenex yes no no limited no no good prefile
+ ;;; compatible with UNIX MM
+mtx yes no no limited no no very good prefile
+ ;;; PC Pine standard format; compatible with TOPS-20; identical to tenex
+ ;;; but instead CRLF newlines instead of LF
+mx yes buggy yes yes yes no poor ixdir
+ ;;; fullest function; *not* recommended due to performance problems and bugs;
+ ;;; to be redesigned/rewritten
+mh yes no no no yes yes very poor dir
+ ;;; compatible with mh; #mhinbox for INBOX, #mh/ prefix for all other names
+news yes no yes no yes yes very poor ixdir
+ ;;; local news spool access; #news. prefix for all names
+phile no no no no no yes good file
+ ;;; reads arbitrary file as a single readonly message
+
+IMPORTANT: the "performance" ratings are relative to other drivers,
+and not necessarily to other software which implements those formats.
+They relate to the driver's performance in typical operations such as
+an IMAP "FETCH ALL".
+
+Key to headings:
+ CA: concurrent read/write access
+ CE: expunge permitted in concurrent read/write access
+ UID: sticky UIDs
+ Kwd: keyword flags
+ Sub: subfolders
+ NFS: usable over network filesystems (NFS, AFS, etc.)
+ Layout: file - single file
+ prefile - file with preallocated space for state
+ dir - directory, messages are files
+ ixdir - directory, messages are files, with helper index
+
+In addition, drivers imap, nntp, and pop3 support IMAP4rev1, NNTP, and
+POP3 protocols respectively.
projects / uw-imap / commitdiff