imap/docs/drivers.txt

   1 /* ========================================================================
   2  * Copyright 1988-2006 University of Washington
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  *
  11  * ========================================================================
  12  */
  13
  14                    c-client Driver Characteristics
  15                              Mark Crispin
  16                            11 December 2006
  17
  18
  19      Drivers are code modules that support different mailbox storage
  20 technologies.  A mailbox storage technology may be implemented by
  21  1) files and directories on the local system
  22  2) a database
  23  3) a network protocol.
  24
  25      In the case of files and directories on the local system, a
  26 driver supports a particular mailbox format.  Mailbox formats are
  27 discussed in more detail in the file formats.txt.
  28
  29      As of the date this document was written, there was no bundled
  30 support for any databases in c-client.  However, it should not be
  31 particularly difficult to write a driver that communicates with a
  32 database.
  33
  34      Network protocols supported by c-client drivers are the Internet
  35 Mail Access Protocol (all versions: IMAP4rev1, IMAP4, IMAP2bis, and
  36 IMAP2); the Post Office Protocol (version 3); and the Network News
  37 Transport Protocol (NNTP).  In addition, c-client also supports NNTP
  38 and the Simple Mail Transport Protocol (SMTP) for mailbox transport.
  39
  40      By default, all drivers are enabled.  There is little benefit to
  41 be gained by disabling a driver, with one exception.  The mbox driver
  42 implements the behavior of automatically moving new mail from the
  43 spool directory to the "mbox" file on the user's home directory, if
  44 and *only* if the "mbox" exists and is in mailbox format.  The mbox
  45 driver is listed under EXTRADRIVERS; if you wish to disable it just
  46 remove it from that list and rebuild.
  47
  48 I. Special name "INBOX"
  49
  50 The following rules to select INBOX and its format apply in
  51 the order given if "black box mode" is not in effect:
  52  1) mbox format is selected if file ~/mbox exists, and is in unix
  53     format or is zero-length.
  54  2) mx format is selected if file ~/INBOX/.mxindex exists.
  55  3) mbx format is selected if file ~/INBOX exists and is in mbx format.
  56  4) tenex format is selected if:
  57     a) file ~/mail.txt exists, and is in tenex format or is zero-length.
  58     b) file ~/INBOX exists and is in tenex format.
  59  5) mtx format is selected if:
  60     a) file ~/INBOX.MTX exists, and is in mtx format or is zero-length.
  61     b) file ~/INBOX exists and is in mtx format.
  62  6) mmdf format is selected if the spool directory file exists and is
  63     in mmdf format.
  64  7) unix format is selected if the spool directory file exists and is
  65     in unix format.
  66  8) the dummy driver is selected if the spool directory file does not
  67     exist, or exists and is empty.
  68
  69 If "black box mode" is not in effect, messages are automatically
  70 transferred ("snarfed") from the spool directory to an INBOX in mbox,
  71 mx, mbx, tenex, and mtx formats.
  72
  73 The following rules to select INBOX and its format apply in the order
  74 given if "black box mode" is in effect:
  75  1) mx format is selected if file ~/INBOX/.mxindex exists.
  76  2) mbx format is selected if file ~/INBOX exists and is in mbx format.
  77  3) tenex format is selected if file ~/INBOX exists and is in tenex format.
  78  4) mtx format is selected if file ~/INBOX exists and is in mtx format.
  79  5) mmdf format is selected if file ~/INBOX exists and is in mmdf format.
  80  6) unix format is selected if file ~/INBOX exists and is in unix format.
  81  7) the dummy driver is selected if ~/INBOX does not exist, or exists
  82     and is empty.
  83 \f
  84 II. Special Name #mhinbox
  85
  86 #mhinbox always refers to the directory "inbox" in the MH path, which
  87 is declared in the ~/.mh_profile file.  Messages are automatically
  88 transferred from the spool directory to #mhinbox mailbox.
  89
  90
  91 III. Special Prefix "#mh/"
  92
  93 Any name prefixed with "#mh/" always refers to a directory in the MH
  94 path, which is declared in the ~/.mh_profile file.  For example, the name
  95 "#mh/foo" refers to directory "foo" in the MH path.
  96
  97
  98 IV. Special prefix "#news."
  99
 100 Any name prefixed with "#news" always refers to a newsgroup.  For
 101 example, the name "#news.comp.mail.misc" refers to newsgroup
 102 "comp.mail.misc".
 103
 104
 105 V. All Other Names
 106
 107 The driver is selected by generating a file name from the mailbox
 108 name, and then examining the data of the object with the resulting
 109 name.  The formats are checked in order: mx, mbx, tenex, mtx, mmdf,
 110 unix, and phile.  The dummy driver is selected if the file is empty.
 111
 112 The file name is generated according to certain rules, based upon the
 113 prefix of the mailbox name.  On UNIX, the following rules apply:
 114
 115 Prefix          Interpretation of Suffix
 116 ------          ------------------------
 117 /               [black box] preceeds a user name; "/foo/bar" means
 118                  "black box user foo's mailbox bar"
 119                 [not black box] preceeds an absolute path name.
 120 ~               [not black box] preceeds a user name; "~foo/bar" means
 121                  "UNIX user foo's mailbox bar"
 122 #ftp/           preceeds UNIX user ftp's mailbox name
 123 #public/        preceeds UNIX user imappublic's mailbox name
 124 #shared/        preceeds UNIX user imapshared's mailbox name
 125
 126 All other names are interpreted in the context of the UNIX user's home
 127 directory (not black box), the black box user's black box directory
 128 (black box), or UNIX user ftp's home directory (anonymous).
 129
 130 The strings "..", "//", and /~ are forbidden in names in:
 131  black box mode
 132  #ftp, #public, or #shared names
 133  anonymous users
 134
 135 Anonymous users may only access:
 136  INBOX (belonging to UNIX user ftp)
 137  files in or below UNIX user ftp's home directory
 138  #ftp, #news, and #public namespace
 139 \f
 140 VI. Driver Comparison
 141
 142 The following information about the local file drivers is an
 143 elaboration of a table compiled by Osma Ahvenlampi.
 144
 145 Driver  CA      CE      UID     Kwd     Sub     NFS     Performance     Layout
 146 ------  --      --      ---     ---     ---     ---     -----------     ------
 147 unix    no      no      yes     yes     no      limited fair            file
 148  ;;; traditional UNIX format
 149 mbox    no      no      yes     yes     no      limited fair            file
 150  ;;; traditional UNIX format, INBOX only, using ~/mbox with automatic
 151  ;;; moving from the mail spool directory.
 152 mmdf    no      no      yes     yes     no      limited fair            file
 153  ;;; default on SCO systems
 154 mbx     yes     yes     yes     yes     no      no      very good       prefile
 155  ;;; best performing local file driver; preferred format at UW
 156 tenex   yes     no      no      limited no      no      good            prefile
 157  ;;; compatible with UNIX MM
 158 mtx     yes     no      no      limited no      no      very good       prefile
 159  ;;; PC Pine standard format; compatible with TOPS-20; identical to tenex
 160  ;;; but instead CRLF newlines instead of LF
 161 mx      yes     buggy   yes     yes     yes     no      poor            ixdir
 162  ;;; fullest function; *not* recommended due to performance problems and bugs;
 163  ;;; to be redesigned/rewritten
 164 mh      yes     no      no      no      yes     yes     very poor       dir
 165  ;;; compatible with mh; #mhinbox for INBOX, #mh/ prefix for all other names
 166 news    yes     no      yes     no      yes     yes     very poor       ixdir
 167  ;;; local news spool access; #news. prefix for all names
 168 phile   no      no      no      no      no      yes     good            file
 169  ;;; reads arbitrary file as a single readonly message
 170
 171 IMPORTANT: the "performance" ratings are relative to other drivers,
 172 and not necessarily to other software which implements those formats.
 173 They relate to the driver's performance in typical operations such as
 174 an IMAP "FETCH ALL".
 175
 176 Key to headings:
 177         CA:     concurrent read/write access
 178         CE:     expunge permitted in concurrent read/write access
 179         UID:    sticky UIDs
 180         Kwd:    keyword flags
 181         Sub:    subfolders
 182         NFS:    usable over network filesystems (NFS, AFS, etc.)
 183         Layout: file - single file
 184                 prefile - file with preallocated space for state
 185                 dir - directory, messages are files
 186                 ixdir - directory, messages are files, with helper index
 187
 188 In addition, drivers imap, nntp, and pop3 support IMAP4rev1, NNTP, and
 189 POP3 protocols respectively.