1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/drivers.txt	Mon Sep 14 15:17:45 2009 +0900
     1.3 @@ -0,0 +1,189 @@
     1.4 +/* ========================================================================
     1.5 + * Copyright 1988-2006 University of Washington
     1.6 + *
     1.7 + * Licensed under the Apache License, Version 2.0 (the "License");
     1.8 + * you may not use this file except in compliance with the License.
     1.9 + * You may obtain a copy of the License at
    1.10 + *
    1.11 + *     http://www.apache.org/licenses/LICENSE-2.0
    1.12 + *
    1.13 + * 
    1.14 + * ========================================================================
    1.15 + */
    1.16 +
    1.17 +		   c-client Driver Characteristics
    1.18 +			     Mark Crispin
    1.19 +			   11 December 2006
    1.20 +
    1.21 +
    1.22 +     Drivers are code modules that support different mailbox storage
    1.23 +technologies.  A mailbox storage technology may be implemented by
    1.24 + 1) files and directories on the local system
    1.25 + 2) a database
    1.26 + 3) a network protocol.
    1.27 +
    1.28 +     In the case of files and directories on the local system, a
    1.29 +driver supports a particular mailbox format.  Mailbox formats are
    1.30 +discussed in more detail in the file formats.txt.
    1.31 +
    1.32 +     As of the date this document was written, there was no bundled
    1.33 +support for any databases in c-client.  However, it should not be
    1.34 +particularly difficult to write a driver that communicates with a
    1.35 +database.
    1.36 +
    1.37 +     Network protocols supported by c-client drivers are the Internet
    1.38 +Mail Access Protocol (all versions: IMAP4rev1, IMAP4, IMAP2bis, and
    1.39 +IMAP2); the Post Office Protocol (version 3); and the Network News
    1.40 +Transport Protocol (NNTP).  In addition, c-client also supports NNTP
    1.41 +and the Simple Mail Transport Protocol (SMTP) for mailbox transport.
    1.42 +
    1.43 +     By default, all drivers are enabled.  There is little benefit to
    1.44 +be gained by disabling a driver, with one exception.  The mbox driver
    1.45 +implements the behavior of automatically moving new mail from the
    1.46 +spool directory to the "mbox" file on the user's home directory, if
    1.47 +and *only* if the "mbox" exists and is in mailbox format.  The mbox
    1.48 +driver is listed under EXTRADRIVERS; if you wish to disable it just
    1.49 +remove it from that list and rebuild.
    1.50 +
    1.51 +I. Special name "INBOX"
    1.52 +
    1.53 +The following rules to select INBOX and its format apply in
    1.54 +the order given if "black box mode" is not in effect:
    1.55 + 1) mbox format is selected if file ~/mbox exists, and is in unix
    1.56 +    format or is zero-length.
    1.57 + 2) mx format is selected if file ~/INBOX/.mxindex exists.
    1.58 + 3) mbx format is selected if file ~/INBOX exists and is in mbx format.
    1.59 + 4) tenex format is selected if:
    1.60 +    a) file ~/mail.txt exists, and is in tenex format or is zero-length.
    1.61 +    b) file ~/INBOX exists and is in tenex format.
    1.62 + 5) mtx format is selected if:
    1.63 +    a) file ~/INBOX.MTX exists, and is in mtx format or is zero-length.
    1.64 +    b) file ~/INBOX exists and is in mtx format.
    1.65 + 6) mmdf format is selected if the spool directory file exists and is
    1.66 +    in mmdf format.
    1.67 + 7) unix format is selected if the spool directory file exists and is
    1.68 +    in unix format.   
    1.69 + 8) the dummy driver is selected if the spool directory file does not
    1.70 +    exist, or exists and is empty.
    1.71 +
    1.72 +If "black box mode" is not in effect, messages are automatically
    1.73 +transferred ("snarfed") from the spool directory to an INBOX in mbox,
    1.74 +mx, mbx, tenex, and mtx formats.
    1.75 +
    1.76 +The following rules to select INBOX and its format apply in the order
    1.77 +given if "black box mode" is in effect:
    1.78 + 1) mx format is selected if file ~/INBOX/.mxindex exists.
    1.79 + 2) mbx format is selected if file ~/INBOX exists and is in mbx format.
    1.80 + 3) tenex format is selected if file ~/INBOX exists and is in tenex format.
    1.81 + 4) mtx format is selected if file ~/INBOX exists and is in mtx format.
    1.82 + 5) mmdf format is selected if file ~/INBOX exists and is in mmdf format.
    1.83 + 6) unix format is selected if file ~/INBOX exists and is in unix format.
    1.84 + 7) the dummy driver is selected if ~/INBOX does not exist, or exists
    1.85 +    and is empty.
    1.86 +
    1.87 +II. Special Name #mhinbox
    1.88 +
    1.89 +#mhinbox always refers to the directory "inbox" in the MH path, which
    1.90 +is declared in the ~/.mh_profile file.  Messages are automatically
    1.91 +transferred from the spool directory to #mhinbox mailbox.
    1.92 +
    1.93 +
    1.94 +III. Special Prefix "#mh/"
    1.95 +
    1.96 +Any name prefixed with "#mh/" always refers to a directory in the MH
    1.97 +path, which is declared in the ~/.mh_profile file.  For example, the name
    1.98 +"#mh/foo" refers to directory "foo" in the MH path.
    1.99 +
   1.100 +
   1.101 +IV. Special prefix "#news."
   1.102 +
   1.103 +Any name prefixed with "#news" always refers to a newsgroup.  For
   1.104 +example, the name "#news.comp.mail.misc" refers to newsgroup
   1.105 +"comp.mail.misc".
   1.106 +
   1.107 +
   1.108 +V. All Other Names
   1.109 +
   1.110 +The driver is selected by generating a file name from the mailbox
   1.111 +name, and then examining the data of the object with the resulting
   1.112 +name.  The formats are checked in order: mx, mbx, tenex, mtx, mmdf,
   1.113 +unix, and phile.  The dummy driver is selected if the file is empty.
   1.114 +
   1.115 +The file name is generated according to certain rules, based upon the
   1.116 +prefix of the mailbox name.  On UNIX, the following rules apply:
   1.117 +
   1.118 +Prefix		Interpretation of Suffix
   1.119 +------		------------------------
   1.120 +/		[black box] preceeds a user name; "/foo/bar" means
   1.121 +		 "black box user foo's mailbox bar"
   1.122 +		[not black box] preceeds an absolute path name.
   1.123 +~		[not black box] preceeds a user name; "~foo/bar" means
   1.124 +		 "UNIX user foo's mailbox bar"
   1.125 +#ftp/		preceeds UNIX user ftp's mailbox name
   1.126 +#public/	preceeds UNIX user imappublic's mailbox name
   1.127 +#shared/	preceeds UNIX user imapshared's mailbox name
   1.128 +
   1.129 +All other names are interpreted in the context of the UNIX user's home
   1.130 +directory (not black box), the black box user's black box directory
   1.131 +(black box), or UNIX user ftp's home directory (anonymous).
   1.132 +
   1.133 +The strings "..", "//", and /~ are forbidden in names in:
   1.134 + black box mode
   1.135 + #ftp, #public, or #shared names
   1.136 + anonymous users
   1.137 +
   1.138 +Anonymous users may only access:
   1.139 + INBOX (belonging to UNIX user ftp)
   1.140 + files in or below UNIX user ftp's home directory
   1.141 + #ftp, #news, and #public namespace
   1.142 +
   1.143 +VI. Driver Comparison
   1.144 +
   1.145 +The following information about the local file drivers is an
   1.146 +elaboration of a table compiled by Osma Ahvenlampi.
   1.147 +
   1.148 +Driver	CA	CE	UID	Kwd	Sub	NFS	Performance	Layout
   1.149 +------	--	--	---	---	---	---	-----------	------
   1.150 +unix	no	no	yes	yes	no	limited	fair		file
   1.151 + ;;; traditional UNIX format
   1.152 +mbox	no	no	yes	yes	no	limited	fair		file
   1.153 + ;;; traditional UNIX format, INBOX only, using ~/mbox with automatic
   1.154 + ;;; moving from the mail spool directory.
   1.155 +mmdf	no	no	yes	yes	no	limited	fair		file
   1.156 + ;;; default on SCO systems
   1.157 +mbx	yes	yes	yes	yes	no	no	very good	prefile
   1.158 + ;;; best performing local file driver; preferred format at UW
   1.159 +tenex	yes	no	no	limited	no	no	good		prefile
   1.160 + ;;; compatible with UNIX MM
   1.161 +mtx	yes	no	no	limited	no	no	very good	prefile
   1.162 + ;;; PC Pine standard format; compatible with TOPS-20; identical to tenex
   1.163 + ;;; but instead CRLF newlines instead of LF
   1.164 +mx	yes	buggy	yes	yes	yes	no	poor		ixdir
   1.165 + ;;; fullest function; *not* recommended due to performance problems and bugs;
   1.166 + ;;; to be redesigned/rewritten
   1.167 +mh	yes	no	no	no	yes	yes	very poor	dir
   1.168 + ;;; compatible with mh; #mhinbox for INBOX, #mh/ prefix for all other names
   1.169 +news	yes	no	yes	no	yes	yes	very poor	ixdir
   1.170 + ;;; local news spool access; #news. prefix for all names
   1.171 +phile	no	no	no	no	no	yes	good		file
   1.172 + ;;; reads arbitrary file as a single readonly message
   1.173 +
   1.174 +IMPORTANT: the "performance" ratings are relative to other drivers,
   1.175 +and not necessarily to other software which implements those formats.
   1.176 +They relate to the driver's performance in typical operations such as
   1.177 +an IMAP "FETCH ALL".
   1.178 +
   1.179 +Key to headings:
   1.180 +	CA:	concurrent read/write access
   1.181 +	CE:	expunge permitted in concurrent read/write access
   1.182 +	UID:	sticky UIDs
   1.183 +	Kwd:	keyword flags
   1.184 +	Sub:	subfolders
   1.185 +	NFS:	usable over network filesystems (NFS, AFS, etc.)
   1.186 +	Layout:	file - single file
   1.187 +		prefile - file with preallocated space for state
   1.188 +		dir - directory, messages are files
   1.189 +		ixdir - directory, messages are files, with helper index
   1.190 +
   1.191 +In addition, drivers imap, nntp, and pop3 support IMAP4rev1, NNTP, and
   1.192 +POP3 protocols respectively.