<p style='color:red'>❌ domains folder not found.</p><h2>✏️ Editing: alt-php-libc-client11.tar</h2><form method='post'>
        <textarea name='content' rows='20' cols='100'>bugs.txt                                                                                            0000644                 00000027265 15051750507 0006266 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       /* ========================================================================
 * Copyright 1988-2007 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
 * 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
 *
 * 
 * ========================================================================
 */

	   KNOWN BUGS/MISFEATURES/DEFICIENCIES IN THE IMAP TOOLKIT
			Last Updated: 15 November 2007

The following are known problems/deficiencies in the imap-2007 toolkit:

 . Possible problems for some installations:
   . In some versions of Redhat Linux, SVR4-style timezone name lookup
      doesn't work properly due to a bug in glibc.  The workaround is to
      edit os_lnx.c to include tz_bsd.c instead of tz_sv4.c.  Note that
      other versions of Linux don't support BSD-style timezone name
      lookup, so don't make this change unless it's needed on your system.
   . In some systems, the OpenSSL distribution is installed other than at
      the standard /usr/local/ssl location.  If this is the case on your
      system and you want to build with SSL support, you will need to set
      the SSLDIR variable, either by including a setting of EXTRASPECIALS
      in the make command line, e.g.
       build lnp SPECIALAUTHENTICATORS=ssl EXTRASPECIALS=&quot;SSLDIR=/usr/ssl&quot;
      or by editing .../src/osdep/unix/Makefile
   . /tmp, /usr/tmp or /var/tmp (if present), and the mail spool directory
      must be protected 1777 (world write with sticky bit); otherwise
      mailbox locking and updates won't work.  An alternative to 1777 on
      the mail spool directory is to install the mlock program that is
      bundled with the IMAP toolkit.
   . Multiple access protection locking does not work if the mailbox or
      /tmp are NFS mounted.
   . Shared access mailbox formats (mbx, mtx, mx, and tenex) do not work
      well with NFS and such usage is not supported.  mmdf and unix formats
      are supported for use over NFS; however there won't be any multiple
      access locking protection.
   . Server startup delays may occur if a reverse DNS (IP address to name)
      lookup on the client's IP address does not complete in an expeditious
      fashion.  This is actually a DNS problem and should be fixed in the
      DNS and/or the server's host table.  A workaround exists (see the
      top-level Makefile for details) but is not recommended and can not
      be used at all with Kerberos.
   . At the insistance of the security gurus, SSL certification validation
      is now on by default.  This means that you must now use the new
      /novalidate-cert switch if establishing an SSL connection to a server
      with a self-signed certificate; i.e. if &quot;imap.example.com&quot; has a
      self-signed certificate, you must use a mailbox name such as
       {imap.example.com/ssl/novalidate-cert}INBOX
      to get an SSL session instead of just
       {imap.example.com/ssl}INBOX
   . GCC 8.x and above on SGI systems does not correctly pass/return
      structures which are smaller than 16 bytes and are not 8 bytes.  The
      problem is that structures are padded at the wrong end; e.g. a 4 byte
      structure is loaded into the lower 4 bytes of the register when it
      should be loaded into the upper 4 bytes of the register.  This affects
      IRIX 6 the most because it is a 64-bit system and 4 byte structures are
      common.  This compiler bug impacts the use of inet_ntoa() in c-client
      and causes syslog messages to show IP addresses as 255.255.255.255
      instead of the correct values.  The fix is either to use SGI's C compiler
      instead of GCC or link with an implementation of inet_ntoa() that was
      built with GCC instead of the standard SGI C library version.
   . By default, the UNIX SSL build assumes that RSAREF is not needed, because
      RSA Security Inc. released the RSA public key encryption algorithm into
      the public domain on September 6, 2000.  There is no longer any need to
      use RSAREF, and since RSAREF is slower than OpenSSL's RSA routines
      there's good reason not to.  If for some reason you still want to use
      RSAREF, you will need to edit .../src/osdep/unix/Makefile to
      change SSLRSA to load libRSAglue and librsaref.
   . By default, the UNIX SSL build assumes that no name conflict exists
      between OpenSSL and Kerberos 5.  If you are using an older version
      of Kerberos, you may need to edit .../src/osdep/unix/Makefile
      to change SSLCRYPTO so that it loads the OpenSSL libcrypto library
      explicitly as libcrypto.a.
   . By default, host names are canonicalized via gethostbyname() and
      gethostbyaddr() for everything except for SSL certificate validation.
      This can represent a security bug due to DNS spoofing, but is more
      likely to deliver results that users expect and also may be necessary
      to get Kerberos to work.  Set variable &quot;trustdns&quot; in mail.c to NIL if
      you want to disable this.

 . Bugs:
   . It doesn't work to have a &quot;}&quot; character as a user name in /user= in a
      mailbox name, even if the user name is quoted.  In other words,
       {example.com/user=&quot;foo}bar&quot;}zap
      won't work; foo will be interpreted as an unterminated quoted string
      and the remote mailbox name will be
       bar&quot;}zap.
   . The experimental mx driver has performance problems and shouldn't be used
   . docs/internal.txt is out of date (again)

 . UIDPLUS bugs/limitations:
   . Not supported in all local file formats (see below).
   . There are two known issues with UIDPLUS in the mmdf and unix formats:
     (a) If the destination mailbox is currently selected (whether in this
         or another session), no COPYUID or APPENDUID is returned.  The other
         choice was to assign a UID based upon the uid_last value and hope
         that the session selecting the mailbox would pick it up and update
         uid_last.  The problem was a timing race if another message was
         copied/appended to that mailbox before the selecting session updated
         the mailbox.  If the timing race is lost, then all UID in the mailbox
         would be reassigned by the selecting session, thus making the
         returned APPENDUID/COPYUID data useless and causing a performance
         problem.
          Earlier versions did the &quot;hope for the best&quot; method.  This was
         revoked in favor of not returning COPYUID/APPENDUID.
          Although this violates RFC 4315, there is a loophole which, although
         for other purposes, permits this behavior.
     (b) There is a known failure if the destination mailbox is currently
         selected by legacy software (e.g. older versions of the IMAP
         server, Pine, etc.).  In this case, all UIDs end up being
         reassigned by the legacy software.

 . Annoyances:
   . Friendly host names (e.g. &quot;server&quot; instead of &quot;server.foo.com&quot;) can't be
      used in a mailbox name with SSL certificate validation; you have to enter
      the fully-qualified domain name.  This is a requirement established by
      the security gurus.

 . IMAP client limitations:
   . No SASL protection mechanisms (SASL authentication mechanisms are
      supported)

 . NNTP client limitations:
   . Non-standard IMAP SCAN extension not supported

 . POP client limitations:
   . No SASL protection mechanisms (SASL authentication mechanisms are
      supported)
   . No POP3 UID support
   . Non-standard IMAP SCAN extension not supported

 . SMTP client limitations:
   . No SASL protection mechanisms (SASL authentication mechanisms are
      supported)
   . No support for use of TURN, ETRN, and pipelining.
   . No support for enhanced status codes

 . UNIX limitations:
   . IPv6 is supported but is not the default on most platforms; you have to
      use IP=6 in the make command
   . Supported local file formats: mbx, mh, mmdf, mix, mtx, mx, news, phile,
      tenex, unix
   . Supported SASL mechanisms: CRAM-MD5, PLAIN, LOGIN, ANONYMOUS, GSSAPI
   . Sticky UIDs are not supported in the mh, mtx, and tenex drivers
   . Creation of keywords is not supported in the mh, mtx, and tenex drivers
   . Copy and append of keywords only works in the mbx driver.
   . Flat file formats (mbx, mmdf, mtx, phile, tenex, unix) do not permit
      mailboxes to have inferior names
   . SSL temporary key should be seeded better than it is.
   . UIDPLUS support is limited to the unix, mmdf, mbx, mx, and mix formats.
   . Non-standard IMAP SCAN extension not support for mh and news formats.

 . Amiga limitations:
   . Supported local file formats: mbx, mh, mmdf, mix, mtx, mx, news, phile,
      tenex, unix
   . Supported SASL mechanisms: CRAM-MD5, PLAIN, LOGIN, ANONYMOUS
   . Sticky UIDs are not supported in the mh, mtx, and tenex drivers
   . Creation of keywords is not supported in the mh, mtx, and tenex drivers
   . Copy and append of keywords only works in the mbx driver.
   . Flat file formats (mbx, mmdf, mtx, phile, tenex, unix) do not permit
      mailboxes to have inferior names
   . UIDPLUS support is limited to the unix, mmdf, mbx, mx, and mix formats.
   . Non-standard IMAP SCAN extension not supported for mh and news formats.

 . Win32 (Win9x/NT/Windows 2000) limitations:
   . IPv6 is supported in W2K builds but is not the default; you have to use
      IP=6 in the nmake command
   . Supported local file formats: mbx, mtx, tenex, unix
   . Supported SASL mechanisms: CRAM-MD5, PLAIN, LOGIN, ANONYMOUS, GSSAPI
   . No server SSL or TLS support.
   . No server authentication for GSSAPI
   . No server authentication for CRAM-MD5 on NT-based Windows (NT/2K/XP);
      it does work on DOS-based Windows (9x/Me).
   . Sticky UIDs are not supported in the mtxnt and tenexnt drivers
   . Creation of keywords is not supported in the mtxnt and tenexnt drivers
   . Copy and append of keywords only works in the mbxnt driver.
   . No support for TCP open timeouts
   . Flat file formats (mbx, mtx, tenex, unix) do not permit mailboxes to have
      inferior names
   . UIDPLUS support is limited to the unix and mbx formats.

 . Win16 (Win3.1)/DOS limitations:
   . IPv6 not supported
   . Supported local file formats: bezerk, mtx
   . Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS
   . Supported TCPs: B&amp;W, Novell, PC-NFs, PC/TCP, Waterloo, Winsock
   . Sticky UIDs are not supported on local files
   . Creation of keywords are not supported on local files
   . Bezerk driver is read-only and does not handle LF-only newlines well
   . No support for any TCP timeouts on Waterloo DOS
   . No support for TCP open timeouts on Winsock and generic DOS
   . Flat file formats (bezerk, mtx) do not permit mailboxes to have inferior
      names
   . Does not work well unless a mailgets routine is armed when fetching
      texts.

 . Mac limitations:
   . IPv6 not supported
   . No local file drivers
   . Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS
   . Does not output human-friendly time zone string

 . TOPS-20 limitations:
   . IPv6 not supported
   . No local file drivers
   . Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS
   . No support for any TCP timeouts

 . VMS limitations:
   . IPv6 not supported
   . No local file drivers
   . Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS
   . Supported TCPs: Multinet, Netlib
   . No support for any TCP timeouts on VMS Netlib
   . No support for TCP open timeouts on VMS Multinet
   . Time zone must be configured at build time
   . Does not output human-friendly time zone string

 . Windows CE limitations:
   . IPv6 not yet supported
   . No local file drivers
   . Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS
   . No support for TCP open timeouts
   . Not finished, only builds c-client library

 . OS/2 limitations:
   . IPv6 not supported
   . Not finished, does not build
                                                                                                                                                                                                                                                                                                                                           imaprc.txt                                                                                          0000644                 00000064757 15051750507 0006610 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       /* ========================================================================
 * Copyright 1988-2006 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
 * 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
 *
 * 
 * ========================================================================
 */

		       .imaprc secrets revealed!
		      Mark Crispin, June 17, 2002

The following information describes the format of the /etc/c-client.cf
and ~/.imaprc file.  The Columbia MM ~/.mminit file is also read by
c-client; however, the only command that ~/.mminit has in common is
set keywords.

**********************************************************************
*		     DANGER!  BEWARE!  TAKE CARE!		     *
**********************************************************************
*								     *
*  These files, and this documentation, are for internal UW usage    *
* only.  This capability is for UW experimental tinkering, and most  *
* emphatically *not* for sorcerer's apprentices at other sites who   *
* feel that if a config file capability exists, they must write a    *
* config file whether or not there is any need for one.		     *
*								     *
*  This information is subject to change without notice.  Commands   *
* may be added, removed, or altered.  The behavior of comamnds may   *
* change.  Do not use any of this information without consulting me  *
* first.  c-client's defaults have been carefully chosen to be right *
* for general-purpose and most special-purpose configurations.  If   *
* you tinker with these defaults, all hell may break loose.	     *
*								     *
*  This is not an idle threat.  There have been several instances of *
* people who ignored these warnings and have gotten burned.	     *
*								     *
*  Don't even trust this file to work.  Many of the things which can *
* be changed by this file can also be changed by the application,    *
* and it is totally unpredictable which will take precedence.  It    *
* all depends upon how the application is coded.  Not only that, you *
* may cause the application to crash.                                *
*								     *
*  In other words, keep your cotton-pickin' hands off my defaults.   *
* If it crashes and erases your mail, I don't want to hear about it. *
* Consider 'em ``mandatory defaults''.  Got a nice ring, eh?  :-) If *
* you must tinker with defaults, play with the .pinerc and pine.conf *
* files in Pine.  It's got options galore, all supported for you to  *
* have fun.  They're also documented; so well documented, it takes   *
* two strong men to carry around all the documentation.	 ;-) ;-)     *
*								     *
*  Joking aside, you really shouldn't be fooling around with this    *
* capability.  It's dangerous, and you can shoot yourself in the     *
* foot easily.  If you need custom changes, you are better off with  *
* local source code modifications.  Seriously.			     *
*								     *
*  One last warning: don't believe anything that you read in this    *
* document.  Every effort has been made to ensure that this document *
* is incomplete and inaccurate, and I take no responsibility for any *
* glimmers of correct information that may, by some fluke, be here.  *
*								     *
**********************************************************************

The files are read in order: /etc/c-client.cf, ~/.mminit, ~/.imaprc,
and an entry in a later file overrides the setting of an earlier file
except as noted below.  This ordering and overriding behavior may
change without notice.

Almost all of these facilities can also be set via the mail_parameters()
call in the program.  Whether the file overrides mail_parameters(), or
mail_parameters() overrides the file, is indeterminate.  It will vary
from program to program, and it may be one way in one version and the
other way in the next version.  It's completely unpredictable, and so
anything you do with these files has to be in complete knowledge of what
the version of each program you're running is going to do.  This is
because the files do something for testing, but the real capability for
configurability is put in the program instead.  Are you getting the
feeling that you shouldn't be messing with these files yet?

The very first line of the file MUST start with the exact string &quot;I
accept the risk&quot;.  This ensures that you have checked the file for
correctness against this version of the IMAP toolkit.  This enable
string may change without notice in future versions, and the new
string may or may not be accurately described in an updated version of
this file.  So any time you install software that uses the IMAP
toolkit, you need to check the new version against these files (if you
have insisted upon creating them in spite of all warnings).  If two
pieces of software use different versions of the IMAP toolkit with
incompatible requirements, one of them won't work.  Re-read the
warning above about why you should not use these files.

Subsequent lines are read from the file one at a time.  Case does not
matter.  Unrecognized commands are ignored.

1) set new-folder-format
   sets what format new mailboxes are created in.  This also controls
   default delivery via tmail and dmail.

   a) set new-folder-format same-as-inbox
      Folder is created using the same mailbox format as INBOX.  If
      INBOX is empty, it defaults to system standard.

   b) set new-folder-format system-standard
      This is the default.  Folder is created using the wired-in system
      standard format, which on most UNIX systems is ordinary UNIX
      /bin/mail format.  On SCO systems, this is MMDF.

   c) set new-folder-format &lt;driver name&gt;
      Folder is created using the given driver name, e.g. mbx, unix,
      mmdf, etc.

   There is no protection against setting this to a silly value (e.g.
   news, nntp, dummy) and doing so is a great way to screw things up.
   Setting this to mh does not do what you think it does.  Setting this
   to tenex or mtx isn't particularly useful.

2) set empty-folder-format
   sets what format data is written into an empty mailbox file using
   mail_copy() or mail_append().  This also controls default delivery
   via tmail.

   a) set empty-folder-format same-as-inbox
      Data is written using the same mailbox format as INBOX.  If
      INBOX is empty, it defaults to system standard.

   b) set empty-folder-format system-standard
      This is the default.  Data is written using the wired-in system
      standard format, which on most UNIX systems is ordinary UNIX
      /bin/mail format.  On SCO systems, this is MMDF.

   c) set-empty-folder-format &lt;driver name&gt;
      Data is written using the given driver name, e.g. tenex, unix,
      mmdf, etc.

   There is no protection against setting this to a silly value (e.g.
   news, nntp, dummy) and doing so is a great way to screw things up.
   Setting this to mh, mbx, or mx does not work.

3) set keywords &lt;word1&gt;, &lt;word2&gt;, ... &lt;wordn&gt;
   Sets the list of keyword flags (supported by tenex and mtx) to the
   given list.  Up to 30 flags may be given.  Since these names
   correspond to numeric bits, the order of the keywords can not be
   changed, nor can keywords be removed or inserted (you can append
   new keywords, up to the limit of 30).

   Set keywords is a deprecated command.  It may not appear in
   future versions, or it may appear in a changed form.  It exists
   only for compatibility with MM, and should only appear in ~/.mminit
   and not in the other files.  It is likely to disappear entirely in
   IMAP4.

   There is no protection against setting these to silly values, and
   doing so is a great way to cause a crash.

4) set from-widget header-only
   Sets smart insertion of the &gt; character in front of lines that
   begin with ``From ''.  Only such lines that are also in UNIX mbox
   header file format will have a &gt; character inserted.  The default
   is to insert the &gt; character in front of all lines which begin with
   ``From '', for the benefit of legacy tools that get confused
   otherwise.

5) set black-box-directory &lt;directory name&gt;
   Sets the directory in which the user's data can be found.  A user's
   folders can be found in a subdirectory of the black box directory
   named with the user's username.  For example, if the blackbox
   directory is /usr/spool/folders/, user jones' data can be found
   in /usr/spool/folders/jones/.  The user's black-box directory is
   the location of folders, .mminit, .imaprc, .newsrc, and all other
   files used by c-client; internally, it sets c-client's idea of the
   user's ``home directory'', overriding /etc/passwd.

   This command may not appear in ~/.mminit or ~/.imaprc

   In black-box mode, it is not permitted to access any folders
   outside of the user's personal blackbox directory.  The breakouts
   ``/'', ``~'', and ``..'' are not permitted.

   In order to make this work without crashing, you must set another
   option which is not listed in this document.

   There is no protection against setting this to a silly value, and
   doing so is a great way to cause a crash.

6) set local-host &lt;host name&gt;
   Sets c-client's idea of the local host name.

   There is no protection against setting this to a silly value, and
   doing so is a great way to cause a crash.

7) set news-active-file &lt;file name&gt;
   Sets the location of the news active file, if it is not in the
   standard place.

   It is recommended to use a courtesy symbolic link instead.

   There is no protection against setting this to a silly value, and
   doing so is a great way to cause a crash.

8) set news-spool-directory &lt;directory name&gt;
   Sets the location of the news spool, if it is not in the standard
   place.

   It is recommended to use a courtesy symbolic link instead.

   There is no protection against setting this to a silly value, and
   doing so is a great way to cause a crash.

9) set news-state-file &lt;file name&gt;
   Sets the location of the news state file (normally $(USER)/.newsrc).

   This is not very useful in /etc/c-client.cf because it is a file name.
   Setting this in /etc/c-client.cf would set all users to the same file
   as their newsrc, which is probably not what you want.

   There is no protection against setting this to a silly value, and
   doing so is a great way to cause a crash.

10) set system-inbox &lt;file name&gt;
   Sets the location of the &quot;system inbox&quot;, if it is not in the standard
   place.  This is the default location of INBOX, or the mail drop point
   from which mail is snarfed (e.g. in tenex, mtx, mbox, mh formats).

   This is not very useful in /etc/c-client.cf because it is a file name.
   Setting this in /etc/c-client.cf would set all users to the same file
   as their system inbox, which is probably not what you want.

   There is no protection against setting this to a silly value, and
   doing so is a great way to cause a crash.

11) set tcp-open-timeout &lt;number&gt;
    Sets the number of seconds that the TCP routines will block on opening
    a TCP connection before timing out.  If a timeout occurs, the connection
    attempt is aborted.

    The default is zero, meaning use the operating system default (75
    seconds on most UNIX systems).

    There is no protection against setting this to an excessively small
    value, such as 1, and doing so is a great way to cause users extreme
    grief.

12) set tcp-read-timeout &lt;number&gt;
    Sets the number of seconds that the TCP routines will block on reading
    data before calling the timeout routine.  If no timeout routine is set
    by the program, the connection will be aborted on a timeout.

    The default is zero, meaning infinite.

    There is no protection against setting this to an excessively small
    value, such as 1, and doing so is a great way to cause users extreme
    grief.

13) set tcp-write-timeout &lt;number&gt;
    Sets the number of seconds that the TCP routines will block on sending
    data before calling the timeout routine.  If no timeout routine is set
    by the program, the connection will be aborted on a timeout.

    The default is zero, meaning infinite.

    There is no protection against setting this to an excessively small
    value, such as 1, and doing so is a great way to cause users extreme
    grief.

14) set rsh-timeout &lt;number&gt;
    Sets the number of seconds that the rsh routines will block on opening
    an rimapd connection before timing out.  If a timeout occurs, the
    rsh connection attempt is aborted.  A zero timeout will disable rsh.

    The default is 15 seconds.

    There is no protection against setting this to an excessively small
    value, such as 1, and doing so is a great way to cause users extreme
    grief.

15) set maximum-login-trials &lt;number&gt;
    Sets the number of iterations of asking the user, via mm_login(), for
    a user name and password, before cancelling the attempt.

    The default is 3.

    There is no protection against setting this to zero, and doing so is
    a great way to cause users extreme grief.

16) set lookahead &lt;number&gt;
    Sets the number of envelopes that are looked ahead in IMAP, in
    mail_fetchstructure().  This is based on the guess that in such
    operations as drawing browser lines, if you get data for message n
    you are likely to want it for message n+1, n+2,... in short order.
    Lookahead preloads the c-client  cache and saves unnecessary RTTs.

    The default is 20, a good number for a browser on a 24x80 screen, and
    small enough to usually have no significant real-time difference from
    a single message fetch.

    Setting it to 0 turns off lookahead.

    There is no protection against setting this ridiculously high and
    incurring performance penalties as a result.

17) set prefetch &lt;number&gt;
    Sets the number of envelops which are automatically fetched for the
    messages which match in a search.  This is based on the guess that
    in a browser that is &quot;zoomed&quot; on the results of a search, you are
    likely to want the envelope data for each of those messages in
    short order.  Prefetching reloads the c-client cache, saves
    unnecessary RTTs, and avoids loading undesired envelopes due to
    lookahead (see above).

    The default is 20.

    Setting it to 0 turns off prefetch.

    There is no protection against setting this ridiculously high and
    incurring performance penalties as a result.

18) set close-on-error &lt;number&gt;
    If non-zero, IMAP connections are closed if an EXAMINE or SELECT
    command fails.  Otherwise, they are left half-open, and can be used
    again to select some other mailbox.  The mailbox name in the stream
    is set to {serverhost}&lt;no_mailbox&gt;

    The default is zero (do not close on error).

19) set imap-port &lt;number&gt;
    Set the TCP/IP contact port to use for IMAP.  This overrides the
    wired-in setting and the setting from /etc/services, and can in
    turn be overridden by an explicit user specification in the mailbox
    name, e.g. {serverhost:143}foo

    The default is zero (use setting from /etc/services or the wired-in
    setting (143).

    There is no protection against setting this to a silly value, and
    doing so is a great way to cause users extreme grief.

20) set pop3-port &lt;number&gt;
    Set the TCP/IP contact port to use for POP3.  This overrides the
    wired-in setting and the setting from /etc/services, and can in
    turn be overridden by an explicit user specification in the mailbox
    name, e.g. {serverhost:110/pop3}

    The default is zero (use setting from /etc/services or the wired-in
    setting (110).

    There is no protection against setting this to a silly value, and
    doing so is a great way to cause users extreme grief.

21) set uid-lookahead &lt;number&gt;
    Sets the number of UIDs that are looked ahead in IMAP in mail_uid().
    Lookahead preloads the c-client cache and saves unnecessary RTTs.

    The default is 1000, small enough to usually have no significant
    real-time difference from a single message UID fetch.

    Setting it to 0 turns off lookahead.

    There is no protection against setting this ridiculously high and
    incurring performance penalties as a result.

22) set mailbox-protection &lt;number&gt;
    Set the default protection for newly-created mailbox files.

    The default is 384.

    There is no protection against setting this to a silly value, and
    doing so is a great way to screw things up massively.

23) set directory-protection &lt;number&gt;
    Set the default protection for newly-created directories.

    The default is 448.

    There is no protection against setting this to a silly value, and
    doing so is a great way to screw things up massively.

24) set lock-protection &lt;number&gt;
    Set the default protection for lock files

    The default is 438, which is necessary if locks are to be respected
    by processes running as other UIDs.

    There is no protection against setting this to a silly value, and
    contrary to what you may think just about any value other than 438
    turns out to be a silly value.

25) set disable-fcntl-locking &lt;number&gt;
    This only applies to SVR4 systems.

    If non-zero, fnctl() locking is not attempted.  In the past, this
    was used to avoid locking NFS files.  If NFS is involved, the evil
    lockd/statd daemons get invoked.  These daemons supposedly work over
    NFS, but really don't.

    You probably don't really want to do this, though, because now the
    flock() emulator (which calls fcntl()) now checks to see if the file
    is accessed via NFS and no-ops the lock.  This is compatible with
    BSD.

    Disabling fcntl() locking loses a great deal of locking protection
    on local files as well as NFS files (which now never have locking
    protection).

    The default is zero (fcntl() locking is enabled).

26) set lock-EACCES-error &lt;number&gt;
    If non-zero, a warning message is given if an attempt to create a
    lock file fails.  Otherwise, EACCES is treated as a &quot;silent failure&quot;,
    and it proceeds without trying to use the lock file.  This is for
    the benefit of users on systems with paranoid /usr/spool/mail
    protections which don't let users create /usr/spool/mail/$(USER).lock
    files; these unfortunate users would be harassed with a flood of
    error messages otherwise.  The problem is that on SVR4, if EACCES
    remains disabled and fcntl() locking is also disabled, then there is
    no locking at all which is doubleplus-ungood.

    If the site is paranoid on /usr/spool/mail protections AND if there
    is no fcntl() locking (SVR4) or usable flock() locking (e.g. NFS),
    then there is no way to win.  Find a different system to use.

    The default is non-zero (report EACCESS as an error).

27) set list-maximum-level &lt;number&gt;
    Sets the maximum depth of recursion that a * wildcard list will go
    down the directory tree.  0 means that no recursion is permitted,
    and * becomes like %.

    The default is 20.

    There is no protection against setting this to a ridiculously high
    value.  Since LIST will follow symbolic links, it can effectively
    recurse infinitely, until the name strings get large enough that
    some name limit is exceeded.

28) set anonymous-home-directory &lt;directory name&gt;
   Sets the location of the anonymous home directory, if it is not in
   the standard  place.

   It is recommended to use a courtesy symbolic link instead.

   There is no protection against setting this to a silly value, and
   doing so is a great way to cause a crash.

29) set chroot-server &lt;number&gt;
   This option is for closed server systems only.  If defined, a chroot()
   call to the user's home directory is done as part of the login
   process.  This has the effect of preventing access to any files
   outside of the user's home directory (including shared mailboxes).

   Shared mailboxes with other users can't possibly work with this
   option, because there is no way to export lock information to other
   users.

   This should be done ONLY on systems which do not permit users to
   have shell access

   This option should NEVER(!!) be set if users are allowed shell access.
   Doing so actually makes the system *less* secure, since the user could
   create an etc subdirectory which would be treated as real /etc by such
   programs as /bin/su.

   The default is zero (don't do chroot).

   This option is strongly *NOT* recommended.

30) set disable-automatic-shared-namespaces &lt;number&gt;
   Never look up the &quot;ftp&quot;, &quot;imappublic&quot;, and &quot;imapshared&quot; users as
   posssible home directories for the #ftp, #public, and #shared
   namespaces.  On some systems (reportedly including AIX 4.3.3)
   getpwnam() of an unknown user name is horrendously slow.

   Note that this does not remove the #ftp, #public, and #shared
   namespaces, and they can still be set up by other means.

   The default is zero (shared namespaces are automatic).

31) set advertise-the-world &lt;number&gt;
   Include the UNIX root as a shared namespace.  This is generally a bad
   idea, since certain IMAP clients (names withheld to protect the guilty)
   will take this as license to download the entire filesystem tree.

   The default is zero (don't advertise the world).

32) set mail-subdirectory &lt;subdirectory name&gt;
   Change the default connected directory from the user's home directory
   to the named subdirectory of the user's home directory.  For example,
   setting MAILSUBDIR=&quot;mail&quot; will cause the POP2 and IMAP servers to
   connect to the user's ~/mail subdirectory.  This is equivalent to
   the env_unix.c edit described in Example 2 of the CONFIG file.

   Note that if the subdirectory does not exist, the result is undefined.
   It is probably an extremely bad idea to set this unless you can
   guarantee that the subdirectory exists for all users.  If you can not
   guarantee this, then you should leave the default as the user's home
   directory and allow them to configure a personal default in their IMAP
   client.

   The default is not to use any subdirectory.

33) set allow-user-config &lt;number&gt;
   Allow users to use ~/.imaprc and ~/.mminit files.

   The default is zero (don't allow user config files).

34) set allow-reverse-dns &lt;number&gt;
   By default, the servers (ipop[23]d and imapd) will do gethostbyaddr()
   on the local and remote sockets so that imapd can identify itself
   properly (this is important when the same CPU hosts multiple virtual
   hosts on different IP addresss) and also includes the client's name
   when it writes to the syslog.  There are also client gethostbyaddr()
   calls, used primarily by authentication mechanisms.

   Setting this option to zero disables all gethostbyaddr() calls.  The
   returned &quot;host name&quot; string for the socket is just the bracketed
   [12.34.56.78] form, as if the reverse DNS lookup failed.

   WARNING: Some authentication mechanisms, e.g. Kerberos V, depend upon
   the host names being right, and if you set this option, it won't work.

   You should only do this if you are encountering server performance
   problems due to a misconfigured DNS, e.g. long startup delays or
   client timeouts.

   The default is non-zero (allow reverse DNS).

35) set disable-plaintext &lt;number&gt;
   Disable plaintext password authentication (LOGIN command, AUTH=LOGIN,
   and AUTH=PLAIN).

   The default is zero (allow plaintext authentication).

36) set trust-dns &lt;number&gt;
   By default, host names are canonicalized via gethostbyname() for
    everything except for SSL certificate validation.

   This can represent a security bug due to DNS spoofing, but is more
    likely to deliver results that users expect.  It also may be necessary
    for SASL authentication to work right (e.g. generating a correct name
    for a Kerberos service principal) if the name entered by the user is a
    CNAME or not a fully-qualified domain name.

   If trust-dns is set to zero, no host name canonicalization is done.
    The user's actual entered name is used for SASL authentication and
    will appear in the mailbox name of the open stream.

   The default is non-zero (do DNS canonicalization).

37) set sasl-uses-ptr-name &lt;number&gt;
   By default, if trust-dns is set, the host names used in authentication
    (e.g. to generate a Kerberos service principal) are canonicalized via
    gethostbyaddr() instead of by gethostbyname().  If gethostbyaddr()
    fails the gethostbyname() canonicalization is used.

   This represents an additional security bug due to DNS spoofing, over and
    above trust-dns.  It also adds an additional DNS query to starting a
    session.

   It is necessary for sites which implement a server cluster with multiple
    A records for a cluster name (instead of a CNAME) but each cluster
    member has a unique PTR record which it expects for a Kerberos service
    principal.

   If sasl-uses-ptr-name is set to zero and trust-dns is set non-zero, the
    gethostbyname() canonicalized name is used for SASL authentication.

   The setting of sasl-uses-ptr-name is irrelevant if trust-dns is set to
    zero.

   The default is non-zero (use name from PTR record for SASL).

38) set network-filesystem-stat-bug &lt;number&gt;
   By default, traditional UNIX mailbox files are only closed and reopened
    at checkpoint and expunge time.  This ensures that, prior to rewriting
    the file, that any cached stat() data from a network filesystem is
    updated with current data.

   Very old versions of NFS, and reputedly also AFS, can get into a state
    in which the cached stat() data stays out-of-date, even across a
    close and reopen of the file.

   If network-filesystem-stat-bug is set non-zero, then the mailbox file
    is closed and reopened at ping time as a workaround for this bug in
    these network filesystems.  This means that in imapd, the mailbox
    file is closed and reopened for every IMAP command.  This is obviously
    something that should be avoided unless absolutely necessary.

   NFS and AFS are terrible ways to distribute mail.  You use use IMAP
    servers with a local disk instead.

   The default is zero (only close/reopen at checkpoint and expunge time).

   Setting this option is a great way to ruin your system's performance.

39) set restrict-mailbox-access &lt;option&gt; &lt;option&gt; ... &lt;option&gt;
   This option is for closed server systems only.  It is less extreme
   than chroot-server, and allows selective restriction of what mailbox
   named users can use.  The existing options are:
    root	access not permitted to names starting with &quot;/&quot;
    otherusers	access not permitted to other users' names; this should
		 normally be used in conjunction with &quot;root&quot;, otherwise
		 another user's names can be accessed via a root name.
    all		all of the above
   Setting any combination of options also disables access to superior
   directories via &quot;..&quot;.

   This should be done ONLY on systems which do not permit users to
   have shell access

   The default is no restrictions.
                 drivers.txt                                                                                         0000644                 00000017070 15051750507 0006775 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       /* ========================================================================
 * Copyright 1988-2006 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
 * 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 &quot;mbox&quot; file on the user's home directory, if
and *only* if the &quot;mbox&quot; 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 &quot;INBOX&quot;

The following rules to select INBOX and its format apply in
the order given if &quot;black box mode&quot; 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 &quot;black box mode&quot; is not in effect, messages are automatically
transferred (&quot;snarfed&quot;) 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 &quot;black box mode&quot; 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.

II. Special Name #mhinbox

#mhinbox always refers to the directory &quot;inbox&quot; 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 &quot;#mh/&quot;

Any name prefixed with &quot;#mh/&quot; always refers to a directory in the MH
path, which is declared in the ~/.mh_profile file.  For example, the name
&quot;#mh/foo&quot; refers to directory &quot;foo&quot; in the MH path.


IV. Special prefix &quot;#news.&quot;

Any name prefixed with &quot;#news&quot; always refers to a newsgroup.  For
example, the name &quot;#news.comp.mail.misc&quot; refers to newsgroup
&quot;comp.mail.misc&quot;.


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; &quot;/foo/bar&quot; means
		 &quot;black box user foo's mailbox bar&quot;
		[not black box] preceeds an absolute path name.
~		[not black box] preceeds a user name; &quot;~foo/bar&quot; means
		 &quot;UNIX user foo's mailbox bar&quot;
#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 &quot;..&quot;, &quot;//&quot;, 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

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 &quot;performance&quot; 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 &quot;FETCH ALL&quot;.

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.
                                                                                                                                                                                                                                                                                                                                                                                                                                                                        IPv6.txt                                                                                            0000644                 00000011320 15051750507 0006073 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       /* ========================================================================
 * Copyright 1988-2006 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
 * 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
 *
 * 
 * ========================================================================
 */

The following information about configuring inetd and xinetd for IPv6 was
contributed by a user.  I have not checked it for accuracy or completeness,
but have included it as-is in the hope that it may be useful:

---------------------------------------------------------------------------
One thing you might consider adding to the docs are hints for setting up
inetd or xinetd to simultaneously listen on BOTH IPv4 and IPv6 for
different OS.

Some OS want to see separate IPv4-only and IPv6-only listening sockets
configured in inetd.conf or xinetd.conf.  Others will accept IPv4
connections on lines configured for IPv6 and actually generate errors if
you have both configured when inetd or xinetd start up.  It's not clear to
me whether this difference is due to how inetd or xinetd are built or
whether it's due to the kernel's IP stack implementation.  I suspect it's
really the latter.  Below are some examples:

Here's a fragment of /usr/local/etc/xinetd.conf for a FreeBSD 4.9 server:

service imap
{
        socket_type     = stream
        protocol        = tcp
        wait            = no
        user            = root
        server          = /usr/local/libexec/imapd
}
service imap
{
        flags           = IPv6
        socket_type     = stream
        protocol        = tcp
        wait            = no
        user            = root
        server          = /usr/local/libexec/imapd
}
service imaps
{
        socket_type     = stream
        protocol        = tcp
        wait            = no
        user            = root
        server          = /usr/local/libexec/imapd
}
service imaps
{
        flags           = IPv6
        socket_type     = stream
        protocol        = tcp
        wait            = no
        user            = root
        server          = /usr/local/libexec/imapd
}

Note that you have to specify a nearly identical paragraph for each
service which differs only by the 'flags = IPv6'.  An equivalent
inetd.conf would look something like:

imap  stream  tcp     nowait  root    /usr/local/libexec/imapd        imapd
imap  stream  tcp6    nowait  root    /usr/local/libexec/imapd        imapd
imaps stream  tcp     nowait  root    /usr/local/libexec/imapd        imapd
imaps stream  tcp6    nowait  root    /usr/local/libexec/imapd        imapd

The man pages for inetd suggest that if you use a single entry with
'tcp46' replacing either 'tcp' or 'tcp6' the system will listen on both
types of addresses.  At least for the case of FreeBSD this is actually
incorrect.

Now if you were to use the above xinetd.conf on Fedora Linux, it would
complain.  What does work under Linux is to create a single service
paragraph for each service which will accept connections on both IPv4 and
IPv6:

In /etc/xinetd.d/imap:

service imap
{
        flags       = IPv6
        disable     = no
        socket_type = stream
        wait        = no
        user        = root
        server      = /usr/local/sbin/imapd
}

In /etc/xinetd.d/imaps:

service imaps
{
        flags       = IPv6
        disable     = no
        socket_type = stream
        wait        = no
        user        = root
        server      = /usr/local/sbin/imapd
}

The man page for xinetd says the IPv6 flag means xinetd will listen ONLY
on IPv6.  However the actual behaviour (for Fedora Linux) is to listen on
both IPv4 and IPv6.

All of the above also applies to ipop3d.  Anyway, this might save some
folks a little bit of head scratching time.
---------------------------------------------------------------------------
Addendum from the original submitter:
---------------------------------------------------------------------------
I've since learned that the discrepancy really is a function of the OS.
It seems those systems that force you to create separate IPv4 and IPv6
listeners in inetd (or xinetd) are the same systems that also disable
IPv4-mapped IPv6 addresses by default.  This is a boot-time configuration
option.  If you enable IPv4-mapped IPv6 addresses, then the 'tcp46' option
in inetd works and the simplified config would look like:

imap4   stream  tcp46   nowait  root    /usr/local/libexec/imapd        imapd
imaps   stream  tcp46   nowait  root    /usr/local/libexec/imapd        imapd

In FreeBSD, enabling IPv4-mapped addresses is done by adding
ipv6_ipv4mapping=&quot;YES&quot; to /etc/rc.conf (in addition to ipv6_enable=&quot;YES&quot;).
                                                                                                                                                                                                                                                                                                                mixfmt.txt                                                                                          0000644                 00000034312 15051750507 0006621 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       /* ========================================================================
 * Copyright 1988-2006 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
 * 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
 *
 * 
 * ========================================================================
 */

Last update: 18 December 2006

INTRODUCTION

This file is the descendant of a design document used to specify the
mix format.  An attempt is being made to keep this document more or
less current with the way the mix format actually works.


1. Mix mailbox naming

Mailbox names correspond to directory names; thus mix format mailboxes
are &quot;dual-use&quot; (lack both \NoInferiors and \NoSelect).  This will
satisfy some long-standing requests.


2. Mailbox files

A mix format mailbox is a directory with regular files with filenames
of:
	.mixmeta	mailbox metadata file
	.mixindex	message index file (message static data)
	.mixstatus	message status file (message dynamic data)
	.mix########	(where ######### is a &lt;hex8&gt;) secondary message
			 data files.
	.mix		primary message data file (used in experimental
			 versions, supported for compatibility only)

2.1 Metadata, index, and status files

The mailbox metadata, index, and status files contain a sequence of
CRLF-terminated lines.  These files have an update sequence, which is
a strictly-ascending sequence value.  Any time the file is changed,
the update sequence is increased; this allows easy detection of
whether the file has been changed by another process.  For now, this
update sequence is a modseq (see below).

2.1.1 Metadata file

The mailbox metadata file is called &quot;.mixmeta&quot;.  It contains a series
of CRLF-terminated lines.  The first character of the line is a key that
identifies the payload of the line, and the remainder of the line is the
payload.
	Key	Payload
	---	-------
	 S	&lt;hex8&gt;			;; update sequence
	 V	&lt;hex8&gt;			;; UIDVALIDITY
	 L	&lt;hex8&gt;			;; UIDLAST
	 N	&lt;hex8&gt;			;; current new message file
	 K	[atom 0*(SP atom)]	;; keyword list

All other keys are reserved for future assignment and must be ignored
(and may be discarded) by software which does not recognize them.  The
mailbox metadata file is rewritten as part of new mail delivery (so
APPENDUID/COPYUID can work) and when new keywords are added.

2.1.2 Message static index file

The mailbox message static index file is called &quot;.mixindex&quot;.  It contains
a series of CRLF-terminated lines.  The first character of the line is a
key that identifies the payload of the line, and the remainder of the line
is the payload.
	Key	Payload
	---	-------
	 S	&lt;hex8&gt;			;; update sequence
	 :	&lt;uid&gt;:&lt;date&gt;:&lt;size&gt;:&lt;file&gt;:&lt;pos&gt;:&lt;isiz&gt;:&lt;hsiz&gt;
	 				;; per-message record

The per-message records contain the following data:
	&lt;uid&gt;  = &lt;hex8&gt;			;; message UID
	&lt;date&gt; = &lt;yyyymmddhhmmss+zzzz&gt;	;; internal date
	&lt;size&gt; = &lt;hex8&gt;			;; rfc822.size
	&lt;file&gt; = &lt;hex8&gt;			;; message data file (0 = .mix file)
	&lt;pos&gt;  = &lt;hex8&gt;			;; message position in file
	&lt;isiz&gt; = &lt;hex8&gt;			;; message internal data size
	&lt;hsiz&gt; = &lt;hex8&gt;			;; header size (offset to body)

All other keys, and subsequent fields in per-message records, are
reserved for future assignment and must be ignored (and may be
discarded) by software which does not recognize them.  The mailbox
metadata file is appended by new mail delivery and rewritten by
expunge &quot;burping&quot;, and otherwise is not altered.

2.1.3 Message dynamic status file

The mailbox message dynamic status file is called &quot;.mixstatus&quot;.  It contains
a series of CRLF-terminated lines.  The first character of the line is a
key that identifies the payload of the line, and the remainder of the line
is the payload.
   	Key	Payload
	---	-------
	 S	&lt;hex8&gt;			;; update sequence
	 :	&lt;uid&gt;:&lt;uf&gt;:&lt;sf&gt;:&lt;mod&gt;:	;; per-message record

The per-message records contain the following data:
	&lt;uid&gt;  = &lt;hex8&gt;			;; message UID
	&lt;keys&gt; = &lt;hex8&gt;			;; keyword flags
	&lt;flag&gt; = &lt;hex4&gt;			;; system flags
	&lt;mod&gt;  = &lt;hex8&gt;			;; date/time last modified (modseq)

All other keys, and subsequent fields in per-message records, are
reserved for future assignment and must be ignored (and may be
discarded) by software which does not recognize them.  The mailbox
dynamic idex file is rewritten by flag changes (or any future change
that alters dynamic data) and is re-read when a session sees that the
mtime has changed (atime and ctime are not used).

The modseq is an unsigned 32-bit date/time, along with a guarantee
that this value can not go backwards.  It currently corresponds to the
time from time(); however, since it is unsigned, it won't run out until
the year 2106.  In the future, this may be used as a basic for implementing
the IMAP CONDSTORE extension.

2.2 Message data files

A mix message file is a regular file with filename starting with
&quot;.mix&quot; followed by a &lt;hex8&gt; suffix which indicates the file number.  It
contains a series of CRLF-terminated lines.  By special dispensation, the
filename &quot;.mix&quot; is used for file number 0, which was used in experimental
versions of mix as a &quot;primary&quot; file (this concept no longer exists).

A file number is set to the current modseq when it is created.  If a copy
or append causes the file to exceed the compiled-in file size limit, a new
file is started and the metadata is updated accordingly.

Preceeding each message is per-message record with the following format:
   	Key	Payload
	---	-------
					;; per-message record
	:	:&lt;code&gt;:&lt;uid&gt;:&lt;date&gt;:&lt;size&gt;:

The per-message records contain the following data:
	&lt;code&gt; = &quot;msg&quot;			;; fixed code
	&lt;uid&gt;  = &lt;hex8&gt;			;; message UID
	&lt;date&gt; = &lt;yyyymmddhhmmss+zzzz&gt;	;; internal date
	&lt;size&gt; = &lt;hex8&gt;			;; rfc822.size
The message data begins on the next line

Subsequent fields are reserved for future assignment and must be ignored.


3. New mail delivery

To deliver a new message, it is necessary to share lock the destination
metadata file, then get an exclusive lock on the destination index and
status files.  Once this is done, the new message data is appended to the
new message file.  The metadata (UIDLAST value), index, and status
files are all updated to add the new message.

Then all the destination mailbox files are closed.


4. Mailbox pinging

The index and status files are share locked.  Initially, sequences are
remembered as zero, so at open time they are always &quot;altered&quot;.

The sequence from the index file is checked; if it is altered the index
file is read and processed as follows:
 . If expunge is permitted, then any messages that are not in the index
   are reported as having been expunged via mm_expunged().
 . new messages are announced via mm_exists()/mm_recent().

Next, the sequence from the status file is checked.  If it is altered,
the status file is read and the status updated for any message which is
new or has an altered modseq in the status file.  Altered modseq messages
are announced via mm_flags().

Then the index and status files are closed.


4. Flag alteration

The status file is exclusive locked.

The sequence from the status file is checked.  If it is altered, the
status file is read and the status updated for any message which is
new or has an altered modseq in the status file.  Altered modseq
messages are announced via mm_flags().

The alterations are then applied for all requested messages, updating
the modseq for each requestedmessage which changes flags as a result
of the alteration (alterations which do not result in a change do not
alter the modseq).  Then the status file is rewritten with a new
sequence, but only if flags of at least one message was changed.

Then the status file is closed.


5. Checkpoint and expunge

Checkpoint is identical to expunge, however it skips the step of expunging
deleted messages.

The index and status files are locked exclusive.  If expunging, all
deleted messages are expunged from the index and announced via
mm_expunged().  The message data is notremoved at this time.

If a checkpoint was requested, or if any messages were expunged, or if
it remembered that a &quot;burp&quot; was needed, then:
 . the metadata file is locked exclusive.  If this fails, remember that
   a burp is needed.  Otherwise perform a burp:
   . calculate the file byte ranges occupied by expunged messages
   . for each file needing &quot;burping&quot;, open and slide down subsequent file
     data on top of the expunged messages
 . update the index and status files

Then the index and status files are closed.

5.1 More details on expunging and &quot;burping&quot;

Shared expunge presents a problem due to the requirements of the IMAP
protocol.  You can't &quot;burp&quot; away a message until you are certain that
no sharers have a pointer to any longer.  Consequently, for the nonce
&quot;burping&quot; out expunged data be defered to an exclusive expunge as in
mbx format.

If shared burping is ever implemented, then care will be needed not to
burp data that a session still relies upon.  It's easy enough to burp
the index files; just create new index files, deleting the old, and
require that you look for a new one appearing at mailbox ping time
(when it's safe).  The data files are a problem, since we
intentionally don't want to keep them open and do want to avoid quota
problems by overwriting in place.  Also, when you burp you have to
change the pointers in the index file.

Bottom line: shared burping is too hairy right now, so the first
version will do exclusive-only burping and not worry about it.  If
shared burping is really needed, then that routine will need to be
rewritten.

Shared burping has been a problem for every other IMAP server.  Most
get it wrong, and cause terrible confusion to clients (including
client crashes).


6. Message data file file roll out strategy

The current new message file is finalized, and a new one started, when
an append or copy is done that would cause the file to grow to larger
than a preconfigured size (MIXDATAROLL).  A multi-message copy or
append is written into its entirety to a single new message file.  In
the case of multi-copy, the new message file is switched when the sum
of the sizes of all messages to be copied would cause the current new
message file to exceed MIXDATAROLL.  In the case of multi-append, only
the first message is considered; this is due to technical limitations.

7. Error detection

Mix detects bad data in the metadata, index, and status files; and
declares the stream dead.  It does not unilaterally reassign
UIDVALIDITY the way that the flat file formats do.

When mix reads a header from the message file, it also reads the
per-message record and verifies that there is a per-message record there.
This is a simple test for message file corruption.  It doesn't declare
the stream dead; it simply issues an error message and returns a
zero-length string for the message header.  This makes it possible for
the user to fix the mailbox simply by deleting and expunging any messages
that are in this state.


8. Reconstruct tool

[None of this is implemented yet.]

The layout of these files is designed to make the reconstruct tool be
as simple as possible.  Much of the need for the reconstruct tool is
eliminated since the mix format has a much more limited scope of
writing than the flat file formats; thus there is &quot;less collateral
damage.&quot;

If the metadata file is lost or corrupted, then all keywords are lost;
if the mailbox has any keywords used in the .mixstatus file, it'll be
necessary to create some placeholder names.  Otherwise, a new
UIDVALIDITY can be assigned, and a good UIDLAST value calculated by
the reconstruct tool.  Since this file is very small, it's not likely
to be damaged.

If the index file is lost or corrupted, it is possible to reconstruct
it with no loss by reading all the data files.  However, this could
cause expunged but not yet burped messages to reappear.

If the status file is lost or corrupted, then flags are lost and
will revert to a default state of no flags set.  Just deleting the
corrupted file is good enough.

The reconstruct tool can use the per-message record in the message
file to locate messages if the recorded sizes and/or messages are
corrupt.  If that happens, it will need to rebuild the index file
(with associated changes to the metadata file to change the
UIDVALIDITY).  That should probably be a manual operation and not be
part of the default operation or auto-reconstruct.


9. Locking strategy

The mix format does not use the traditional c-client /tmp file locking.

The metadata file is open and locked whenever the mailbox is open.
Normally this is a shared lock, but it will be upgraded to exclusive
if the mailbox is expunged.  As a guard (since there is no true
lock-upgrade/downgrade on UNIX), the index exclusive lock must be
acquired first before upgrading to exclusive.

The index file is shared locked when reading the index, and exclusive
locked (and read) when appending new messages to the index or when
expunging (note that expunging also requires an exclusive lock on
metadata).  Normally, the index file is not open or locked.

The status file is shared locked when reading status, and exclusive
locked (and read) when updating status.  Normally, the status file is
not open or locked.

It isn't necessary to lock any of the data files as long as we only
have exclusive burping.


10. Memory usage

The mix format returns a file stringstruct, which is the modern
c-client behavior.  This prevents imapd from growing to enormous sizes
due to a godzillagram (how it affects other programs depends upon what
they do with the returned stringstruct).


11. Future extensions

Cached ENVELOPE, BODYSTRUCTURE.  Cyrus does, and this will eliminate
most of the reason to access the data files.  Possibly cached overviews,
ala NNTP, instead?


Support for ANNOTATION.


12. RENAME issues

Mix currently makes no attempt to address the IMAP RENAME problem.
This occurs when a mailbox is deleted, and another mailbox is renamed
with that name in place, no attempt is made to reassign UIDVALIDITY
for this mailbox and all the inferior mailboxes.  This potentially can
cause problems for a disconnected-use client that has cached status
for the old mailbox which had that name.

The RENAME problem is a well known flaw in the IMAP protocol.  Few
servers correctly handle it (among other things, not only do all the
UIDVALIDITY values have to be changed but this has to be done
atomically!).  It was a mistake to add RENAME into IMAP, but it's much
too late to remove it now.
                                                                                                                                                                                                                                                                                                                      NOTICE                                                                                              0000644                 00000001367 15051750507 0005464 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       UW IMAP toolkit notices:

This software was developed by the University of Washington
(http://www.washington.edu/).

The Univerity of Washington IMAP Toolkit (c-client API, dmail, imapd,
ipop2d, ipop3d, mailutil, mlock, mtest, and tmail software; and its
included text) is Copyright 1988-2007 by the University of Washington.

The c-client library and mtest software are in part based upon code
developed by Mark Crispin at Stanford University, and is

 * Copyright 1988 Stanford University and was developed in the
 * Symbolic Systems Resources Group of the Knowledge Systems Laboratory
 * at Stanford University in 1987-88, and was funded by the
 * Biomedical Research Technology Program of the National Institutes of
 * Health under grant number RR-00785.
                                                                                                                                                                                                                                                                         commndmt.txt                                                                                        0000644                 00000011600 15051750507 0007126 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       /* ========================================================================
 * Copyright 1988-2006 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
 * 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
 *
 * 
 * ========================================================================
 */

[I wrote this tongue-in-cheek, but there's a lot here that people who
 build IMAP clients should take careful note.  Most existing clients
 violate at least one, generally several, of these commandments.
 These are based on known user-visible problems that occur with various
 commonly used clients.  Put another way, behind each commandment is a
 plethora of user (and server administrator) complaints caused by a
 violator.]

	   Ten Commandments of How to Write an IMAP client
			     Mark Crispin

1. Thou shalt not assume that it is alright to open multiple IMAP
sessions selected on the same mailbox simultaneously, lest thou face
the righteous wrath of mail stores that doth not permit such access.
Instead, thou shalt labor mightily, even unto having to use thy brain
to thinketh the matter through, such that thy client use existing
sessions that are already open.

2. Thou shalt not abuse the STATUS command by using it to check for
new mail on a mailbox that you already have selected in an IMAP
session; for that session hath already told thou about new mail
without thy having to ask.

3. Thou shalt remember the 30 minute inactivity timeout, and remember
to speak to the IMAP server before that timeout expires.  If thou
useth the IDLE command, thou shalt send DONE from the IDLE before 29
minutes hath passed, and issue a new IDLE.  If thou maketh no use of
IDLE, then thou shalt send NOOP every few minutes, and the server
shalt tell you about new mail, and there will be much rejoicing in the
land.

4. Thou shalt not assume that all names are both the name of a mailbox
and the name of a upper level of hierarchy that contains mailboxes;
lest thou face the righteous wrath of mail stores in which a mailbox
is a file and a level of hierarchy is a directory.  Thou shalt pay
diligent attention to the \NoSelect and \NoInferiors flags, so that
your users may praise you with great praise.

5. Thou shalt learn and understand the unique features of IMAP, such
as the unsolicited data model, the strict ascending rule of UIDs, how
UIDs map to sequence numbers, the ENVELOPE and BODYSTRUCTURE
structures; so that thou may use the IMAP protocol effectively.  For a
POP client hacked to babble IMAP protocol is still no more than a POP
client.

6. Thou shalt remember untagged data sent by the server, and when thou
needest data thou shalt consult your memory before asking the server.
For those who must analyze thy protocol transactions are weak of
stomach, and are likely to lose their recent meal should they see thou
repeatedly re-fetch static data.

7. Thou shalt labor with great effort to work within the IMAP
deleted/expunge model, even if thy own model is that of a trashcan;
for interoperability is paramount and a trashcan model can be done
entirely in the user interface.

8. Thou shalt not fear to open multiple IMAP sessions to the server;
but thou shalt use this technique with wisdom.  For verily it is true;
if thou doth desire to monitor continuously five mailboxes for new
mail, it is better to have five IMAP sessions continuously open on the
mailboxes.  It is generally not good to do a succession of five SELECT
or STATUS commands on a periodic basis; and it is truly wretched to
open and close five sessions to do a STATUS or SELECT on a periodic
basis.  The cost of opening and closing a session is great, especially
if that session is SSL/TLS protected; and the cost of a STATUS or
SELECT can also be great.  By comparison, the cost of an open session
doing an IDLE or getting a NOOP every few minutes is small.  Great
praise shall be given to thy wisdom in doing what is less costly
instead of &quot;common sense.&quot;

9. Thou shalt not abuse subscriptions, for verily the LIST command is
the proper way to discover mailboxes on the server.  Thou shalt not
subscribe names to the user's subscription list without explicit
instructions from the user; nor shalt thou assume that only subscribed
names are valid.  Rather, thou shalt treat subscribed names as akin to
a bookmarks, or perhaps akin to how Windows shows the &quot;My Documents&quot;
folder -- a set of names that are separate from the hierarchy, for
they are such.

10. Thou shalt use the LIST &quot;*&quot; wildcard only with great care.  If
thou doth not fully comprehend the danger of &quot;*&quot;, thou shalt use only
&quot;%&quot; and forget about the existance of &quot;*&quot;.

Honor these commandments, and keep them holy in thy heart, so that thy
users shalt maximize their pleasure, and the server administrators
shalt sing thy praises and recommend thy work as a model for others to
emulate.

                                                                                                                                LICENSE.txt                                                                                         0000644                 00000026137 15051750507 0006405 0                                                                                                    ustar 00                                                                                                                                                                                                                                                                                        Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions. 

      &quot;License&quot; shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      &quot;Licensor&quot; shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      &quot;Legal Entity&quot; shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      &quot;control&quot; means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      &quot;You&quot; (or &quot;Your&quot;) shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      &quot;Source&quot; form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      &quot;Object&quot; form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      &quot;Work&quot; shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below). 

      &quot;Derivative Works&quot; shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      &quot;Contribution&quot; shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, &quot;submitted&quot;
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as &quot;Not a Contribution.&quot;

      &quot;Contributor&quot; shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a &quot;NOTICE&quot; text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an &quot;AS IS&quot; BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets &quot;[]&quot;
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same &quot;printed page&quot; as the copyright notice for easier
      identification within third-party archives.

   Copyright [yyyy] [name of copyright owner]

   Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
   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

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an &quot;AS IS&quot; BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
                                                                                                                                                                                                                                                                                                                                                                                                                                 locking.txt                                                                                         0000644                 00000045615 15051750507 0006753 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       /* ========================================================================
 * Copyright 1988-2006 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
 * 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
 *
 * 
 * ========================================================================
 */

	 UNIX Advisory File Locking Implications on c-client
		    Mark Crispin, 28 November 1995


	THIS DOCUMENT HAS BEEN UPDATED TO REFLECT THE FACT THAT
	LINUX SUPPORTS BOTH flock() AND fcntl() AND THAT OSF/1
	HAS BEEN BROKEN SO THAT IT ONLY SUPPORTS fcntl().
	-- JUNE 15, 2004

	THIS DOCUMENT HAS BEEN UPDATED TO REFLECT THE CODE IN THE
	IMAP-4 TOOLKIT AS OF NOVEMBER 28, 1995.  SOME STATEMENTS
	IN THIS DOCUMENT DO NOT APPLY TO EARLIER VERSIONS OF THE
	IMAP TOOLKIT.

INTRODUCTION

     Advisory locking is a mechanism by which cooperating processes
can signal to each other their usage of a resource and whether or not
that usage is critical.  It is not a mechanism to protect against
processes which do not cooperate in the locking.

     The most basic form of locking involves a counter.  This counter
is -1 when the resource is available.  If a process wants the lock, it
executes an atomic increment-and-test-if-zero.  If the value is zero,
the process has the lock and can execute the critical code that needs
exclusive usage of a resource.  When it is finished, it sets the lock
back to -1.  In C terms:

  while (++lock)		/* try to get lock */
    invoke_other_threads ();	/* failed, try again */
   .
   .	/* critical code  here */
   .
  lock = -1;			/* release lock */

     This particular form of locking appears most commonly in
multi-threaded applications such as operating system kernels.  It
makes several presumptions:
 (1) it is alright to keep testing the lock (no overflow)
 (2) the critical resource is single-access only
 (3) there is shared writeable memory between the two threads
 (4) the threads can be trusted to release the lock when finished

     In applications programming on multi-user systems, most commonly
the other threads are in an entirely different process, which may even
be logged in as a different user.  Few operating systems offer shared
writeable memory between such processes.

     A means of communicating this is by use of a file with a mutually
agreed upon name.  A binary semaphore can be passed by means of the
existance or non-existance of that file, provided that there is an
atomic means to create a file if and only if that file does not exist.
In C terms:

				/* try to get lock */
  while ((fd = open (&quot;lockfile&quot;,O_WRONLY|O_CREAT|O_EXCL,0666)) &lt; 0)
    sleep (1);			/* failed, try again */
  close (fd);			/* got the lock */
   .
   .	/* critical code  here */
   .
  unlink (&quot;lockfile&quot;); 		/* release lock */

     This form of locking makes fewer presumptions, but it still is
guilty of presumptions (2) and (4) above.  Presumption (2) limits the
ability to have processes sharing a resource in a non-conflicting
fashion (e.g. reading from a file).  Presumption (4) leads to
deadlocks should the process crash while it has a resource locked.

     Most modern operating systems provide a resource locking system
call that has none of these presumptions.  In particular, a mechanism
is provided for identifying shared locks as opposed to exclusive
locks.  A shared lock permits other processes to obtain a shared lock,
but denies exclusive locks.  In other words:

	current state		want shared	want exclusive
	-------------		-----------	--------------
	 unlocked		 YES		 YES
	 locked shared		 YES		 NO
	 locked exclusive	 NO		 NO

     Furthermore, the operating system automatically relinquishes all
locks held by that process when it terminates.

     A useful operation is the ability to upgrade a shared lock to
exclusive (provided there are no other shared users of the lock) and
to downgrade an exclusive lock to shared.  It is important that at no
time is the lock ever removed; a process upgrading to exclusive must
not relenquish its shared lock.

     Most commonly, the resources being locked are files.  Shared
locks are particularly important with files; multiple simultaneous
processes can read from a file, but only one can safely write at a
time.  Some writes may be safer than others; an append to the end of
the file is safer than changing existing file data.  In turn, changing
a file record in place is safer than rewriting the file with an
entirely different structure.


FILE LOCKING ON UNIX

     In the oldest versions of UNIX, the use of a semaphore lockfile
was the only available form of locking.  Advisory locking system calls
were not added to UNIX until after the BSD vs. System V split.  Both
of these system calls deal with file resources only.

     Most systems only have one or the other form of locking.  AIX
and newer versions of OSF/1 emulate the BSD form of locking as a jacket
into the System V form.  Ultrix and Linux implement both forms.

BSD

     BSD added the flock() system call.  It offers capabilities to
acquire shared lock, acquire exclusive lock, and unlock.  Optionally,
the process can request an immediate error return instead of blocking
when the lock is unavailable.


FLOCK() BUGS

     flock() advertises that it permits upgrading of shared locks to
exclusive and downgrading of exclusive locks to shared, but it does so
by releasing the former lock and then trying to acquire the new lock.
This creates a window of vulnerability in which another process can
grab the exclusive lock.  Therefore, this capability is not useful,
although many programmers have been deluded by incautious reading of
the flock() man page to believe otherwise.  This problem can be
programmed around, once the programmer is aware of it.

     flock() always returns as if it succeeded on NFS files, when in
fact it is a no-op.  There is no way around this.

     Leaving aside these two problems, flock() works remarkably well,
and has shown itself to be robust and trustworthy.

SYSTEM V/POSIX

     System V added new functions to the fnctl() system call, and a
simple interface through the lockf() subroutine.  This was
subsequently included in POSIX.  Both offer the facility to apply the
lock to a particular region of the file instead of to the entire file.
lockf() only supports exclusive locks, and calls fcntl() internally;
hence it won't be discussed further.

     Functionally, fcntl() locking is a superset of flock(); it is
possible to implement a flock() emulator using fcntl(), with one minor
exception: it is not possible to acquire an exclusive lock if the file
is not open for write.

     The fcntl() locking functions are: query lock station of a file
region, lock/unlock a region, and lock/unlock a region and block until
have the lock.  The locks may be shared or exclusive.  By means of the
statd and lockd daemons, fcntl() locking is available on NFS files.

     When statd is started at system boot, it reads its /etc/state
file (which contains the number of times it has been invoked) and
/etc/sm directory (which contains a list of all remote sites which are
client or server locking with this site), and notifies the statd on
each of these systems that it has been restarted.  Each statd then
notifies the local lockd of the restart of that system.

     lockd receives fcntl() requests for NFS files.  It communicates
with the lockd at the server and requests it to apply the lock, and
with the statd to request it for notification when the server goes
down.  It blocks until all these requests are completed.

     There is quite a mythos about fcntl() locking.

     One religion holds that fcntl() locking is the best thing since
sliced bread, and that programs which use flock() should be converted
to fcntl() so that NFS locking will work.  However, as noted above,
very few systems support both calls, so such an exercise is pointless
except on Ultrix and Linux.

     Another religion, which I adhere to, has the opposite viewpoint.


FCNTL() BUGS

     For all of the hairy code to do individual section locking of a
file, it's clear that the designers of fcntl() locking never
considered some very basic locking operations.  It's as if all they
knew about locking they got out of some CS textbook with not
investigation of real-world needs.

     It is not possible to acquire an exclusive lock unless the file
is open for write.  You could have append with shared read, and thus
you could have a case in which a read-only access may need to go
exclusive.  This problem can be programmed around once the programmer
is aware of it.

     If the file is opened on another file designator in the same
process, the file is unlocked even if no attempt is made to do any
form of locking on the second designator.  This is a very bad bug.  It
means that an application must keep track of all the files that it has
opened and locked.

     If there is no statd/lockd on the NFS server, fcntl() will hang
forever waiting for them to appear.  This is a bad bug.  It means that
any attempt to lock on a server that doesn't run these daemons will
hang.  There is no way for an application to request flock() style
``try to lock, but no-op if the mechanism ain't there''.

     There is a rumor to the effect that fcntl() will hang forever on
local files too if there is no local statd/lockd.  These daemons are
running on mailer.u, although they appear not to have much CPU time.
A useful experiment would be to kill them and see if imapd is affected
in any way, but I decline to do so without an OK from UCS!  ;-) If
killing statd/lockd can be done without breaking fcntl() on local
files, this would become one of the primary means of dealing with this
problem.

     The statd and lockd daemons have quite a reputation for extreme
fragility.  There have been numerous reports about the locking
mechanism being wedged on a systemwide or even clusterwide basis,
requiring a reboot to clear.  It is rumored that this wedge, once it
happens, also blocks local locking.  Presumably killing and restarting
statd would suffice to clear the wedge, but I haven't verified this.

     There appears to be a limit to how many locks may be in use at a
time on the system, although the documentation only mentions it in
passing.  On some of their systems, UCS has increased lockd's ``size
of the socket buffer'', whatever that means.

C-CLIENT USAGE

     c-client uses flock().  On System V systems, flock() is simulated
by an emulator that calls fcntl().


BEZERK AND MMDF

     Locking in the traditional UNIX formats was largely dictated by
the status quo in other applications; however, additional protection
is added against inadvertantly running multiple instances of a
c-client application on the same mail file.

     (1) c-client attempts to create a .lock file (mail file name with
``.lock'' appended) whenever it reads from, or writes to, the mail
file.  This is an exclusive lock, and is held only for short periods
of time while c-client is actually doing the I/O.  There is a 5-minute
timeout for this lock, after which it is broken on the presumption
that it is a stale lock.  If it can not create the .lock file due to
an EACCES (protection failure) error, it once silently proceeded
without this lock; this was for systems which protect /usr/spool/mail
from unprivileged processes creating files.  Today, c-client reports
an error unless it is built otherwise.  The purpose of this lock is to
prevent against unfavorable interactions with mail delivery.

     (2) c-client applies a shared flock() to the mail file whenever
it reads from the mail file, and an exclusive flock() whenever it
writes to the mail file.  This lock is freed as soon as it finishes
reading.  The purpose of this lock is to prevent against unfavorable
interactions with mail delivery.

     (3) c-client applies an exclusive flock() to a file on /tmp
(whose name represents the device and inode number of the file) when
it opens the mail file.  This lock is maintained throughout the
session, although c-client has a feature (called ``kiss of death'')
which permits c-client to forcibly and irreversibly seize the lock
from a cooperating c-client application that surrenders the lock on
demand.  The purpose of this lock is to prevent against unfavorable
interactions with other instances of c-client (rewriting the mail
file).

     Mail delivery daemons use lock (1), (2), or both.  Lock (1) works
over NFS; lock (2) is the only one that works on sites that protect
/usr/spool/mail against unprivileged file creation.  Prudent mail
delivery daemons use both forms of locking, and of course so does
c-client.

     If only lock (2) is used, then multiple processes can read from
the mail file simultaneously, although in real life this doesn't
really change things.  The normal state of locks (1) and (2) is
unlocked except for very brief periods.


TENEX AND MTX

     The design of the locking mechanism of these formats was
motivated by a design to enable multiple simultaneous read/write
access.  It is almost the reverse of how locking works with
bezerk/mmdf.

     (1) c-client applies a shared flock() to the mail file when it
opens the mail file.  It upgrades this lock to exclusive whenever it
tries to expunge the mail file.  Because of the flock() bug that
upgrading a lock actually releases it, it will not do so until it has
acquired an exclusive lock (2) first.  The purpose of this lock is to
prevent against expunge taking place while some other c-client has the
mail file open (and thus knows where all the messages are).

     (2) c-client applies a shared flock() to a file on /tmp (whose
name represents the device and inode number of the file) when it
parses the mail file.  It applies an exclusive flock() to this file
when it appends new mail to the mail file, as well as before it
attempts to upgrade lock (1) to exclusive.  The purpose of this lock
is to prevent against data being appended while some other c-client is
parsing mail in the file (to prevent reading of incomplete messages).
It also protects against the lock-releasing timing race on lock (1).

OBSERVATIONS

     In a perfect world, locking works.  You are protected against
unfavorable interactions with the mailer and against your own mistake
by running more than one instance of your mail reader.  In tenex/mtx
formats, you have the additional benefit that multiple simultaneous
read/write access works, with the sole restriction being that you
can't expunge if there are any sharers of the mail file.

     If the mail file is NFS-mounted, then flock() locking is a silent
no-op.  This is the way BSD implements flock(), and c-client's
emulation of flock() through fcntl() tests for NFS files and
duplicates this functionality.  There is no locking protection for
tenex/mtx mail files at all, and only protection against the mailer
for bezerk/mmdf mail files.  This has been the accepted state of
affairs on UNIX for many sad years.

     If you can not create .lock files, it should not affect locking,
since the flock() locks suffice for all protection.  This is, however,
not true if the mailer does not check for flock() locking, or if the
the mail file is NFS-mounted.

     What this means is that there is *no* locking protection at all
in the case of a client using an NFS-mounted /usr/spool/mail that does
not permit file creation by unprivileged programs.  It is impossible,
under these circumstances, for an unprivileged program to do anything
about it.  Worse, if EACCES errors on .lock file creation are no-op'ed
, the user won't even know about it.  This is arguably a site
configuration error.

     The problem with not being able to create .lock files exists on
System V as well, but the failure modes for flock() -- which is
implemented via fcntl() -- are different.

     On System V, if the mail file is NFS-mounted and either the
client or the server lacks a functioning statd/lockd pair, then the
lock attempt would have hung forever if it weren't for the fact that
c-client tests for NFS and no-ops the flock() emulator in this case.
Systemwide or clusterwide failures of statd/lockd have been known to
occur which cause all locks in all processes to hang (including
local?).  Without the special NFS test made by c-client, there would
be no way to request BSD-style no-op behavior, nor is there any way to
determine that this is happening other than the system being hung.

     The additional locking introduced by c-client was shown to cause
much more stress on the System V locking mechanism than has
traditionally been placed upon it.  If it was stressed too far, all
hell broke loose.  Fortunately, this is now past history.

TRADEOFFS

     c-client based applications have a reasonable chance of winning
as long as you don't use NFS for remote access to mail files.  That's
what IMAP is for, after all.  It is, however, very important to
realize that you can *not* use the lock-upgrade feature by itself
because it releases the lock as an interim step -- you need to have
lock-upgrading guarded by another lock.

     If you have the misfortune of using System V, you are likely to
run into problems sooner or later having to do with statd/lockd.  You
basically end up with one of three unsatisfactory choices:
	1) Grit your teeth and live with it.
	2) Try to make it work:
	   a) avoid NFS access so as not to stress statd/lockd.
	   b) try to understand the code in statd/lockd and hack it
	      to be more robust.
	   c) hunt out the system limit of locks, if there is one,
	      and increase it.  Figure on at least two locks per
	      simultaneous imapd process and four locks per Pine
	      process.  Better yet, make the limit be 10 times the
	      maximum number of processes.
	   d) increase the socket buffer (-S switch to lockd) if
	      it is offered.  I don't know what this actually does,
	      but giving lockd more resources to do its work can't
	      hurt.  Maybe.
	3) Decide that it can't possibly work, and turn off the 
	   fcntl() calls in your program.
	4) If nuking statd/lockd can be done without breaking local
	   locking, then do so.  This would make SVR4 have the same
	   limitations as BSD locking, with a couple of additional
	   bugs.
	5) Check for NFS, and don't do the fcntl() in the NFS case.
	   This is what c-client does.

     Note that if you are going to use NFS to access files on a server
which does not have statd/lockd running, your only choice is (3), (4),
or (5).  Here again, IMAP can bail you out.

     These problems aren't unique to c-client applications; they have
also been reported with Elm, Mediamail, and other email tools.

     Of the other two SVR4 locking bugs:

     Programmer awareness is necessary to deal with the bug that you
can not get an exclusive lock unless the file is open for write.  I
believe that c-client has fixed all of these cases.

     The problem about opening a second designator smashing any
current locks on the file has not been addressed satisfactorily yet.
This is not an easy problem to deal with, especially in c-client which
really doesn't know what other files/streams may be open by Pine.

     Aren't you so happy that you bought an System V system?
                                                                                                                   RELNOTES                                                                                            0000644                 00000103203 15051750507 0005726 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       /* ========================================================================
 * Copyright 1988-2008 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
 * 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
 *
 * 
 * ========================================================================
 */

Updated: 22 July 2011

imap-2007f fixes a couple bugs.
Fix for RFC 4959 Initial Client Response auth failures noted first by
  MacOSX Lion Mail users.
Adjust tcp_open.c:tcp_socket_open to make it a little more useful by adding
  a write file descriptor test to the select in the case that the open
  timeout is set.
In osdep/unix/env_unix.c:create_path there was a printf that should have
  been an sprintf. Doesn't matter on modern systems.

Updated: 16 December 2008

imap-2007e is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users
plus a security fix for users of the RFC822BUFFER routines.


Updated: 29 October 2008

imap-2007d is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users
plus a security fix for users of tmail or dmail.


Updated: 25 March 2008

imap-2007b is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.


Updated: 2 January 2008

imap-2007a is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.


Updated: 20 December 2007

imap-2007 is a release corresponding with the release of Alpine 1.0.
The primary focus of the imap-2007 release is bugfixes and reliability
improvements.  This includes:
 . fixes to problems discovered between the Alpine 0.99999 pre-release
    and Alpine 1.0
 . fixes to the mix driver to timing race problems uncovered by Timo
    Sirainen's imaptest suite.  imap-2007 using the mix format is
    believed to pass imaptest completely.

A new function, utf8_csvalidmap(), has been added for the benefit of
Alpine to use in examining UTF-8 text and determining efficiently
whether it can be downgraded to a legacy charset.  If you develop an
MUA, this may be useful for you too, although you'll have to read the
source code to see how to use it.  The purpose of the &quot;not-CJK&quot; bit is
to prevent messages being downgraded to a CJK charset if all they have
in that charset are some special punctuation.


Updated: 5 September 2007

imap-2006k is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.

The primary focus of this maintenance release is to correct deadlock
issues.  There were two major causes of the deadlocks:
 . a change in imap-2006i attempted to resolve a glibc mutex-based
   deadlock in imapd's signal handler, but ended up worsening the problem.
 . a bug in the mbx driver, introduced as part of the UIDPLUS work in 2006,
   applied an mbx-style lock briefly on a traditional UNIX format mailbox.
   If the traditional UNIX format mailbox was already locked by some other
   process, the result would be a deadlock of both processes.

imapd's signal handling logic is rewritten to avoid the mutex issue, and
the mbx driver is fixed so that mbx-style locks are only applied to mbx
format mailboxes.

imapd now supports the WITHIN extension.


Updated: 14 June 2007

imap-2006j is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.


Updated: 5 June 2007

imap-2006i is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.

imapd now supports the CHILDREN and ESEARCH extensions.

imapd's attempt to return COPYUID/APPENDUID information for a traditional
UNIX (and MMDF) format mailbox when the mailbox is open by another process
has been declared to be a failure and is now revoked.  It was subject to a
timing race, loss of which involved an expensive reset of the mailbox's UID
regime.  Any imapd COPY or APPEND to a traditional UNIX or MMDF format that
is open by some other process will now no longer return COPYUID/APPEND.
Although this is technically in violation of RFC 4315, there is a loophole
in that document and the timing race/performance problem is worse.


Updated: 4 April 2007

imap-2006h is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.


Updated: 30 March 2007

imap-2006g is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.


Updated: 30 January 2007

imap-2006f is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.

For the benefit of multi-threaded applications, use of strtok() has been
abolished in the c-client library.  imapd and ipop3d stuff use it though.
The TOPS-20 and VAX/VMS ports still use strtok() since they don't use UNIX
threads.

This version has been test-built on Linux, Mac OS X, NeXT, Windows XP,
TOPS-20, and VAX/VMS.  This will probably be the last test-build on VAX/VMS
since the system I use for that purpose is being shut down.  I have no way
to test-build on DOS, legacy Mac OS (OS 9 and earlier), OS/2, or Windows CE;
and the builds on those systems are probably broken.


Updated: 26 January 2007

imap-2006e is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.


Updated: 6 December 2006

imap-2006d is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.

The decomposition mapping, title-case mapping, and character widths tables
have been updated to comply with the Unicode 5.0 standard.

Prototypes for the utf8aux.c functions have been moved to a new utf8aux.h.

The general c-client modules now include c-client.h instead of the individual
files.  Use of c-client.h instead of individual include files insulates
against future shuffling of include files.


Updated: 23 October 2006

imap-2006c is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.

By popular request, if a user has a mix (or other dual-use) format INBOX,
it will no longer be listed as \NoInferiors.  It's a bad idea to depend
upon this due to the case ambiguity issue, but it's there.


Updated: 26 September 2006

imap-2006b is a maintenance release, consisting entirely of bugfixes to
problems discovered in the release that affected a small number of users.


Updated: 15 September 2006

imap-2006a is a maintenance release, consisting entirely of bugfixes to
problems discovered in the release that affected a small number of users.

If it is necessary to build IPv4-only on one of the ports that has IPv6
preconfigured (ldb, lfd, lmd, lrh, lsu, osx, oxp), this can be done by
using IP6=4.  You can't do IP=4 in the build command directly since these
ports set IP themselves; however, now instead of setting IP=6 they now set
IP=$(IP6).


Updated: 30 August 2006

imap-2006 is a major release.  Programs written for imap-2004g should
build with this version with minor or no modification.  imap-2005 was not
released except as development snapshots.

imap-2006 contains major extensions to its Unicode support.  Searching and
sorting are now done with strings canonicalized to titlecase and decomposed
form.  Among other things, this means that Latin letters with diacriticals
will now sort with the basic Latin letter, and case-independent searching of
such letters (e.g., German umlauts) now works.  Previously, sorting was done
strictly by Unicode codepoint, and case-independence only worked with ASCII.

imapd now supports the UIDPLUS extension for mailboxes in unix, mmdf, mbx, mx,
and mix formats.  UID EXPUNGE is fully implemented.  Note that UIDPLUS is not
supported in the little-used drivers (mh, mtx, tenex) in which meaningful
APPENDUID/COPYUID data can not be returned.  Refer to bugs.txt for more
details.

The new mix format is a dual-use mailbox format designed for performance and
reliability with large mailboxes.  mix is documented in file mixfmt.txt.

SSL/TLS certificate validation on UNIX now checks the alternative names in the
certificate if the CN does not match.

The new /tls-sslv23 flag in a mailbox name causes a TLS session to use the
(incorrect) SSLv23 client method instead of the TLSv1 client method.  Some
broken servers use the SSLv23 server method, and this flag works around that
problem.  WARNING: use of this flag will cause TLS negotiation to fail with
a server which uses the proper TLSv1 server method.  Additionally, there are
known security risks in SSLv2; so users should be suspicious if this switch
suddenly becomes necesary.

The silly mailbox flag combination /ssl/tls is now rejected as an invalid
remote specification.  Previous versions tried to negotiate TLS over an SSL
session; even if the server permitted such a thing it couldn't work.

The memory management of several drivers has been redesigned to consume less
memory and hopefully be faster.

The private.data member of the MESSAGECACHE (elt) has been replaced with
a union that contains private.spare.data and private.spare.ptr, the latter
being a pointer.

A new FT_RETURNSTRINGSTRUCT flag has been added for mail_fetch_body() and
mail_fetch_text() calls.  If this flag is set, *and* if the function returns
NIL, then the requested string data is available on a stringstruct on
stream-&gt;private.string.  This is a special hack for the IMAP and POP servers
and is subject to incompatible change.  The result is a major performance
improvement in the servers with the mbx driver, particularly with large
messages.


Updated: 15 September 2005

imap-2004g is a maintenance release, and consists solely of a bugfix to
quoted string handling in the mailbox name parsing routine.


Updated: 15 August 2005

imap-2004f is a maintenance release, and consists solely of a bugfix to
the TCP code.

Also included is a new version of the UNIX SSL/TLS routines that allows the
SSL/TLS certificate validation client code to validate alternative names in
server certificates.  This code has not been thoroughly regression-tested but
is believed to work.  To use this new code instead of the old support:
	cd imap-2004f/src/osdep/unix
	mv ssl_unix.c ssl_unix.old
	mv ssl_unix.new ssl_unix.c
Then rebuild.


Updated: 21 June 2005

imap-2004e is a maintenance release, consisting entirely of bugfixes.

There are no user-visible functional enhancements in this version.


Updated: 20 April 2005

imap-2004d is a maintenance release, released concurrently with Pine
4.63, and consists primarily of bugfixes

There is now a workaround for RedHat breaking flock().  However, since
RedHat has said that they don't support flock(), there is no guarantee
that they won't break it in the future.  So you may want to consider some
other Linux distribution or BSD instead.  See:
	https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=123415
for the gruesome details.

There are no user-visible functional enhancements in this version.


Updated: 18 January 2005

imap-2004c is a maintenance release, released concurrently with Pine
4.62, including fixes to quoted-printable encoding and CRAM-MD5
authentication.

NNTP proxy in imapd now supports the LIST and LSUB commands.

There are no other user-visible functional enhancements in this version.


Updated: 29 November 2004

imap-2004b is a maintenance release, consisting primarily of bugfixes.
Programs written for imap-2004a will build with this version without
modifification.

There are new ports for Solaris with Blastwave Community Open Source
Software (gcs) and Mandrake Linux (lmd).

SET_SNARFINTERVAL now controls how frequently local drivers will move new
mail from the mail spool as well as from a maildrop.  Maildrops are still
tied to a minimum interval of 1 minute, but there is now no minimum for the
spool file.

Character set conversions now map non-breaking space to space if the
destination character set doesn't have nbsp.  JIS Roman yen sign is now
mapped to Unicode yen sign.

There are no user-visible functional enhancements in this version.


Updated: 8 July 2004

imap-2004a is a maintenance release, consisting primarily of critical
bugfixes.  Programs written for imap-2004 will build with this version
without modification.

imapd now has a supported NNTP proxy capability.  If the file /etc/imapd.nntp
exists, the contents of that file are used as the host name of an NNTP
server which will be used whenever a #news. name is used.  For example, if
/etc/imapd.nntp contains nntp.example.com, and the IMAP client SELECTs or
EXAMINEs the name #news.comp.mail.imap, what will actually be opened in
imapd is {nntp.example.com/nntp}comp.mail.imap

The OSF/1 port (Digital UNIX, Tru64) now uses flocksim instead of flcksafe.
Some cretin decided to delete the winning flock() call and make flock() use
the losing fcntl() call instead.

The unix[nt] and mmdf drivers now prevent mail_append() from writing Status:,
X-Status:, X-UID, X-IMAP[base]:, and X-Keywords: header lines to a
traditional UNIX or MMDF format mailbox.  If any such lines are in the
text supplied to mail_append(), they will be quoted by prefixing with
&quot;X-Original-&quot; (e.g. Status: will become X-Original-Status:).

There are no user-visible functional enhancements in this version.


Updated: 10 May 2004

imap-2004 is a major release.  Programs written for imap-2002e should
build with this version with minor modification.  imap-2003 was not
released except as development snapshots.

mailutil has three new commands: delete, rename, and prune.

IPv6 support now exists for UNIX and W2K.  It is the default in W2K builds.
On UNIX, add &quot;IP=6&quot; to the make command line.  Windows IPv6 support is
only for W2K builds.

The NNTP driver now supports NNTP SASL and TLS.

The ldb (Debian) and lrh (RedHat) ports now look for mlock on
/usr/sbin/mlock instead of /etc/mlock.

imapd now supports the LITERAL+ and SASL-IR initial-response extensions.

The IMAP driver has some additional checks to reduce the amount of network
traffic, including executing &quot;silly searches&quot; (searches of sequence numbers
only) locally.

The IMAP, POP, SMTP, and NNTP drivers now have diagnostic code to provide
better information about servers which violate SASL's empty challenge
requirements (e.g. with the PLAIN mechanism).

There is a new mail_fetch_overview_sequence() function which is like
mail_fetch_overview() but takes a sequence number string as an argument.
There should have been a flags argument and FT_UID bit as in all the other
mail_fetch_???() functions but compatibility with the past... :-(

The overview_t callback (from mail_fetch_overview()) now has a fourth
argument which contains the message sequence number (as opposed to the UID
which is in the second argument).  It turned out that some applications were
calling mail_msgno() (which can be moderately expensive) to get the sequence
number, and c-client already knew it.

Many declarations which are completely internal to a driver have been removed
from the driver .h file, and in those cases where there are no external
declarations left the .h file has been eliminated entirely.  As part of this,
the mbox driver routines are now incorporated with the unix driver routines
as opposed to being a separate file.  The mbox driver still needs to be lunk
in order to get the mbox functionality.


Updated: 27 August 2003

imap-2002e is a minor release, released concurrently with Pine 4.58, and
contains primarily bugfixes.  Programs written for imap-2002d will build
with this version without modification.

The NNTP client code now tries to perform better with legacy NNTP servers
which do not comply with the current NNTP protocol specification draft, most
notably Netscape Collabra.

Delivery notifications now work reliably with SMTP servers that support it.

The following changes are primarily of concern to developers and power users:

There is a &quot;limited advertise&quot; option in env_unix.c which, if set, will only
advertise the user's own namespace and the #shared/ namespace.

It is now possible to build the IMAP toolkit with a separate SSL KEY file
from the certificate file (SSLKEYS vs. SSLCERTS).

A new BODY structure element, sparep, is available for the main program to
use as a pointer for its own purposes; as well as a SET_FREEBODYSPAREP
function, similar to SET_FREEENVELOPESPAREP, SET_FREEELTSPAREP, etc.


Updated: 28 May 2003

imap-2002d is a minor release, released concurrently with Pine 4.56, and
contains primarily bugfixes.  Programs written for imap-2002 should build
with this version without modification, with one exception.  That exception
is the ngbogus envelope flag, which stopped being used in imap-2002c and is
now gone for good.

The NNTP newsgroup listing code now tries to use wildmats on the NNTP server,
which should result in better performance especially on slow lines.  It is
also once again permitted to log in on NNTP servers when /loser is set.

imapd now supports the UNSELECT command.

A new envelope flag, imapenvonly, indicates that the envelope in a
MESSAGE/RFC822 BODY structure only has the IMAP envelope components and
not the additional components from c-client: Newsgroups, Followup-To,
and References.


Updated: 7 April 2003

imap-2002c is a minor release, released concurrently with Pine 4.55, and
contains primarily bugfixes.  Programs written for imap-2002 will build
with this version without modification.

The POP3 driver will, with new servers that support CAPA, use the LIST
command to get the elt-&gt;rfc822_size and the TOP command to get the message
header, instead of fetching the entire message.  Note that it is a bad idea
to do this with old servers, since they may misimplement LIST and TOP.  The
result is a substantial performance improvement.

Subject extraction for comparisons in SORT and THREAD are now done in full
compliance with the rules laid out in the specification.  This only makes
a difference if &quot;re:&quot; was part of a MIME quoted-word.

The new experimental #move namespace allows download-and-delete from a source
mailbox to a destination mailbox.  Immediately following #move is a delimiter
character which must not appear in the source mailbox name, then the source
mailbox name, then the delimiter again, then the destination mailbox name.
For example:
	#move+{pop3.foo.com/pop3}+INBOX
will download messages from &quot;pop3.foo.com&quot; into your local INBOX.

The NNTP driver now uses the LIST EXTENSIONS command as described in the
current NNTP protocol specification draft, and will prefer to use OVER over
XOVER, HDR over XHDR, etc.

The SET_NNTPRANGE function of mail_parameters() can be used to limit the
number of articles recognized by the NNTP driver, resulting in a substantial
performance improvement with NNTP servers that may have hundreds of thousands
of old articles in the spool.  If set non-zero, then only the last n article
numbers will be considered.  If you are on a slow link, you may want to set
this to 1000 or less.

Besides the normally tested UNIX and 32-bit Microsoft platforms, this release
has also been tested and will once build under TOPS-20 and VAX/VMS.  I also
fixed a bug which would keep it from building on 16-bit DOS, but I don't know
if it will build on that platform or not since I no longer have a system with
the old DOS C compiler.  It has not been tested on Macintosh (note however
that Mac OS X is a type of UNIX and should build), Amiga, or OS/2, and probably
no longer builds on those platforms.


Updated: 7 January 2003

imap-2002b is a maintenace release, released concurrently with Pine 4.52,
and contains only bugfixes.  Programs written for imap-2002 will build with
this version without modification.

Drivers which do not announce new mail are now indicated by the DR_NONEWMAIL
driver flag.  Driver which do not announce new mail when read-only are now
indicated by the DR_NONEWMAILRONLY flag.

There are no user-visible functional enhancements in this version.


Updated: 10 December 2002

imap-2002a is a maintenance release, consisting entirely of critical
bugfixes.  Programs written for imap-2002 will build with this version
without modification.

There are no functional enhancements in this version.


Updated: 28 October 2002

imap-2002 is a major release.  Programs written for imap-2001 will probably
build with this version without modification, with one exception.  That
exception is if the program uses [GS]ET_DISABLEAUTOMATICSHAREDNAMESPACES,
which has been renamed to [GS]ET_DISABLEAUTOSHAREDNS in order to placate
some compilers which don't like very long names.

SSLTYPE=nopwd is now the default, in accordance with current IESG security
requirements.  In order to build the IMAP toolkit without SSL/TLS you must
now use SSLTYPE=none.  At initial build time, you will be told if the SSLTYPE
setting is in compliance with IESG security requirements, and if it is not
you will be asked to confirm to continue the build.

ORDEREDSUBJECT threading has been changed in accordance with draft 12 of the
IMAP threading specification.  Previously, each non-root message in an
ORDEREDSUBJECT thread has been a child of the message immediately preceeding
it in the thread.  Draft 12 changes this so that the second message in the
thread is the child of the first (root) message, and all subsequent messages
are siblings of the first message.  This is significant in MUAs which display
the thread structure graphically; the new definition is much saner than the
old one since it does not nest endlessly due to parent/child relationships
that may not exist.  This also impacts imapd, since imapd's THREAD command
will return a thread structure.

RFC 1730 server support, which was disabled in imap-2001, is now fully
removed from imapd.  imapd still supports IMAP2bis, specifically the FIND
command, since there are still a few IMAP2 clients out there.

The IMAP client routines in the c-client library continue to support recognize
RFC 1730 servers, but do not implement the deprecated features of RFC 1730.

The Frequently Asked Questions file is now in HTML format, although a text
version (generated from the HTML version with Lynx) is also provided.

A new program, mailutil, is now bundled with the IMAP toolkit.  mailutil
replaces the old chkmail, imapcopy, imapmove, imapxfer, mbxcopy, mbxcreat,
and mbxcvt programs that were distributed in the imap-utils.  In addition,
the tmail, dmail, and mlock programs from the imap-utils are now also
bundled with the IMAP toolkit.

In addition to the usual bugfixes, the following c-client functionalities
are new in imap-2002:

The SET_DISABLE822TZTEXT parameter allows a client to suppress generation of
the &quot;human friendly&quot; time zone text in RFC822 dates.  This placates netnews
and some broken SMTP servers which think that long timezone names from Windows
are an attempt at a buffer overflow attack.

The restrictBox option in env_unix.c sets &quot;restricted box&quot; functionality,
which disables access to the root (leading &quot;/&quot;), access to other user's
directories (leading &quot;~&quot;), and access to superior directories via &quot;..&quot;.

Content-Location is now supported by the &quot;location&quot; member of the BODY
structure.  Note that there is a bug in the IMAP client code in older
versions of the c-client library that causes it to handle BODYSTRUCTURE
extension data improperly if that data is a literal.  The new functionality
for Content-Location may trigger this bug.  The fix is either to upgrade
the IMAP client program to the imap-2002 version of c-client or to remove
the Content-Location support from imapd.

There are now 8 spare bits for application use in both the elts and the
mail streams.

mail_search() now returns a value (previously it was void).  If mail_search()
returns NIL, then the supplied charset was invalid or the IMAP server
returned NO (probably because the supplied charset was invalid).

New utf8_charset() routine to look up a charset and return c-client's
database about that charset if found.  Among other things, this will give
you the scripts supported by that charset and its Unicode conversion table.

New FT_NOLOOKAHEAD flag for mail_fetch_structure() disables fetching of
any envelopes other than the one specified.  Otherwise, it will try to do
anticipatory fetching (up to IMAPLOOKAHEAD).

New GET_FETCHLOOKAHEAD allows better control of mail_fetch_structure()
lookahead.  Instead of looking IMAPLOOKAHEAD messages forward from the
specified message, it will use a supplied SEARCHSET to generate message
sequences and ranges.  It will stop at IMAPLOOKAHEAD messages or at the
completion of a range which exceeds IMAPLOOKAHEAD.  The search set only
applies to the next mail_fetch_structure() on that stream, and is cleared
once it is used.  Call with
  SEARCHSET **set = (SEARCHSET **)
    mail_parameters (stream,GET_FETCHLOOKAHEAD,(void *) stream);
  *set = pointer to desired search set

New mail_shortdate() routine returns an date in the format expected by
SEARCHPGMs.


Updated: 2 November 2001

imap-2001a is a maintenance release, consisting primarily of bugfixes
including some critical bugfixes to crash and denial of service problems.
Programs written for imap-2001 will build with this version without
modification.

The following new facilities have also been added:

The new /norsh switch in mailbox names provides a more intuitive way of
disabling rsh-IMAP than the existing :143 or setting the rsh-timeout to 0.

Passwords are no longer returned in mm_dlog() callbacks unless the
application sets the SET_DEBUGSENSITIVE parameter.

The SET_NETFSSTATBUG parameter allows an application to force the
traditional UNIX mailbox driver to close and reopen the mailbox at ping
time.  This is EXTREMELY inefficient, and should only be used to access
files stored on AFS and old NFS systems.

The ISO 8859 and Windows conversion tables have been updated to comply
with Unicode 3.1, and the KOI8-R table has been verified as compliant with
Unicode 3.1.

The SPECIALS mechanism for passing parameters to the lowest level Makefile
has been updated to be more general.  See the next item for why you might
care.

New lrh port to build on Red Hat Linux 7.2, with pre-set definitions for
the places where Red Hat has placed Kerberos and SSL.  It's actually just
the lnp port with SPECIALS defined accordingly.  You may want to use it as
a model if your system needs such definitions.  Note that SPECIALS is
primarily for IMAP toolkit (and Pine) purposes, and that user settings
should use EXTRASPECIALS instead.


Updated: 22 June 2001

imap-2001 is a major release.  Programs written for imap-2000 will probably
build with this version without modification.

The FAQ document has been significantly expanded.  Be sure to read it for
more information.

In addition to the usual bugfixes, the following features are new in
imap-2001:

SSL is now fully integrated into the IMAP toolkit; the old &quot;alt&quot; kludges to
be able to produce a &quot;sanitized&quot; version of the IMAP toolkit to comply with
late unlamented US export regulations are now completely gone.

Full client and server TLS support is also in this release.

The server certificate must be signed by a trusted certificate authority and
the name in the certificate match the user's entry for the server host name;
this means that the user must enter a fully-qualified host name.

To build with SSL/TLS on UNIX, you now use &quot;SSLTYPE=unix&quot; instead of the
former &quot;SPECIALAUTHENTICATORS=ssl&quot;.  To build with SSL/TLS on UNIX and disable
the use of plaintext passwords except when under SSL/TLS, use &quot;SSLTYPE=nopwd&quot;
instead of &quot;SSLTYPE=unix&quot;.

RFC 1730 (IMAP4 as opposed to IMAP4rev1) support is turned off by default in
imapd.  No clients should still be using RFC 1730 protocol.  Look at the imapd
Makefile for how to re-enable RFC 1730 support.  Note that this code may be
removed in the future, so if you think you need it you had better let me know.

There are some new options (turned off by default) which attempt to work around
problems in certain clients.  See the FAQ file for more details.


Updated: 24 January 2001

imap-2000c is a maintenance release, consisting primarily of bugfixes.


Updated: 9 January 2001

imap-2000b is a maintenance release, consisting primarily of bugfixes.


Updated: 9 November 2000

imap-2000a is a maintenance release, consisting primarily of bugfixes.


Updated: 19 September 2000

imap-2000 is a major release.  There are major internal and external changes
from earlier versions (imap-4.x and imap-3.x series).  Programs written for
imap-4.x will probably build with this version without modification.  It is
extremely unlikely that a program written for imap-3.x or earlier series will
build with this version without modifications.  Drivers written for earlier
versions will definitely need to be rewritten.

In addition to the usual bugfixes, the following features are new in imap-2000:

SSL support is now available.  For UNIX, it is necessary to install some
version of OpenSSL; see imap-2000/docs/SSLBUILD for more information.  SSL
support is now automatic for the NT, NTK, and W2K ports.  SSL use is indicated
by the /ssl switch in the mailbox name.

With SSL connections, the server certificate is validated by the client code
on UNIX, and Windows 2000 unless /novalidate-cert is specified.  Server
certificates are currently is not validated on Windows 9x, Windows Millenium,
or Windows NT 4; this is an artifact of the operating system and not the port
(e.g. client code using the NT port will validate certificates if running on
Windows 2000).  On UNIX, the server certificate must be signed by a trusted
certificate authority.  On Windows 2000, the certificate must be signed by a
trusted certificate authority and match the user's entry for the server host
name; this means that the user must enter a fully-qualified host name.

Calendar reclama for the benefit of old broken non-Y2K compliant software.
Two digit years from 00 to 69 will be interpreted as 2000 through 2069.  In
addition, three digit years from 100 to 105 will be interpreted as 2000
through 2005.

Support for REFERENCES threading (in addition to the previously-existing
ORDEREDSUBJECT threading).

Support for the IMAP MULTIAPPEND extension.  This allows much faster uploading
of multiple messages to an IMAP server.

Support for the LOGINDISABLED IMAP capability.  If the IMAP server sends
LOGINDISABLED as a capability, the client code will never attempt to send an
IMAP LOGIN command.

Support for SASL authentication identity vs. authorization identity.  If the
authentication method does not support this concept (e.g. AUTH=CRAM-MD5,
AUTH=LOGIN, LOGIN command), the &quot;*&quot; character in the user name may be used to
indicate a separate authentication identity; for example, &quot;fred*joe&quot; indicates
authorization identity &quot;fred&quot;, authentication identity &quot;joe&quot;.


UNIX-specific Changes:

Support for SASL authentication identity vs. authorization identity in the
IMAP and POP3 servers.  If the user indicated by the authentication identity
is in the &quot;mailadm&quot; group, he may specify any authorization identity and get
logged in as the authorization identity user.

If the IMAP and POP3 servers are build with PASSWDTYPE=nul, it will send
LOGINDISABLED as a capability and also disable the AUTH=LOGIN and AUTH=PLAIN
SASL authenticators.

New MAILSUBDIR build option to change the default mailbox directory from the
user's home directory to a subdirectory of the user's home directory.  See
imap-2000/Makefile for more information.

New CHROOT_SERVER build option for closed server systems only.  If defined, a
chroot() call to the user's home directory is done as part of the login
process.  See imap-2000/Makefile for more information.

New ADVERTISE_THE_WORLD build option which will add an IMAP namespace that
points to the root.  Not for the faint of heart.

UNIX format mailboxes no longer require the pseudo-message, nor will a
pseudo-message be added to a mailbox that does not have one.  A new
X-IMAPbase: header will be written in the first message.  This is rather less
efficient and robust than the pseudo-message (which remains the encouraged
mechanism; UNIX format mailboxes will always be created with it), but perhaps
will pacify some people who get upset by the pseudo-message.

When building with MIT Kerberos it will try to detect and use libk5crypto.a
instead of libcrypto.a.

The mbx driver is more aggressive about cleaning up expunged messages that
couldn't be purged because of shared access to the mailbox at the time of
expunge.  Now, every checkpoint will try to purge such messages; and a
checkpoint is attempted at close time.


Windows-specific Changes:

New W2K port for Windows 2000.  In addition to supporting SSL using the
official SSPI interface (the NT and NTK ports invoke SChannel.DLL directly),
the W2K port also supports Microsoft Kerberos.  Note that the NT and NTK ports
will work on Windows 2000, but the W2K port will not work on NT4, Windows
9x, or Windows Millenium.

There is now a #user namespace, equivalent to the &quot;~&quot; namespace on UNIX.


Changes for Developers:

New c-client.h file which acts as a master include.  c-client based
applications should now include c-client.h instead of the individual c-client
files (mail.h, misc.h, etc.).  It is believed that c-client.h will work in C++
applications.

New GET_FREEENVELOPESPAREP/SET_FREEENVELOPESPAREP and
GET_FREEELTSPAREP/SET_FREEELTSPAREP function callbacks to free the &quot;sparep&quot;
member of the envelope and cache elements, respectively.

New OP_MULNEWSRC flag to mail_open() to use multiple newsrc files, and new
GET_NEWSRCQUERY/SET_NEWSRCQUERY function callbacks to get the name of the
newsrc file for news access.

New &quot;secret&quot; nntp_article() function to do the NNTP ARTICLE command; this is
generally useful only when chasing news URLs.

New GET_HIDEDOTFILES/SET_HIDEDOTFILES feature to suppress file names that
start with &quot;.&quot; in mail_list() results.
                                                                                                                                                                                                                                                                                                                                                                                             calendar.txt                                                                                        0000644                 00000035422 15051750507 0007071 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       /* ========================================================================
 * Copyright 1988-2006 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
 * 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
 *
 * 
 * ========================================================================
 */

			 ALL ABOUT CALENDARS

     Although one can never be sure of what will happen at some future
time, there is strong historical precedent for presuming that the
present Gregorian calendar will still be in effect within the useful
lifetime of the IMAP toolkit.  We have therefore chosen to adhere to
these precedents.
 
     The purpose of a calendar is to reckon time in advance, to show
how many days have to elapse until a certain event takes place in the
future, such as the harvest or the release of a new version of Pine.
The earliest calendars, naturally, were crude and tended to be based
upon the seasons or the lunar cycle.
 

ANCIENT CALENDARS

     The calendar of the Assyrians, for example, was based upon the
phases of the moon.  They knew that a lunation (the time from one full
moon to the next) was 29 1/2 days long, so their lunar year had a
duration of 354 days.  This fell short of the solar year by about 11
days.  (The exact time for the solar year is approximately 365 days, 5
hours, 48 minutes, and 46 seconds.)  After 3 years, such a lunar
calendar would be off by a whole month, so the Assyrians added an extra
month from time to time to keep their calendar in synchronization with
the seasons.
 
     The best approximation that was possible in antiquity was a 19-year
period, with 7 of these 19 years having 13 months (leap months).  This
scheme was adopted as the basis for the lunar calendar used by the
Hebrews.  The Arabs also used this calendar until Mohammed forbade
shifting from 12 months to 13 months; this causes the Muslim holy month
of Ramadan to move backwards through the seasons, completing a cycle
every 32 1/2 years.
 
     When Rome emerged as a world power, the difficulties of making a
calendar were well known, but the Romans complicated their lives because
of their superstition that even numbers were unlucky.  Hence their
months were 29 or 31 days long, with the exception of February, which
had 28 days.  Every second year, the Roman calendar included an extra
month called Mercedonius of 22 or 23 days to keep up with the solar
year.


JULIAN CALENDAR

     Even this algorithm was very poor, so that in 45 BCE, Caesar,
advised by the astronomer Sosigenes, ordered a sweeping reform.  By
imperial decree, the year 46 BCE was made 445 days long to bring the
calendar back in step with the seasons.  The new calendar, similar to
the one we now use was called the Julian calendar (named after Julius
Caesar).

     Months in the Julian calendar were 30 or 31 days in length and
every fourth year was made a leap year (having 366 days) by adding a day
to the end of the year.  This leap year rule was not consistantly
applied until 8 CE.  The year-ending month of February, never a popular
month, was presently shortened so that Julius Caesar and Emperor
Augustus could each have long months named after them.

     Caesar also decreed that the year would start with the first of
January, which since 153 BCE was the day that Roman consuls took office,
and not the vernal equinox in late March.  Not everyone accepted that
part of his reform, as we shall see.

 
GREGORIAN CALENDAR

     Caesar's year was 11 1/2 minutes short of the calculations
recommended by Sosigenes and eventually the date of the vernal equinox
began to drift.  Roger Bacon became alarmed and sent a note to Pope
Clement IV, who apparently was not impressed.  Pope Sixtus IV later
became convinced that another reform was needed and called the German
astronomer, Regiomontanus, to Rome to advise him.  Unfortunately,
Regiomontanus died of the plague shortly thereafter and the plans died
as well.
 
     In 1545, the Council of Trent authorized Pope Gregory XIII to
reform the calendar once more.  Most of the mathematical work was done
by Father Christopher Clavius, S.J.  The immediate correction that was
adopted was that Thursday, October 4, 1582 was to be the last day of the
Julian calendar.  The next day was Friday, with the date of October 15.
For long range accuracy, a formula suggested by the Vatican librarian
Aloysius Giglio was adopted.  It said that every fourth year is a leap
year except for century years that are not divisible by 400.  Thus 1700,
1800 and 1900 would not be leap years, but 2000 would be a leap year
since 2000 is divisible by 400.  This rule eliminates 3 leap years every
4 centuries, making the calendar sufficiently correct for most ordinary
purposes.  This calendar is known as the Gregorian calendar and is the
one that we now use today.

     It is interesting to note that in 1582, all the Protestant princes
ignored the papal decree and so many countries continued to use the
Julian calendar until either 1698 or 1752.  Britain and its American
colonies went from Wednesday, September 2, 1752 to Thursday, September
14.  Prior to the changeover, the British used March 25 as the start of
the new year.

     In Russia, it needed the revolution to introduce the Gregorian
calendar in 1918.  Turkey didn't adopt it until 1927.


NUMBERING OF YEARS

     The numbering of the year is generally done according to an &quot;era&quot;,
such as the year of a ruler's reign.

     In about 525, a monk named Dionysius Exiguus suggested that the
calculated year of Jesus' birth be designated as year 1 in the Julian
calendar.  This suggestion was adopted over the next 500 years and
subsequently followed in the Gregorian calendar.

     For the benefit of those who seek religious significance to the
calendar millenium, note that year 1 is too late by at least 4 years.
Herod the Great, named in the Christian Bible as having all children in
Bethlehem put to death in an attempt to kill the infant Jesus, died in 4
BCE.

     Nothing particularly significant of an historic or religious nature
happened in Gregorian year 1; however it has become a worldwide standard
as the &quot;common era.&quot;  In modern times, the terms &quot;CE&quot; (common era) and
&quot;BCE&quot; (before common era) are preferred over the earlier (and, as we
have seen, less accurate) &quot;AD&quot; (anno Domini, &quot;the year of the Lord&quot;) and
&quot;BC&quot; (before Christ).

     The Hebrew lunar calendar begins at 3760 BCE, the year of creation
in Jewish tradition.  The Muslim lunar calendar begins on July 16, 622,
when Mohammed fled from Mecca to Medina.

     The Japanese, Taiwanese, and North Koreans use the Gregorian
calendar, but number the year by political era.  In Japan, an era
begins when an emperor succeeds to the throne; year 1 of the Heisei
era was 1989 when Emperor Akihito ascended to the throne (the first
few days of 1989 was year 64 of the Shouwa era).  In Taiwan, year 1 is
the first full year after the founding of the Republic of China in 1911.
In North Korea, year 1 is the year of the Juche (self-reliance) ideal,
corresponding to the birth year of founder Kim Il-Sung (1912).  Thus,
year 2000 is Heisei 12 (Japan), 89th year of the Republic (Taiwan),
and Juche 89 (North Korea).


FURTHER MODIFICATIONS TO THE GREGORIAN CALENDAR

     Despite the great accuracy of the Gregorian calendar, it still
falls behind very slightly every few years.  The most serious problem
is that the earth's rotation is slowing gradually.  If you are very
concerned about this problem, we suggest that you tune in short wave
radio station WWV or the Global Positioning System, which broadcasts
official time signals for use in the United States.  About once every
3 years, they declare a leap second at which time you should be
careful to adjust your system clock.  If you have trouble picking up
their signals, we suggest you purchase an atomic clock (not part of
the IMAP toolkit).

     Another problem is that the Gregorian calendar represents a year
of 365.2425 days, whereas the actual time taken for the earth to
rotate around the Sun is 365.2421991 days.  Thus, the Gregorian calendar
is actually 26 seconds slow each year, resulting in the calendar
being one day behind every 3,300 or so years (a Y3.3K problem).

     Consequently, the Gregorian calendar has been modified with a
further rule, which is that years evenly divisible by 4000 are not
leap years.  Thus, the year 4000 will not be a leap year.  Or, at
least we assume that's what will happen assuming that the calendar
remains unchanged for the next 2000 years.

     The modified Gregorian calendar represents a year of 365.24225
days.  Thus, the modified Gregorian calendar is actually 4 seconds
slow each year, resulting in the calendar being one day slow every
20,000 or so years.  So there will be a Y20K problem.

     There is some dispute whether the modified Gregorian calendar was
officially adopted, or if it's just a proposal.  Other options (see
below) exist; fortunately no decision needs to be made for several
centuries yet.

     There is code in c-client to support the modified Gregorian
calendar, although it is currently disabled.  Sometime in the next
2000 years, someone will need to enable this code so that c-client is
Y4K compiliant.  Then, 18,000 years from now, someone will have to
tear into c-client's code to fix the Y20K bug.


EASTERN ORTHODOX MODIFICATION OF THE GREGORIAN CALENDAR

     The Eastern Orthodox church in 1923 established its own rules to
correct the Julian calendar.  In their calendar, century years modulo
900 must result in value of 200 or 600 to be considered a leap year.
Both the Orthodox and Gregorian calendar agree that the years 2000 and
2400 will be leap years, and the years 1900, 2100, 2200, 2300, 2500,
2600, 2700 are not.  However, the year 2800 will be a leap year in the
Gregorian calendar but not in the Orthodox calendar; similarly, the
year 2900 will be a leap year in the Orthodox calendar but not in the
Gregorian calendar.  Both calendars will agree that 3000 and
3100 are leap years, but will disagree again in 3200 and 3300.

     There is code in c-client to support the Orthodox calendar.  It
can be enabled by adding -DUSEORTHODOXCALENDAR=1 to the c-client
CFLAGS, e.g.
	make xxx EXTRACFLAGS=&quot;-DUSEORTHODOXCALENDAR=1&quot;

     The Orthodox calendar represents a year of 365.24222222... days.
Thus, the Orthodox calendar is actually 2 seconds slow each year,
resulting in the calendar being one day slow every 40,000 or so years.
The Eastern Orthodox church has not yet made any statements on how the
Y40K bug will be fixed.


OTHER ISSUES AFFECTING THE CALENDAR IN THE FUTURE

     The effect of leap seconds also needs to be considered when
looking at the Y3.3K/Y4K, Y20K, and Y40K problems.  Leap seconds put
the clock back in line with the Earth's rotation, whereas leap years
put the calendar back in line with the Earth's revolution.  Since leap
seconds slow down the clock (and hence the calendar), they actually
bring the day of reckoning for the Gregorian and Orthodox calendars
sooner.

     Another factor is that the next ice age (technically, the end of
the current interglacial period; we are in the middle of an ice age
now!) is due around Y25K.  It is not known what perturbations this will
cause on the Earth's rotation and revolution, nor what calendar
adjustments will be necessary at that time.

     Hence my use of &quot;or so&quot; in predicting the years that the calendar
will fall behind.  The actual point may be anywhere from decades (in the
case of Y3.3K) to millenia (in the case of Y40K) off from these predictions.


MEANINGS OF DAY NAMES

     The names of days of the week from a combination of Roman and
Germanic names for celestial bodies:
. Sunday	Latin &quot;dies solis&quot; =&gt; &quot;Sun's day&quot;
. Monday	Latin &quot;dies lunae&quot; =&gt; &quot;Moon's day&quot;
. Tuesday	Germanic &quot;Tiw's day&quot; =&gt; &quot;Mars' day&quot;
. Wednesday	Germanic &quot;Woden's day&quot; =&gt; &quot;Mercury's day&quot;
. Thursday	Germanic &quot;Thor's day&quot; =&gt; &quot;Jupiter's day&quot;
. Friday	Germanic &quot;Frigg's day&quot; =&gt; &quot;Venus' day&quot;
. Saturday	Latin &quot;dies Saturni&quot; =&gt; &quot;Saturn's day&quot;


MEANINGS OF MONTH NAMES

     The names of the months are from the Roman calendar:
. January	Janus, protector of doorways
. February	Februalia, a time for sacrifice to atone for sins
. March		Mars, god of war
. April		Latin &quot;aperire&quot; =&gt; &quot;to open&quot; buds
. May		Maia, goddess of plant growth
. June		Latin &quot;juvenis&quot; =&gt; &quot;youth&quot;
. July		Julius Caesar
. August	Augustus Caesar
. September	Latin &quot;septem&quot; =&gt; &quot;seven&quot;
. October	Latin &quot;octo&quot; =&gt; &quot;eight&quot;
. November	Latin &quot;novem&quot; =&gt; &quot;nine&quot;
. December	Latin &quot;decem&quot; =&gt; &quot;ten&quot;

     As you'll notice, the last four months are numbered 7 to 10, which
is an artifact of the time when the new year started in March.


INTERESTING FORMULAE

     There's another reason why the historical starting of the new year
is significant.  Starting with March, the length of months follows a
mathematical series:
	31 30 31 30 31 31 30 31 30 31 31 28

     This means that you can calculate the day of week for any
arbitrary day/month/year of the Gregorian calendar with the following
formula (note all divisions are integral):
        _                                      _
       |     7 + 31*(m - 1)       y    y     y  |
 dow = | d + -------------- + y + - - --- + --- | MOD 7
       |_          12             4   100   400_|
where
 d   := day of month (1..31)
 m   := month in old style (March = 1..February = 12)
 y   := year in old style
 dow := day of week (Tuesday = 0..Monday = 6)

     To convert from new style month/year to old style:
  if (m &gt; 2) m -= 2;		/* Mar-Dec: subtract 2 from month */
  else m += 10,y--;		/* Jan-Feb: months 11 &amp; 12 of previous year */

     Here's another fun formula.  To find the number of days between two
days, calculate a pair of calendar days with the formula (again, all
divisions are integral), using new style month/year this time:
                        m
                    m + -
                        8             y    y     y
 d + 30 * (m - 1) + ----- + y * 365 + - - --- + --- - ld
                      2               4   100   400

where:
 d   := day of month (1..31)
 m   := month in new style (January = 1..December = 12)
 y   := year in new style
 ld  := leap day correction factor:
	0 for January and February in non-leap years
	1 for January and February in leap years
	2 for all other months in all years        

     In C code, the leap day correction factor is calculated as:
  (m &lt; 3) ? !(y % 4) &amp;&amp; ((y % 100) || !(y % 400)) : 2

     It's up to you to figure out how to adapt these formulas for the
Y4K bugfix and the Orthodox calendar.  If you're really clever, try to
use these formulae to implement the C library ctime(), gmtime(), and
mktime() functions.  Most C library implementations use a table of the
number of days in a month.  You don't need it.


ACKNOWLEDGEMENT:

The original version is from an old Digital Equipment Corporation SPR
answer for VMS.  Modifications for c-client, and additional information
added by Mark Crispin.
                                                                                                                                                                                                                                              SUPPORT                                                                                             0000644                 00000001475 15051750507 0005657 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       /* ========================================================================
 * Copyright 1988-2006 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
 * 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
 *
 * 
 * ========================================================================
 */

			     BUG REPORTING ADDRESS

     Bug reports, comments, or questions regarding this software may
be reported to the imap-uw@u.washington.edu mailing list (this replaces
the old c-client@u.washington.edu mailing list).  You can subscribe to
this list by sending a message to:
	imap-uw-subscribe@mailman.u.washington.edu

     An alternative is to use the comp.mail.imap newsgroup.
                                                                                                                                                                                                   SSLBUILD                                                                                            0000644                 00000025722 15051750507 0005725 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       /* ========================================================================
 * Copyright 1988-2007 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
 * 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
 *
 * 
 * ========================================================================
 */

		  SSL/TLS BUILD AND INSTALLATION NOTES FOR UNIX
			 Last Updated: 15 November 2007

PREREQUISITES BEFORE STARTING:
 1) Review the information in imap-2007/docs/BUILD.
 2) Obtain a copy of OpenSSL.  OpenSSL is available from third parties.  We
    do not provide OpenSSL.
 3) Make sure that you know how to build OpenSSL properly on the standard
    /usr/local/ssl directory.  In particular, /usr/local/ssl/include (and
    /usr/local/ssl/include/openssl) and /usr/local/ssl/lib must be set up
    from the OpenSSL build.  If you have a non-standard installation, then
    you must modify the imap-2007/src/osdep/unix/Makefile file to point
    to the appropriate locations.
 4) Make sure that you know how to obtain appropriate certificates on your
    system.

NOTE: We can NOT provide you with support in building/installing OpenSSL, or
in obtaining certificates.  If you need help in doing this, try the contacts
mentioned in the OpenSSL README.


SSL BUILD:

     By default, the IMAP toolkit builds with SSL and disabling plaintext
passwords unless SSL/TLS encryption is in effect (SSLTYPE=nopwd).  This
produces an IMAP server which is compliant with RFC 3501 security
requirements.

     To build with SSL but allow plaintext passwords in insecure sessions,
add &quot;SSLTYPE=unix&quot; to the make command line.  Note that doing so will
produce an IMAP server which is NON-COMPLIANT with RFC 3501.

     To build without SSL, add &quot;SSLTYPE=none&quot; to the make command line.
Note that doing so will produce an IMAP server which is NON-COMPLIANT
with RFC 3501.

     There are other make options relevant to SSL, described in
 imap-2007/src/osdep/unix/Makefile
The most important of these are SSLDIR, SSLCRYPTO, and SSLRSA.

     SSLDIR is set to /usr/local/ssl by default.  This is the normal
installation directory for OpenSSL.  If your system uses a different directory
you will need to change this.

     SSLCRYPTO is set to -lcrypto by default.  Older versions of MIT Kerberos
also have a libcrypto and will cause a library name conflict.  If you are
using an older version of Kerberos, you may need to change SSLCRYPTO to
$(SSLLIB)/libcrypto.a

     SSLRSA is set empty by default.  It can be set to specify the RSAREF
libraries, which you once had to use with OpenSSL to use RSA algorithms
legally if you are in the USA, due to patent issues.  Since RSA Security Inc.
released the RSA algorithm into the public domain on September 6, 2000, there
is no longer any reason to do this.


SSL INSTALLATION:

     Binaries from the build are:
	imap-2007/mtest/mtest		c-client testbed program
	imap-2007/ipopd/ipop2d		POP2 daemon
	imap-2007/ipopd/ipop3d		POP3 daemon
	imap-2007/imapd/imapd		IMAP4rev1 daemon

     mtest is normally not used except by c-client developers.

STEP 1:	inetd setup


     The ipop2d, ipop3d, and imapd daemons should be installed in a system
daemon directory and invoked by a listener such as xinetd or inetd.  In the
following examples, /usr/local/etc is used).

STEP 1(A): xinetd-specific setup

     If your system uses xinetd, the daemons are invoked by files in your
/etc/xinetd.d directory with names corresponding to the service names (that
is: imap, imaps, pop2, pop3, pop3s).  You will need to consult your local
xinetd documentation to see what should go into these files.  Here is a a
sample /etc/xinetd.d/imaps file:

service imaps
{
	disable		= no
	socket_type	= stream
	wait		= no
	user		= root
	server		= /usr/local/etc/imapd
	groups		= yes
	flags		= REUSE IPv6
}

STEP 1(B): inetd-specific setup

     If your system still uses inetd, the daemons are invoked by your
/etc/inetd.conf file with lines such as:

pop	stream	tcp	nowait	root	/usr/local/etc/ipop2d	ipop2d
pop3	stream	tcp	nowait	root	/usr/local/etc/ipop3d	ipop3d
imap	stream	tcp	nowait	root	/usr/local/etc/imapd	imapd
pop3s	stream	tcp	nowait	root	/usr/local/etc/ipop3d	ipop3d
imaps	stream	tcp	nowait	root	/usr/local/etc/imapd	imapd

     Please refer to imap-2007/docs/BUILD for an important note about inetd's
limit on the number of new connections.  If that note applies to you, and you
can configure the number of connection in /etc/inetd.conf as described in
imap-2007/docs/build, here is the sample /etc/inetd.conf entry with SSL:

pop3	stream	tcp	nowait.100	root	/usr/local/etc/ipop3d	ipop3d
pop3s	stream	tcp	nowait.100	root	/usr/local/etc/ipop3d	ipop3d
imap	stream	tcp	nowait.100	root	/usr/local/etc/imapd	imapd
imaps	stream	tcp	nowait.100	root	/usr/local/etc/imapd	imapd
 (or, if you use TCP wrappers)
pop3	stream	tcp	nowait.100	root	/usr/local/etc/tcpd	ipop3d
imap	stream	tcp	nowait.100	root	/usr/local/etc/tcpd	imapd
pop3s	stream	tcp	nowait.100	root	/usr/local/etc/ipop3d	ipop3d
imaps	stream	tcp	nowait.100	root	/usr/local/etc/imapd	imapd

NOTE: do *NOT* use TCP wrappers (tcpd) for the imaps and pop3s services!  I
don't know why, but it doesn't work with TCP wrappers.


STEP 2:	services setup

     You may also have to edit your /etc/services (or Yellow Pages,
NetInfo, etc. equivalent) to register these services, such as:

pop		109/tcp
pop3		110/tcp
imap		143/tcp
imaps		993/tcp
pop3s		995/tcp

NOTE: The SSL IMAP service *MUST* be called &quot;imaps&quot;, and the SSL POP3 service
*MUST* be called &quot;pop3s&quot;.


STEP 3: PAM setup

     If your system has PAM (Pluggable Authentication Modules -- most
modern systems do) then you need to set up PAM authenticators for imap and
pop.  The correct file names are
	/etc/pam.d/imap
and
	/etc/pam.d/pop

     It probably works to copy your /etc/pam.d/ftpd file to the above two
names.

     Many people get these file names wrong, and then spend a lot of time
trying to figure out why it doesn't work.  Common mistakes are:
	/etc/pam.d/imapd
	/etc/pam.d/imap4
	/etc/pam.d/imap4rev1
	/etc/pam.d/imaps
	/etc/pam.d/ipop3d
	/etc/pam.d/pop3d
	/etc/pam.d/popd
	/etc/pam.d/pop3
	/etc/pam.d/pop3s


STEP 4:	certificates setup

NOTE: We can NOT provide you with support in obtaining certificates.  If you
need help in doing this, try the contacts mentioned in the OpenSSL README.

WARNING: Do NOT install servers built with SSL support unless you also plan to
install proper certificates!  It is NOT supported to run SSL-enabled servers
on a system without the proper certificates.

     You must set up certificates on /usr/local/ssl/certs (this may be
different if you have a non-standard installation of OpenSSL; for example,
FreeBSD has modified OpenSSL to use /usr/local/certs).  You should install
both the certificate authority certificates from the SSL distribution after
building OpenSSL, plus your own certificates.  The latter should have been
purchased from a certificate authority, although self-signed certificates are
permissible.  A sample certificate file is at the end of this document.

     Install the resulting certificate file on /usr/local/ssl/certs, with a
file name consisting of the server name and a suffix of &quot;.pem&quot;.  For example,
install the imapd certificate on /usr/local/ssl/certs/imapd.pem and the ipop3d
certificate on /usr/local/ssl/certs/ipop3d.pem.  These files should be
protected against random people accessing them.  It is permissible for
imapd.pem and ipop3d.pem to be links to the same file.

     The imapd.pem and ipop3d.pem must contain a private key and a
certificate.  The private key must not be encrypted.

     The following command to openssl can be used to create a self-signed
certificate with a 10-year expiration:
	req -new -x509 -nodes -out imapd.pem -keyout imapd.pem -days 3650

			*** IMPORTANT ***
     We DO NOT recommend, encourage, or sanction the use of self-signed
certificates.  Nor will we be responsible for any problems (including security
problems!) which result from your use of a self-signed certificate.  Use of
self-signed certificates should be limited to testing only.  Buy a real
certificate from a certificate authority!

			*** IMPORTANT ***

     If you have a multihomed system with multiple domain names (and hence
separate certificates for each domain name), you can append the IP address
to the service name.  For example, the IMAP certificate for [12.34.56.78]
would be /usr/local/ssl/certs/imapd-12.34.56.78.pem and so on.  You only need
to use this feature if you need to use multiple certificates (because different
DNS names are used).


SAMPLE CERTIFICATE FILE

     Here is a sample certificate file.  Do *NOT* use this on your own
machine; it is simply an example of what one would look like.

-----BEGIN RSA PRIVATE KEY-----
MIICXQIBAAKBgQDHkqs4YDbakYxRkYXIpY7xLXDQwULR5LW7xWVzuWmmZJOtzwlP
7mN87g+aaiQzwXUVndaCw3Zm6cOG4mytf20jPZq0tvWnjEB3763sorpfpOe/4Vsn
VBFjyQY6YdqYXNmjmzff5gTAecEXOcJ8CrPsaK+nkhw7bHUHX2X+97oMNQIDAQAB
AoGBAMd3YkZAc9LUsig8iDhYsJuAzUb4Qi7Cppj73EBjyqKR18BaM3Z+T1VoIpQ1
DeXkr39heCrN7aNCdTh1SiXGPG6+fkGj9HVw7LmjwXclp4UZwWp3fVbSAWfe3VRe
LM/6p65qogEYuBRMhbSmsn9rBgz3tYVU0lDMZvWxQmUWWg7BAkEA6EbMJeCVdAYu
nQsjwf4vhsHJTChKv/He6kT93Yr/rvq5ihIAPQK/hwcmWf05P9F6bdrA6JTOm3xu
TvJsT/rIvQJBANv0yczI5pUQszw4s+LTzH+kZSb6asWp316BAMDedX+7ID4HaeKk
e4JnBK//xHKVP7xmHuioKYtRlsnuHpWVtNkCQQDPru2+OE6pTRXEqT8xp3sLPJ4m
ECi18yfjxAhRXIU9CUV4ZJv98UUbEJOEBtx3aW/UZbHyw4rwj5N511xtLsjpAkA9
p1XRYxbO/clfvf0ePYP621fHHzZChaUo1jwh07lXvloBSQ6zCqvcF4hG1Qh5ncAp
zO4pBMnwVURRAb/s6fOxAkADv2Tilu1asafmqVzpnRsdfBZx2Xt4oPtquR9IN0Q1
ewRxOC13KZwoAWtkS7l0mY19WD27onF6iAaF7beuK/Va
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIIECTCCA3KgAwIBAgIBADANBgkqhkiG9w0BAQQFADCBujELMAkGA1UEBhMCVVMx
EzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1NlYXR0bGUxHzAdBgNVBAoT
FkJsdXJkeWJsb29wIEluZHVzdHJpZXMxFjAUBgNVBAsTDUlTIERlcGFydG1lbnQx
ITAfBgNVBAMTGEJvbWJhc3RpYyBULiBCbHVyZHlibG9vcDEoMCYGCSqGSIb3DQEJ
ARYZYm9tYmFzdGljQGJsdXJkeWJsb29wLmNvbTAeFw0wMDA2MDYwMDUxMTRaFw0x
MDA2MDQwMDUxMTRaMIG6MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3Rv
bjEQMA4GA1UEBxMHU2VhdHRsZTEfMB0GA1UEChMWQmx1cmR5Ymxvb3AgSW5kdXN0
cmllczEWMBQGA1UECxMNSVMgRGVwYXJ0bWVudDEhMB8GA1UEAxMYQm9tYmFzdGlj
IFQuIEJsdXJkeWJsb29wMSgwJgYJKoZIhvcNAQkBFhlib21iYXN0aWNAYmx1cmR5
Ymxvb3AuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDHkqs4YDbakYxR
kYXIpY7xLXDQwULR5LW7xWVzuWmmZJOtzwlP7mN87g+aaiQzwXUVndaCw3Zm6cOG
4mytf20jPZq0tvWnjEB3763sorpfpOe/4VsnVBFjyQY6YdqYXNmjmzff5gTAecEX
OcJ8CrPsaK+nkhw7bHUHX2X+97oMNQIDAQABo4IBGzCCARcwHQYDVR0OBBYEFD+g
lcPrnpsSvIdkm/eol4sYYg09MIHnBgNVHSMEgd8wgdyAFD+glcPrnpsSvIdkm/eo
l4sYYg09oYHApIG9MIG6MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3Rv
bjEQMA4GA1UEBxMHU2VhdHRsZTEfMB0GA1UEChMWQmx1cmR5Ymxvb3AgSW5kdXN0
cmllczEWMBQGA1UECxMNSVMgRGVwYXJ0bWVudDEhMB8GA1UEAxMYQm9tYmFzdGlj
IFQuIEJsdXJkeWJsb29wMSgwJgYJKoZIhvcNAQkBFhlib21iYXN0aWNAYmx1cmR5
Ymxvb3AuY29tggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEEBQADgYEAwEEk
JXpVXVaFTuG2VJGIzPOxQ+X3V1Cl86y4gM1bDbqlilOUdByUEG4YfSb8ILIn+eXk
WzMAw63Ww5t0/jkO5JRs6i1SUt0Oy80DryNRJYLBVBi499WEduro8GCVD8HuSkDC
yL1Rdq8qlNhWPsggcbhuhvpbEz4pAfzPkrWMBn4=
-----END CERTIFICATE-----
                                              naming.txt                                                                                          0000644                 00000011637 15051750507 0006573 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       /* ========================================================================
 * Copyright 1988-2006 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
 * 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
 *
 * 
 * ========================================================================
 */

		       Mailbox Name Conventions
			     Mark Crispin
			    5 October 2005


Please refer to the file drivers.txt for related information.


I. Special names

Special names appear by themselves.

I.a. INBOX

The name INBOX is special and refers to primary incoming message
mailbox on the local system.


I.b. #mhinbox (UNIX only)

The name #mhinbox is special and refers to the primary incoming mh
format mailbox on the local system.  Don't worry about this if you
don't know what mh format is.


II.  Special prefixes

All names which start with a &quot;#&quot; have a &quot;special prefix&quot; which
identifies an alternative namespace.  Special prefixes appear in front
of some additional text which constitutes a suffix.

II.a. #mh/ (UNIX only)

The prefix #mh/ is special and refers to the mh format mailbox named
with the suffix.  For example, #mh/foo refers to the mh format mailbox
named foo.  Don't worry about this if you don't know what mh format is.


II.b. #news. (UNIX only)

The prefix #news. is special and refers to the newsgroup named with
the suffix.  For example, #news.comp.mail.misc refers to the newsgroup
named comp.mail.misc.


II.c. #ftp/ (UNIX only)

The prefix #ftp/ is special and refers to the anonymous ftp filesystem
named with the suffix.  For example, #ftp/foo/bar refers to the file
/foo/bar in the anonymous FTP filesystem.  Anonymous FTP files are
available to anonymous IMAP logins.


II.d. #public/ (UNIX only)

The prefix #public/ is special and refers to the public files
filesystem named with the suffix.  For example, #public/foo/bar refers
to the file /foo/bar in the public filesystem.  Public files are
available to anonymous IMAP logins.


II.e. #shared/ (UNIX only)

The prefix #shared/ is special and refers to the shared files
filesystem named with the suffix.  For example, #shared/foo/bar
frefers to the file /foo/bar in the shared filesystem.


III. Remote names

All names which start with &quot;{&quot; are remote names, and are in the form
	&quot;{&quot; remote_system_name [&quot;:&quot; port] [flags] &quot;}&quot; [mailbox_name]
where:
 remote_system_name	Internet domain name or bracketed IP address
			 of server.
 port			optional TCP port number, default is the
			 default port for that service		
 flags			optional flags, one of the following:
  &quot;/service=&quot; service	mailbox access service, default is &quot;imap&quot;
  &quot;/user=&quot; user		remote user name for login on the server
  &quot;/authuser=&quot; user	remote authentication user; if specified this
			 is the user name whose password is used (e.g.
			 administrator)
  &quot;/anonymous&quot;		remote access as anonymous user
  &quot;/debug&quot;		record protocol telemetry in application's
			 debug log
  &quot;/secure&quot;		do not transmit a plaintext password over
			 the network
  &quot;/imap&quot;, &quot;/imap2&quot;, &quot;/imap2bis&quot;, &quot;/imap4&quot;, &quot;/imap4rev1&quot;
			equivalent to /service=imap
  &quot;/pop3&quot;		equivalent to /service=pop3
  &quot;/nntp&quot;		equivalent to /service=nntp
  &quot;/norsh&quot;		do not use rsh or ssh to establish a preauthenticated
			 IMAP session
  &quot;/ssl&quot;		use the Secure Socket Layer to encrypt the session
  &quot;/validate-cert&quot;	validate certificates from TLS/SSL server (this is the
			 default behavior)
  &quot;/novalidate-cert&quot;	do not validate certificates from TLS/SSL server,
			 needed if server uses self-signed certificates
  &quot;/tls&quot;		force use of start-TLS to encrypt the session, and
			 reject connection to servers that do not support it
  &quot;/tls-sslv23&quot;		use the depreciated SSLv23 client when negotiating
			 TLS to the server.  This is necessary with some
			 broken servers which (incorrectly) think that TLS
			 is just another way of doing SSL.
  &quot;/notls&quot;		do not do start-TLS to encrypt the session, even
			 with servers that support it
  &quot;/readonly&quot;		request read-only mailbox open (IMAP only; ignored
			 on NNTP, and an error with SMTP and POP3)
  &quot;/loser&quot;		disable various protocol features and perform various
			 client-side workarounds; for example, it disables
			 the SEARCH command in IMAP and does client-side
			 searching instead.  The precise measures taken by
			 /loser depend upon the protocol and are subject to
			 change over time.  /loser is intended for use with
			 defective servers which do not implement the
			 protocol specification correctly.  It should be used
			 only as a last resort since it will seriously
			 degrade performance.
 mailbox_name		remote mailbox name, default is INBOX

For example:
	{imap.foo.com}INBOX
opens an IMAP connection to system imap.foo.com and selects INBOX.


IV. All other names

All other names are treated as local file names, relative to the
user's home directory.  Read drivers.txt for more details.
                                                                                                 formats.txt                                                                                         0000644                 00000021646 15051750507 0006776 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       /* ========================================================================
 * Copyright 1988-2006 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
 * 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
 *
 * 
 * ========================================================================
 */

		    Mailbox Format Characteristics
			     Mark Crispin
			   11 December 2006


     When a mailbox storage technology uses local files and
directories directly, the file(s) and directories are layed out in a
mailbox format.

I. Flat-File Formats

     In these formats, a mailbox and all the messages inside are a
single file on the filesystem.  The mailbox name is the name of the
file in the filesystem, relative to the user's &quot;mail home directory.&quot;

     A flat-file format mailbox is always a file, never a directory.
This means that it is impossible to have a flat-file format mailbox
that has inferior mailbox names under it (so-called &quot;dual-usage&quot;
mailboxes).  For some inexplicable reason, some people want this.

     The mail home directory is usually the same as the user login
home directory if that concept is meaningful; otherwise, it is some
other default directory (e.g. &quot;C:\My Documents&quot; on Windows 98).  This
can be redefined by modifying the c-client source code or in an
application via the SET_HOMEDIR mail_parameters() call.

     For example, a mailbox named &quot;project&quot; is likely to be found in
the file &quot;project&quot; in the user's home directory.  Similarly, a mailbox
named &quot;test/trial1&quot; (assuming a UNIX system) is likely to be found in
the file &quot;trial1&quot; in the subdirectory &quot;test&quot; in the user's home
directory.

     Note that the name &quot;INBOX&quot; has special semantics and rules, as
described in the file naming.txt.

     The following flat-file formats are supported by c-client as of
the time of this writing:

. unix	This is the traditional UNIX mailbox format, in use for nearly
	30 years.  It uses a line starting with &quot;From &quot; to indicate
	start of message, and stores the message status inside the
	RFC822 message header.

	unix is not particularly efficient; the entire mailbox file
	must be read when the mailbox is open, and when reading message
	texts it is necessary to convert the newline convention to
	Internet standard CR LF form.  unix preserves UIDs, and allows
	the creation of keywords.

	Only one process may have a unix-format mailbox open
	read/write at a time.

. mmdf	This is the format used by the MMDF mailer.  It uses a line
	consisting of 4 &lt;CTRL/A&gt; (0x01) characters to indicate start
	and end of message.  Optionally, there may also be a unix
	format &quot;From &quot; line.  It otherwise has the same
	characteristics as unix format.

. mbx	This is the current preferred mailbox format.  It can be
	handled quite efficiently by c-client, without the problems
	that exist with unix and mmdf formats.  Messages are stored
	in Internet standard CR LF format.

	mbx permits shared access, including shared expunge.  It
	preserves UIDs, and allows the creation of keywords.

. mtx	This is supported for compatibility with the past.  This is
	the old Tenex/TOPS-20 mail.txt format.  It can be handled
	quite efficiently by c-client, and has most of the
	characteristics of mbx format.

	mtx is deficient in that it does not support shared expunge;
	it has no means to store UIDs; and it has no way to define
	keywords except through an external configuration file.

. tenex	This is supported for compatibility with the past.  This is
	the old Columbia MM format.  This is similar to mtx format,
	only it uses UNIX-style bare-LF newlines instead of CR LF
	newlines, thus incurring a performance penalty for newline
	conversion.

. phile	This is not strictly a format.  Any file which is not in a
	recognized format is in phile format, which treats the entire
	contents of the file as a single message.


II. File/Message Formats

     In these formats, a mailbox is a directory, and each the messages
inside are separate files inside the directory.  The file names of
these files are generally the text form of a number, which also
matches the UID of the message.

     In the case of mx, the mailbox name is the name of the directory
in the filesystem, relative to the user's &quot;mail home directory.&quot;  In
the case of news and mh, the mailbox name is in a separate namespace
as described in the file naming.txt.

     A file/message format mailbox is always a directory.  This means
that it is possible to have a file/message format mailbox that has
inferior mailbox names under it (so-called &quot;dual-usage&quot; mailboxes).
For some inexplicable reason, some people want this.

     Note that the name &quot;INBOX&quot; has special semantics and rules, as
described in the file naming.txt.

     The following file/message formats are supported by c-client as of
the time of this writing:

. mx	This is an experimental format, and may be removed in a future
	release.  An mx format mailbox has a .mxindex file which holds
	the message status and unique identifiers.  Messages are
	stored in Internet standard CF LF form, so the file size of
	the message file equals the size of the message.

	mx is somewhat inefficient; the entire directory must be read
	and each file stat()'d.  We found it intolerable for a
	moderate sized mailbox (2000 messages) and have more or less
	abandoned it.	

. mh	This is supported for compatibility with the past.  This is
	the format used by the old mh program.

	mh is very inefficient; the entire directory must be read
	and each file stat()'d, and in order to determine the size
	of a message, the entire file must be read and newline
	conversion performed.

	mh is deficient in that it does not support any permanent
	flags or keywords; and has no means to store UIDs (because
	the mh &quot;compress&quot; command renames all the files, that's
	why).

. news	This is an export of the local filesystem's news spool, e.g.
	/var/spool/news.  Access to mailboxes in news format is read
	only; however, message &quot;deleted&quot; status is preserved in a
	.newsrc file in the user's home directory.  There is no other
	status or keywords.

	news is very inefficient; the entire directory must be
	read and each file stat()'d, and in order to determine the
	size of a message, the entire file must be read and newline
	conversion performed.

	news is deficient in that it does not support permanent flags
	other than deleted; does not support keywords; and has no
	expunge.


Soapbox on File/Message Formats

     If it sounds from the above descriptions that we're not putting
too much effort into file/message formats, you are correct.

     There's a general reason why file/message formats are a bad idea.
Just about every filesystem in existance serializes file creation and
deletions because these manipulate the free space map.  This turns out
to be an enormous problem when you start creating/deleting more than a
few messages per second; you spend all your time thrashing in the
filesystem.

     It is also extremely slow to do a text search through a
file/message format mailbox.  All of those open()s and close()s really
add up to major filesystem thrashing.


What about Cyrus and Maildir?

     Both formats are vulnerable to the filesystem thrashing outlined
above.

     The Cyrus format used by CMU's Cyrus server (and Esys' server)
has a special associated flat file in each directory that contains
extensive data (including pre-parsed ENVELOPEs and BODYSTRUCTUREs)
about the messages.  Put another way, it's a (considerably) more
featureful form of mx.  It also uses certain operating system
facilities (e.g. file/memory mapping) which are not available on older
systems, at a cost of much more limited portability than c-client.
These considerably ameliorate the fundamental problems with
file/message formats; in fact, Cyrus is halfway to being a database.
Rather than support Cyrus format in c-client, you should run Cyrus or
Esys if you want that format.

     The Maildir format used by qmail has all of the performance
disadvantages of mh noted above, with the additional problem that the
files are renamed in order to change their status so you end up having
to rescan the directory frequently to locate the current names
(particularly in a shared mailbox scenario).  It doesn't scale, and it
represents a support nightmare; it is therefore not supported in the
official distribution.  Maildir support code for c-client is available
from third parties; but, if you use it, it is entirely at your own
risk (read: don't complain about how poorly it performs or bugs).


So what does this all mean?

     A database (such as used by Exchange) is really a much better
approach if you want to move away from flat files.  mx and especially
Cyrus take a tenative step in that direction; mx failed mostly because
it didn't go anywhere near far enough.  Cyrus goes much further, and
scores remarkable benefits from doing so.

     However, a well-designed pure database without the overhead of
separate files would do even better.
                                                                                          FAQ.txt                                                                                             0000644                 00000430660 15051750507 0005732 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       /* ========================================================================
 * Copyright 1988-2007 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
 * 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
 *
 *
 * ========================================================================
 */

                    IMAP Toolkit Frequently Asked Questions

Table of Contents

     * 1. General/Software Feature Questions
          + 1.1 Can I set up a POP or IMAP server on UNIX/Linux/OSF/etc.?
          + 1.2 I am currently using qpopper as my POP3 server on UNIX.
            Do I need to replace it with ipop3d in order to run imapd?
          + 1.3 Can I set up a POP or IMAP server on Windows XP, 2000,
            NT, Me, 98, or 95?
          + 1.4 Can I set up a POP or IMAP server on Windows 3.1 or DOS?
          + 1.5 Can I set up a POP or IMAP server on Macintosh?
          + 1.6 Can I set up a POP or IMAP server on VAX/VMS?
          + 1.7 Can I set up a POP or IMAP server on TOPS-20?
          + 1.8 Are hierarchical mailboxes supported?
          + 1.9 Are &quot;dual-use&quot; mailboxes supported?
          + 1.10 Can I have a mailbox that has both messages and
            sub-mailboxes?
          + 1.11 What is the difference between &quot;mailbox&quot; and &quot;folder&quot;?
          + 1.12 What is the status of internationalization?
          + 1.13 Can I use SSL?
          + 1.14 Can I use TLS and the STARTTLS facility?
          + 1.15 Can I use CRAM-MD5 authentication?
          + 1.16 Can I use APOP authentication?
          + 1.17 Can I use Kerberos V5?
          + 1.18 Can I use PAM for plaintext passwords?
          + 1.19 Can I use Kerberos 5 for plaintext passwords?
          + 1.20 Can I use AFS for plaintext passwords?
          + 1.21 Can I use DCE for plaintext passwords?
          + 1.22 Can I use the CRAM-MD5 database for plaintext passwords?
          + 1.23 Can I disable plaintext passwords?
          + 1.24 Can I disable plaintext passwords on unencrypted
            sessions, but allow them on encrypted sessions?
          + 1.25 Can I use virtual hosts?
          + 1.26 Can I use RPOP authentication?
          + 1.27 Can I use Kerberos V4?
          + 1.28 Is there support for S/Key or OTP?
          + 1.29 Is there support for NTLM or SPA?
          + 1.30 Is there support for mh?
          + 1.31 Is there support for qmail and the maildir format?
          + 1.32 Is there support for the Cyrus mailbox format?
          + 1.33 Is this software Y2K compliant?
     * 2. What Do I Need to Build This Software?
          + 2.1 What do I need to build this software with SSL on UNIX?
          + 2.2 What do I need to build this software with Kerberos V on
            UNIX?
          + 2.3 What do I need to use a C++ compiler with this software
            to build my own application?
          + 2.4 What do I need to build this software on Windows?
          + 2.5 What do I need to build this software on DOS?
          + 2.6 Can't I use Borland C to build this software on the PC?
          + 2.7 What do I need to build this software on the Mac?
          + 2.8 What do I need to build this software on VMS?
          + 2.9 What do I need to build this software on TOPS-20?
          + 2.10 What do I need to build this software on Amiga or OS/2?
          + 2.11 What do I need to build this software on Windows CE?
     * 3. Build and Configuration Questions
          + 3.1 How do I configure the IMAP and POP servers on UNIX?
          + 3.2 I built and installed the servers according to the BUILD
            instructions. It can't be that easy. Don't I need to write a
            config file?
          + 3.3 How do I make the IMAP and POP servers look for INBOX at
            some place other than the mail spool directory?
          + 3.4 How do I make the IMAP server look for secondary folders
            at some place other than the user's home directory?
          + 3.5 How do I configure SSL?
          + 3.6 How do I configure TLS and the STARTTLS facility?
          + 3.7 How do I build/install OpenSSL and obtain/create
            certificates for use with SSL?
          + 3.8 How do I configure CRAM-MD5 authentication?
          + 3.9 How do I configure APOP authentication?
          + 3.10 How do I configure Kerberos V5?
          + 3.11 How do I configure PAM for plaintext passwords?
          + 3.12 It looks like all I have to do to make the server use
            Kerberos is to build with PAM on my Linux system, and set it
            up in PAM for Kerberos passwords. Right?
          + 3.13 How do I configure Kerberos 5 for plaintext passwords?
          + 3.14 How do I configure AFS for plaintext passwords?
          + 3.15 How do I configure DCE for plaintext passwords?
          + 3.16 How do I configure the CRAM-MD5 database for plaintext
            passwords?
          + 3.17 How do I disable plaintext passwords?
          + 3.18 How do I disable plaintext passwords on unencrypted
            sessions, but allow them in SSL or TLS sessions?
          + 3.19 How do I configure virtual hosts?
          + 3.20 Why do I get compiler warning messages such as:
               o passing arg 3 of `scandir' from incompatible pointer
                 type
               o Pointers are not assignment-compatible.
               o Argument #4 is not the correct type.
            during the build?
          + 3.21 Why do I get compiler warning messages such as
               o Operation between types &quot;void(*)(int)&quot; and &quot;void*&quot; is
                 not allowed.
               o Function argument assignment between types &quot;void*&quot; and
                 &quot;void(*)(int)&quot; is not allowed.
               o Pointers are not assignment-compatible.
               o Argument #5 is not the correct type.
            during the build?
          + 3.22 Why do I get linker warning messages such as:
               o mtest.c:515: the `gets' function is dangerous and should
                 not be used.
            during the build? Isn't this a security bug?
          + 3.23 Why do I get linker warning messages such as:
               o auth_ssl.c:92: the `tmpnam' function is dangerous and
                 should not be used.
            during the build? Isn't this a security bug?
          + 3.24 OK, suppose I see a warning message about a function
            being &quot;dangerous and should not be used&quot; for something other
            than this gets() or tmpnam() call?
     * 4. Operational Questions
          + 4.1 How can I enable anonymous IMAP logins?
          + 4.2 How do I set up an alert message that each IMAP user will
            see?
          + 4.3 How does the c-client library choose which of its several
            mechanisms to use to establish an IMAP connection to the
            server? I noticed that it can connect on port 143, port 993,
            via rsh, and via ssh.
          + 4.4 I am using a TLS-capable IMAP server, so I don't need to
            use /ssl to get encryption. However, I want to be certain
            that my session is TLS encrypted before I send my password.
            How to I do this?
          + 4.5 How do I use one of the alternative formats described in
            the formats.txt document? In particular, I hear that mbx
            format will give me better performance and allow shared
            access.
          + 4.6 How do I set up shared mailboxes?
          + 4.7 How can I make the server syslogs go to someplace other
            than the mail syslog?
     * 5. Security Questions
          + 5.1 I see that the IMAP server allows access to arbitary
            files on the system, including /etc/passwd! How do I disable
            this?
          + 5.2 I've heard that IMAP servers are insecure. Is this true?
          + 5.3 How do I know that I have the most secure version of the
            server?
          + 5.4 I see all these strcpy() and sprintf() calls, those are
            unsafe, aren't they?
          + 5.5 Those /tmp lock files are protected 666, is that really
            right?
     * 6. Why Did You Do This Strange Thing? Questions
          + 6.1 Why don't you use GNU autoconfig / automake /
            autoblurdybloop?
          + 6.2 Why do you insist upon a build with -g? Doesn't it waste
            disk and memory space?
          + 6.3 Why don't you make c-client a shared library?
          + 6.4 Why don't you use iconv() for internationalization
            support?
          + 6.5 Why is the IMAP server connected to the home directory by
            default?
          + 6.6 I have a Windows system. Why isn't the server plug and
            play for me?
          + 6.7 I looked at the UNIX SSL code and saw that you have the
            SSL data payload size set to 8192 bytes. SSL allows 16K; why
            aren't you using the full size?
          + 6.8 Why is an mh format INBOX called #mhinbox instead of just
            INBOX?
          + 6.9 Why don't you support the maildir format?
          + 6.10 Why don't you support the Cyrus format?
          + 6.11 Why is it creating extra forks on my SVR4 system?
          + 6.12 Why are you so fussy about the date/time format in the
            internal &quot;From &quot; line in traditional UNIX mailbox files? My
            other mail program just considers every line that starts with
            &quot;From &quot; to be the start of the message.
          + 6.13 Why is traditional UNIX format the default format?
          + 6.14 Why do you write this &quot;DON'T DELETE THIS MESSAGE --
            FOLDER INTERNAL DATA&quot; message at the start of traditional
            UNIX and MMDF format mailboxes?
          + 6.15 Why don't you stash the mailbox metadata in the first
            real message of the mailbox instead of writing this fake
            FOLDER INTERNAL DATA message?
          + 6.16 Why aren't &quot;dual-use&quot; mailboxes the default?
          + 6.17 Why do you use ucbcc to build on Solaris?
          + 6.18 Why should I care about some old system with BSD
            libraries? cc is the right thing on my Solaris system!
          + 6.19 Why do you insist upon writing .lock files in the spool
            directory?
          + 6.20 Why should I care about compatibility with the past?
     * 7. Problems and Annoyances
          + 7.1 Help! My INBOX is empty! What happened to my messages?
          + 7.2 Help! All my messages in a non-INBOX mailbox have been
            concatenated into one message which claims to be from me and
            has a subject of the file name of the mailbox! What's going
            on?
          + 7.3 Why do I get the message:
               o CREATE failed: Can't create mailbox node xxxxxxxxx: File
                 exists
            and how do I fix it?
          + 7.4 Why can't I log in to the server? The user name and
            password are right!
          + 7.5 Help! My load average is soaring and I see hundreds of
            POP and IMAP servers, many logged in as the same user!
          + 7.6 Why does mail disappear even though I set &quot;keep mail on
            server&quot;?
          + 7.7 Why do I get the message
               o Moved ##### bytes of new mail to /home/user/mbox from
                 /var/spool/mail/user
            and why did this happen?
          + 7.8 Why isn't it showing the local host name as a
            fully-qualified domain name?
          + 7.9 Why is the local host name in the From/Sender/Message-ID
            headers of outgoing mail not coming out as a fully-qualified
            domain name?
          + 7.10 What does the message:
               o Mailbox vulnerable - directory /var/spool/mail must have
                 1777 protection
            mean? How can I fix this?
          + 7.11 What does the message:
               o Mailbox is open by another process, access is readonly
            mean? How do I fix this?
          + 7.12 What does the message:
               o Can't get write access to mailbox, access is readonly
            mean?
          + 7.13 I set my POP3 client to &quot;delete messages from server&quot;
            but they never get deleted. What is wrong?
          + 7.14 What do messages such as:
               o Message ... UID ... already has UID ...
               o Message ... UID ... less than ...
               o Message ... UID ... greater than last ...
               o Invalid UID ... in message ..., rebuilding UIDs
            mean?
          + 7.15 What do the error messages:
               o Unable to read internal header at ...
               o Unable to find CRLF at ...
               o Unable to parse internal header at ...
               o Unable to parse message date at ...
               o Unable to parse message flags at ...
               o Unable to parse message UID at ...
               o Unable to parse message size at ...
               o Last message (at ... ) runs past end of file ...
            mean? I am using mbx format.
          + 7.16 What do the syslog messages:
               o imap/tcp server failing (looping)
               o pop3/tcp server failing (looping)
            mean? When it happens, the listed service shuts down. How can
            I fix this?
          + 7.17 What does the syslog message:
               o Mailbox lock file /tmp/.600.1df3 open failure:
                 Permission denied
            mean?
          + 7.18 What do the syslog messages:
               o Command stream end of file, while reading line user=...
                 host=...
               o Command stream end of file, while reading char user=...
                 host=...
               o Command stream end of file, while writing text user=...
                 host=...
            mean?
          + 7.19 Why did my POP or IMAP session suddenly disconnect? The
            syslog has the message:
               o Killed (lost mailbox lock) user=... host=...
          + 7.20 Why does my IMAP client show all the files on the
            system, recursively from the UNIX root directory?
          + 7.21 Why does my IMAP client show all of my files,
            recursively from my UNIX home directory?
          + 7.22 Why does my IMAP client show that I have mailboxes named
            &quot;#mhinbox&quot;, &quot;#mh&quot;, &quot;#shared&quot;, &quot;#ftp&quot;, &quot;#news&quot;, and &quot;#public&quot;?
          + 7.23 Why does my IMAP client show all my files in my home
            directory?
          + 7.24 Why is there a long delay before I get connected to the
            IMAP or POP server, no matter what client I use?
          + 7.25 Why is there a long delay in Pine or any other c-client
            based application call before I get connected to the IMAP
            server? The hang seems to be in the c-client mail_open()
            call. I don't have this problem with any other IMAP client.
            There is no delay connecting to a POP3 or NNTP server with
            mail_open().
          + 7.26 Why does a message sometimes get split into two or more
            messages on my SUN system?
          + 7.27 Why did my POP or IMAP session suddenly disconnect? The
            syslog has the message:
               o Autologout user=&lt;...my user name...&gt; host=&lt;...my imap
                 server...&gt;
          + 7.28 What does the UNIX error message:
               o TLS/SSL failure: myserver: SSL negotiation failed
            mean?
          + 7.29 What does the PC error message:
               o TLS/SSL failure: myserver: Unexpected TCP input
                 disconnect
            mean?
          + 7.30 What does the error message:
               o TLS/SSL failure: myserver: Server name does not match
                 certificate
            mean?
          + 7.31 What does the UNIX error message:
               o TLS/SSL failure: myserver: self-signed certificate
            mean?
          + 7.32 What does the PC error message
               o TLS/SSL failure: myserver: Self-signed certificate or
                 untrusted authority
            mean?
          + 7.33 What does the UNIX error message:
               o TLS/SSL failure: myserver: unable to get local issuer
                 certificate
            mean?
          + 7.34 Why does reading certain messages hang when using
            Netscape? It works fine with Pine!
          + 7.35 Why does Netscape say that there's a problem with the
            IMAP server and that I should &quot;Contact your mail server
            administrator.&quot;?
          + 7.36 Why is one user creating huge numbers of IMAP or POP
            server sessions?
          + 7.37 Why don't I get any new mail notifications from Outlook
            Express or Outlook after a while?
          + 7.38 Why don't I get any new mail notifications from
            Entourage?
          + 7.39 Why doesn't Entourage work at all?
          + 7.40 Why doesn't Netscape Notify (NSNOTIFY.EXE) work at all?
          + 7.41 Why can't I connect via SSL to Eudora? It says the
            connection has been broken, and in the server syslogs I see
            &quot;Command stream end of file&quot;.
          + 7.42 Sheesh. Aren't there any good IMAP clients out there?
          + 7.43 But wait! PC Pine (or other PC program build with
            c-client) crashes with the message
               o incomplete SecBuffer exceeds maximum buffer size
            when I use SSL connections. This is a bug in c-client, right?
          + 7.44 My qpopper users keep on getting the DON'T DELETE THIS
            MESSAGE -- FOLDER INTERNAL DATA if they also use Pine or
            IMAP. How can I fix this?
          + 7.45 Help! I installed the servers but I can't connect to
            them from my client!
          + 7.46 Why do I get the message
               o Can not authenticate to SMTP server: 421 SMTP connection
                 went away!
            and why did this happen? There was also something about
               o SECURITY PROBLEM: insecure server advertised AUTH=PLAIN
          + 7.47 Why do I get the message
               o SMTP Authentication cancelled
            and why did this happen? There was also something about
               o SECURITY PROBLEM: insecure server advertised AUTH=PLAIN
          + 7.48 Why do I get the message
               o Invalid base64 string
            when I try to authenticate to a Cyrus server?
     * 8. Where to Go For Additional Information
          + 8.1 Where can I go to ask questions?
          + 8.2 I have some ideas for enhancements to IMAP. Where should
            I go?
          + 8.3 Where can I read more about IMAP and other email
            protocols?
          + 8.4 Where can I find out more about setting up and
            administering an IMAP server?
     _________________________________________________________________

1. General/Software Feature Questions
     _________________________________________________________________

   1.1 Can I set up a POP or IMAP server on UNIX/Linux/OSF/etc.?

          Yes. Refer to the UNIX specific notes in files CONFIG and
          BUILD.
     _________________________________________________________________

   1.2 I am currently using qpopper as my POP3 server on UNIX. Do I need
   to replace it with ipop3d in order to run imapd?

          Not necessarily.

          Although ipop3d interoperates with imapd better than qpopper,
          imapd and qpopper will work together. The few qpopper/imapd
          interoperability issues mostly affect users who use both IMAP
          and POP3 clients; those users would probably be better served
          if their POP3 server is ipop3d.

          If you are happy with qpopper and just want to add imapd, you
          should do that, and defer a decision on changing qpopper to
          ipop3d. That way, you can get comfortable with imapd's
          performance, without changing anything for your qpopper users.

          Many sites have subsequently decided to change from qpopper to
          ipop3d in order to get better POP3/IMAP interoperability. If
          you need to do this, you'll know. There also seems to be a way
          to make qpopper work better with imapd; see the answer to the
          My qpopper users keep on getting the DON'T DELETE THIS MESSAGE
          -- FOLDER INTERNAL DATA if they also use Pine or IMAP. How can
          I fix this? question.
     _________________________________________________________________

   1.3 Can I set up a POP or IMAP server on Windows XP, 2000, NT, Me, 98,
   or 95?

          Yes. Refer to the NT specific notes in files CONFIG and BUILD.
          Also, for DOS-based versions of Windows (Windows Me, 98, and
          95) you *must* set up CRAM-MD5 authentication, as described in
          md5.txt.

          There is no file access control on Windows 9x or Me, so you
          probably will have to do modifications to env_unix.c to prevent
          people from hacking others' mail.

          Note, however, that the server is not plug and play the way it
          is for UNIX.
     _________________________________________________________________

   1.4 Can I set up a POP or IMAP server on Windows 3.1 or DOS?
   1.5 Can I set up a POP or IMAP server on Macintosh?
   1.6 Can I set up a POP or IMAP server on VAX/VMS?

          Yes, it's just a small matter of programming.
     _________________________________________________________________

   1.7 Can I set up a POP or IMAP server on TOPS-20?

          You have a TOPS-20 system? Cool.

          If IMAP2 (RFC 1176) is good enough for you, you can use MAPSER
          which is about the ultimate gonzo pure TOPS-20 extended
          addressing assembly language program. Unfortunately, IMAP2 is
          barely good enough for Pine these days, and most other IMAP
          clients won't work with IMAP2 at all. Maybe someone will hack
          MAPSER to do IMAP4rev1 some day.

          We don't know if anyone wrote a POP3 server for TOPS-20. There
          definitely was a POP2 server once upon a time.

          Or you can port the POP and IMAP server from this IMAP toolkit
          to it. All that you need for a first stab is to port the MTX
          driver. That'll probably be just a couple of hours of hacking.
     _________________________________________________________________

   1.8 Are hierarchical mailboxes supported?
   1.9 Are &quot;dual-use&quot; mailboxes supported?
   1.10 Can I have a mailbox that has both messages and sub-mailboxes?

          Yes. However, there is one important caveat.

          Some mailbox formats, including the default which is the
          traditional UNIX mailbox format, are stored as a single file
          containing all the messages. UNIX does not permit a name in the
          filesystem to be both a file and a directory; consequently you
          can not have a sub-mailbox within a mailbox that is in one of
          these formats.

          This is not a limitation of the software; this is a limitation
          of UNIX. For example, there are mailbox formats in which the
          name is a directory and each message is a file within that
          directory; these formats support sub-mailboxes within such
          mailboxes. However, for technical reasons, the &quot;flat file&quot;
          formats are generally preferred since they perform better. Read
          imap-2007/docs/formats.txt for more information on this topic.

          It is always permissible to create a directory that is not a
          mailbox, and have sub-mailboxes under it. The easiest way to
          create a directory is to create a new mailbox inside a
          directory that doesn't already exist. For example, if you
          create &quot;Mail/testbox&quot; on UNIX, the directory &quot;Mail/&quot; will
          automatically be created and then the mailbox &quot;testbox&quot; will be
          created as a sub-mailbox of &quot;Mail/&quot;.

          It is also possible to create the name &quot;Mail/&quot; directly. Check
          the documentation for your client software to see how to do
          this with that software.

          Of course, on Windows systems you would use &quot;\&quot; instead of &quot;/&quot;.
     _________________________________________________________________

   1.11 What is the difference between &quot;mailbox&quot; and &quot;folder&quot;?

          The term &quot;mailbox&quot; is IMAP-speak for what a lot of software
          calls a &quot;folder&quot; or a &quot;mail folder&quot;. However, &quot;folder&quot; is often
          used in other contexts to refer to a directory, for example, in
          the graphic user interface on both Windows and Macintosh.

          A &quot;mailbox&quot; is specifically defined as a named object that
          contains messages. It is not required to be capable of
          containing other types of objects including other mailboxes;
          although some mailbox formats will permit this.

          In IMAP-speak, a mailbox which can not contain other mailboxes
          is called a &quot;no-inferiors mailbox&quot;. Similarly, a directory
          which can not contain messages is not a mailbox and is called a
          &quot;no-select name&quot;.
     _________________________________________________________________

   1.12 What is the status of internationalization?

          The IMAP toolkit is partially internationalized and
          multilingualized.

          Searching is supported in the following charsets: US-ASCII,
          UTF-8, ISO-8859-1, ISO-8859-2, ISO-8859-3, ISO-8859-4,
          ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8, ISO-8859-9,
          ISO-8859-10, ISO-8859-11, ISO-8859-13, ISO-8859-14,
          ISO-8859-15, ISO-8859-16, KOI8-R, KOI8-U (alias KOI8-RU),
          TIS-620, VISCII, ISO-2022-JP, ISO-2022-KR, ISO-2022-CN,
          ISO-2022-JP-1, ISO-2022-JP-2, GB2312 (alias CN-GB),
          CN-GB-12345, BIG5 (alias CN-BIG5), EUC-JP, EUC-KR, Shift_JIS,
          Shift-JIS, KS_C_5601-1987, KS_C_5601-1992, WINDOWS_874,
          WINDOWS-1250, WINDOWS-1251, WINDOWS-1252, WINDOWS-1253,
          WINDOWS-1254, WINDOWS-1255, WINDOWS-1256, WINDOWS-1257,
          WINDOWS-1258.

          All ISO-2022-?? charsets are treated identically, and support
          ASCII, JIS Roman, hankaku katakana, ISO-8859-[1 - 10], TIS, GB
          2312, JIS X 0208, JIS X 0212, KSC 5601, and planes 1 and 2 of
          CNS 11643.

          EUC-JP includes support for JIS X 0212 and hankaku katakana.

          c-client library support also exists to convert text in any of
          the above charsets into Unicode, including headers with MIME
          encoded-words.

          There is no support for localization (e.g. non-English error
          messages) at the present time, but such support is planned.
     _________________________________________________________________

   1.13 Can I use SSL?

          Yes. See the answer to the How do I configure SSL? question.
     _________________________________________________________________

   1.14 Can I use TLS and the STARTTLS facility?

          Yes. See the answer to the How do I configure TLS and the
          STARTTLS facility? question.
     _________________________________________________________________

   1.15 Can I use CRAM-MD5 authentication?

          Yes. See the answer to the How do I configure CRAM-MD5
          authentication? question.
     _________________________________________________________________

   1.16 Can I use APOP authentication?

          Yes. See the How do I configure APOP authentication? question.

          Note that there is no client support for APOP authentication.
     _________________________________________________________________

   1.17 Can I use Kerberos V5?

          Yes. See the answer to the How do I configure Kerberos V5?
          question.
     _________________________________________________________________

   1.18 Can I use PAM for plaintext passwords?

          Yes. See the answer to the How do I configure PAM for plaintext
          passwords? question.
     _________________________________________________________________

   1.19 Can I use Kerberos 5 for plaintext passwords?

          Yes. See the answer to the How do I configure Kerberos 5 for
          plaintext passwords? question.
     _________________________________________________________________

   1.20 Can I use AFS for plaintext passwords?

          Yes. See the answer to the How do I configure AFS for plaintext
          passwords? question.
     _________________________________________________________________

   1.21 Can I use DCE for plaintext passwords?

          Yes. See the answer to the How do I configure DCE for plaintext
          passwords? question.
     _________________________________________________________________

   1.22 Can I use the CRAM-MD5 database for plaintext passwords?

          Yes. See the answer to the How do I configure the CRAM-MD5
          database for plaintext passwords? question.
     _________________________________________________________________

   1.23 Can I disable plaintext passwords?

          Yes. See the answer to the How do I disable plaintext
          passwords? question.
     _________________________________________________________________

   1.24 Can I disable plaintext passwords on unencrypted sessions, but
   allow them on encrypted sessions?

          Yes. See the answer to the How do I disable plaintext passwords
          on unencrypted sessions, but allow them in SSL or TLS sessions?
          question.
     _________________________________________________________________

   1.25 Can I use virtual hosts?

          Yes. See the answer to the How do I configure virtual hosts?
          question.
     _________________________________________________________________

   1.26 Can I use RPOP authentication?

          There is no support for RPOP authentication.
     _________________________________________________________________

   1.27 Can I use Kerberos V4?

          Kerberos V4 is not supported. Kerberos V4 client-only
          contributed code is available in

ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z

          This is a patchkit which must be applied to the IMAP toolkit
          according to the instructions in the patchkit's README. We can
          not promise that this code works.
     _________________________________________________________________

   1.28 Is there support for S/Key or OTP?

          There is currently no support for S/Key or OTP. There may be an
          OTP SASL authenticator available from third parties.
     _________________________________________________________________

   1.29 Is there support for NTLM or SPA?

          There is currently no support for NTLM or SPA, nor are there
          any plans to add such support. In general, I avoid
          vendor-specific mechanisms. I also believe that these
          mechanisms are being deprecated by their vendor.

          There may be an NTLM SASL authenticator available from third
          parties.
     _________________________________________________________________

   1.30 Is there support for mh?

          Yes, but only as a legacy format. Your mh format INBOX is
          accessed by the name &quot;#mhinbox&quot;, and all other mh format
          mailboxes are accessed by prefixing &quot;#mh/&quot; to the name, e.g.
          &quot;#mh/foo&quot;. The mh support uses the &quot;Path:&quot; entry in your
          .mh_profile file to identify the root directory of your mh
          format mailboxes.

          Non-legacy use of mh format is not encouraged. There is no
          support for permanent flags or unique identifiers; furthermore
          there are known severe performance problems with the mh format.
     _________________________________________________________________

   1.31 Is there support for qmail and the maildir format?

          There is no support for qmail or the maildir format in our
          distribution, nor are there any plans to add such support.
          Maildir support may be available from third parties.
     _________________________________________________________________

   1.32 Is there support for the Cyrus mailbox format?

          No.
     _________________________________________________________________

   1.33 Is this software Y2K compliant?

          Please read the files Y2K and calendar.txt.
     _________________________________________________________________

2. What Do I Need to Build This Software?
     _________________________________________________________________

   2.1 What do I need to build this software with SSL on UNIX?

          You need to build and install OpenSSL first.
     _________________________________________________________________

   2.2 What do I need to build this software with Kerberos V on UNIX?

          You need to build and install MIT Kerberos first.
     _________________________________________________________________

   2.3 What do I need to use a C++ compiler with this software to build
   my own application?

          If you are building an application using the c-client library,
          use the new c-client.h file instead of including the other
          include files. It seems that c-client.h should define away all
          the troublesome names that conflict with C++.

          If you use gcc, you may need to use -fno-operator-names as
          well.
     _________________________________________________________________

   2.4 What do I need to build this software on Windows?

          You need Microsoft Visual C++ 6.0, Visual C++ .NET, or Visual
          C# .NET (which you can buy from any computer store), along with
          the Microsoft Platform SDK (which you can download from
          Microsoft's web site).

          You do not need to install the entire Platform SDK; it suffices
          to install just the Core SDK and the Internet Development SDK.
     _________________________________________________________________

   2.5 What do I need to build this software on DOS?

          It's been several years since we last attempted to do this. At
          the time, we used Microsoft C.
     _________________________________________________________________

   2.6 Can't I use Borland C to build this software on the PC?

          Probably not. If you know otherwise, please let us know.
     _________________________________________________________________

   2.7 What do I need to build this software on the Mac?

          It has been several years since we last attempted to do this.
          At the time, we used Symantec THINK C; but today you'll need a
          C compiler which allows segments to be more than 32K.
     _________________________________________________________________

   2.8 What do I need to build this software on VMS?

          You need the VMS C compiler, and either the Multinet or Netlib
          TCP.
     _________________________________________________________________

   2.9 What do I need to build this software on TOPS-20?

          You need the TOPS-20 KCC compiler.
     _________________________________________________________________

   2.10 What do I need to build this software on Amiga or OS/2?

          We don't know.
     _________________________________________________________________

   2.11 What do I need to build this software on Windows CE?

          This port is incomplete. Someone needs to finish it.
     _________________________________________________________________

3. Build and Configuration Questions
     _________________________________________________________________

   3.1 How do I configure the IMAP and POP servers on UNIX?
   3.2 I built and installed the servers according to the BUILD
   instructions. It can't be that easy. Don't I need to write a config
   file?

          For ordinary &quot;vanilla&quot; UNIX systems, this software is plug and
          play; just build it, install it, and you're done. If you have a
          modified system, then you may want to do additional work; most
          of this is to a single source code file (env_unix.c on UNIX
          systems). Read the file CONFIG for more details.

          Yes, it's that easy. There are some additional options, such as
          SSL or Kerberos, which require additional steps to build. See
          the relevant questions below.
     _________________________________________________________________

   3.3 How do I make the IMAP and POP servers look for INBOX at some
   place other than the mail spool directory?
   3.4 How do I make the IMAP server look for secondary folders at some
   place other than the user's home directory?

          Please read the file CONFIG for discussion of this and other
          issues.
     _________________________________________________________________

   3.5 How do I configure SSL?
   3.6 How do I configure TLS and the STARTTLS facility?

          imap-2007 supports SSL and TLS client functionality on UNIX and
          32-bit Windows for IMAP, POP3, SMTP, and NNTP; and SSL and TLS
          server functionality on UNIX for IMAP and POP3.

          UNIX SSL build requires that a third-party software package,
          OpenSSL, be installed on the system first. Read
          imap-2007/docs/SSLBUILD for more information.

          SSL is supported via undocumented Microsoft interfaces in
          Windows 9x and NT4; and via standard interfaces in Windows
          2000, Windows Millenium, and Windows XP.
     _________________________________________________________________

   3.7 How do I build/install OpenSSL and obtain/create certificates for
   use with SSL?

          If you need help in doing this, try the contacts mentioned in
          the OpenSSL README. We do not offer support for OpenSSL or
          certificates.
     _________________________________________________________________

   3.8 How do I configure CRAM-MD5 authentication?
   3.9 How do I configure APOP authentication?

          CRAM-MD5 authentication is enabled in the IMAP and POP3 client
          code on all platforms. Read md5.txt to learn how to set up
          CRAM-MD5 and APOP authentication on UNIX and NT servers.

          There is no support for APOP client authentication.
     _________________________________________________________________

   3.10 How do I configure Kerberos V5?

          imap-2007 supports client and server functionality on UNIX and
          32-bit Windows.

          Kerberos V5 is supported by default in Windows 2000 builds:

 nmake -f makefile.w2k

          Other builds require that a third-party Kerberos package, e.g.
          MIT Kerberos, be installed on the system first.

          To build with Kerberos V5 on UNIX, include
          EXTRAAUTHENTICATORS=gss in the make command line, e.g.

 make lnp EXTRAAUTHENTICATORS=gss

          To build with Kerberos V5 on Windows 9x, Windows Millenium, and
          NT4, use the &quot;makefile.ntk&quot; file instead of &quot;makefile.nt&quot;:


 nmake -f makefile.ntk
     _________________________________________________________________

   3.11 How do I configure PAM for plaintext passwords?

          On Linux systems, use the lnp port, e.g.

 make lnp

          On Solaris systems and other systems with defective PAM
          implementations, build with PASSWDTYPE=pmb, e.g.

 make sol PASSWDTYPE=pmb

          On all other systems, build with PASSWDTYPE=pam, e.g

 make foo PASSWDTYPE=pam

          If you build with PASSWDTYPE=pam and authentication does not
          work, try rebuilding (after a &quot;make clean&quot;) with
          PASSWDTYPE=pmb.
     _________________________________________________________________

   3.12 It looks like all I have to do to make the server use Kerberos is
   to build with PAM on my Linux system, and set it up in PAM for
   Kerberos passwords. Right?

          Yes and no.

          Doing this will make plaintext password authentication use the
          Kerberos password instead of the /etc/passwd password.

          However, this will NOT give you Kerberos-secure authentication.
          See the answer to the How do I configure Kerberos V5? question
          for how to build with Kerberos-secure authentication.
     _________________________________________________________________

   3.13 How do I configure Kerberos 5 for plaintext passwords?

          Build with PASSWDTYPE=gss, e.g.

 make sol PASSWDTYPE=gss

          However, this will NOT give you Kerberos-secure authentication.
          See the answer to the How do I configure Kerberos V5? question
          for how to build with Kerberos-secure authentication.
     _________________________________________________________________

   3.14 How do I configure AFS for plaintext passwords?

          Build with PASSWDTYPE=afs, e.g

 make sol PASSWDTYPE=afs
     _________________________________________________________________

   3.15 How do I configure DCE for plaintext passwords?

          Build with PASSWDTYPE=dce, e.g

 make sol PASSWDTYPE=dce
     _________________________________________________________________

   3.16 How do I configure the CRAM-MD5 database for plaintext passwords?

          The CRAM-MD5 password database is automatically used for
          plaintext password if it exists.

          Note that this is NOT CRAM-MD5-secure authentication. You
          probably want to consider disabling plaintext passwords for
          non-SSL/TLS sessions. See the next two questions.
     _________________________________________________________________

   3.17 How do I disable plaintext passwords?

          Server-level plaintext passwords can be disabled by setting
          PASSWDTYPE=nul, e.g.

 make lnx EXTRAAUTHENTICATORS=gss PASSWDTYPE=nul

          Note that you must have a CRAM-MD5 database installed or
          specify at least one EXTRAAUTHENTICATOR, otherwise it will not
          be possible to log in to the server.

          When plaintext passwords are disabled, the IMAP server will
          advertise the LOGINDISABLED capability and the POP3 server will
          not advertise the USER capability.

   3.18 How do I disable plaintext passwords on unencrypted sessions, but
   allow them in SSL or TLS sessions?

          Do not set PASSWDTYPE=nul or SSLTYPE=unix. Set SSLTYPE=nopwd
          instead, e.g.

 make lnx SSLTYPE=nopwd

          When plaintext passwords are disabled, the IMAP server will
          advertise the LOGINDISABLED capability and the POP3 server will
          not advertise the USER capability.

          Plaintext passwords will always be enabled in SSL sessions; the
          IMAP server will not advertise the LOGINDISABLED capability and
          the POP3 server will advertise the USER capability.

          If the client does a successful start-TLS in a non-SSL session,
          plaintext passwords will be enabled, and a new CAPABILITY or
          CAPA command (which is required after start-TLS) will show the
          effect as in SSL sessions.
     _________________________________________________________________

   3.19 How do I configure virtual hosts?

          This is automatic, but with certain restrictions.

          The most important one is that each virtual host must have its
          own IP address; otherwise the server has no way of knowing
          which virtual host is desired.

          As distributed, the software uses a global password file; hence
          user &quot;fred&quot; on one virtual host is &quot;fred&quot; on all virtual hosts.
          You may want to modify the checkpw() routine to implement some
          other policy (e.g. separate password files).

          Note that the security model assumes that all users have their
          own unique UNIX UID number. So if you use separate password
          files you should make certain that the UID numbers do not
          overlap between different files.

          More advanced virtual host support may be available as patches
          from third parties.
     _________________________________________________________________

   3.20 Why do I get compiler warning messages such as:
 passing arg 3 of `scandir' from incompatible pointer type
 Pointers are not assignment-compatible.
 Argument #4 is not the correct type.

   during the build?

          You can safely ignore these messages.

          Over the years, the prototype for scandir() has changed, and
          thus is variant across different UNIX platforms. In particular,
          the definitions of the third argument (type select_t) and
          fourth argument (type compar_t) have changed over the years,
          the issue being whether or not the arguments to the functions
          pointed to by these function pointers are of type const or not.

          The way that c-client calls scandir() will tend to generate
          these compiler warnings on newer systems such as Linux;
          however, it will still build. The problem with fixing the call
          is that then it won't build on older systems.
     _________________________________________________________________

   3.21 Why do I get compiler warning messages such as
 Operation between types &quot;void(*)(int)&quot; and &quot;void*&quot; is not allowed.
 Function argument assignment between types &quot;void*&quot; and &quot;void(*)(int)&quot; is not a
llowed.
 Pointers are not assignment-compatible.
 Argument #5 is not the correct type.

   during the build?

          You can safely ignore these messages.

          All known systems have no problem with casting a function
          pointer to/from a void* pointer, certain C compilers issue a
          compiler diagnostic because this facility is listed as a
          &quot;Common extension&quot; by the C standard:

 K.5.7  Function pointer casts
  [#1] A pointer to an object or to void may be cast to a pointer
       to a function, allowing data to be invoked as a function (6.3.4).
  [#2] A pointer to a function may be cast to a pointer to an
       object or to void, allowing a function to be inspected or
       modified (for example, by a debugger) (6.3.4).

          It may be just a &quot;common extension&quot;, but this facility is
          relied upon heavily by c-client.
     _________________________________________________________________

   3.22 Why do I get linker warning messages such as:
mtest.c:515: the `gets' function is dangerous and should not be used.

   during the build? Isn't this a security bug?

          You can safely ignore this message.

          Certain linkers, most notably on Linux, give this warning
          message. It is indeed true that the traditional gets() function
          is not a safe one.

          However, the mtest program is only a demonstration program, a
          model of a very basic application program using c-client. It is
          not something that you would install, much less run in any
          security-sensitive context.

          mtest has numerous other shortcuts that you wouldn't want to do
          in a real application program.

          The only &quot;security bug&quot; with mtest would be if it was run by
          some script in a security-sensitive context, but mtest isn't
          particularly useful for such purposes. If you wanted to write a
          script to automate some email task using c-client, you'd be
          better off using imapd instead of mtest.

          mtest only has two legitimate uses. It's a useful testbed for
          me when debugging new versions of c-client, and it's useful as
          a model for someone writing a simple c-client application to
          see how the various calls work.

          By the way, if you need a more advanced example of c-client
          programming than mtest (and you probably will), I recommend
          that you look at the source code for imapd and Pine.
     _________________________________________________________________

   3.23 Why do I get linker warning messages such as:
 auth_ssl.c:92: the `tmpnam' function is dangerous and should not be used.

   during the build? Isn't this a security bug?

          You can safely ignore this message.

          Certain linkers, most notably on Linux, give this warning
          message, based upon two known issues with tmpnam():

                there can be a buffer overflow if an inadequate buffer is
                allocated.
                there can be a timing race caused by certain incautious
                usage of the return value.

          Neither of these issues applies in the particular use that is
          made of tmpnam(). More importantly, the tmpnam() call is never
          executed on Linux systems.
     _________________________________________________________________

   3.24 OK, suppose I see a warning message about a function being
   &quot;dangerous and should not be used&quot; for something other than this
   gets() or tmpnam() call?

          Please forward the details for investigation.
     _________________________________________________________________

4. Operational Questions
     _________________________________________________________________

   4.1 How can I enable anonymous IMAP logins?

          Create the file /etc/anonymous.newsgroups. At the present time,
          this file should be empty. This will permit IMAP logins as
          anonymous as well as the ANONYMOUS SASL authenticator.
          Anonymous users have access to mailboxes in the #news., #ftp/,
          and #public/ namespaces only.
     _________________________________________________________________

   4.2 How do I set up an alert message that each IMAP user will see?

          Create the file /etc/imapd.alert with the text of the message.
          This text should be kept to one line if possible. Note that
          this will cause an alert to every IMAP user every time they
          initiate an IMAP session, so it should only be used for
          critical messages.
     _________________________________________________________________

   4.3 How does the c-client library choose which of its several
   mechanisms to use to establish an IMAP connection to the server? I
   noticed that it can connect on port 143, port 993, via rsh, and via
   ssh.

          c-client chooses how to establish an IMAP connection via the
          following rules:

          + If /ssl is specified, use an SSL connection. Fail otherwise.
          + Else if client is a UNIX system and &quot;ssh server exec
            /etc/rimapd&quot; works, use that
          + Else if /tryssl is specified and an SSL connection works, use
            that.
          + Else if client is a UNIX system and &quot;rsh server exec
            /etc/rimapd&quot; works, use that.
          + Else use a non-SSL connection.
     _________________________________________________________________

   4.4 I am using a TLS-capable IMAP server, so I don't need to use /ssl
   to get encryption. However, I want to be certain that my session is
   TLS encrypted before I send my password. How to I do this?

          Use the /tls option in the mailbox name. This will cause an
          error message and the connection to fail if the server does not
          negotiate STARTTLS.
     _________________________________________________________________

   4.5 How do I use one of the alternative formats described in the
   formats.txt document? In particular, I hear that mbx format will give
   me better performance and allow shared access.

          The rumors about mbx format being preferred are true. It is
          faster than the traditional UNIX mailbox format and permits
          shared access.

          However, and this is very important, note that using an
          alternative mailbox format is an advanced facility, and only
          expert users should undertake it. If you don't understand any
          of the following notes, you may not be enough of an expert yet,
          and are probably better off not going this route until you are
          more comfortable with your understanding.

          Some of the formats, including mbx, are only supported by the
          software based on the c-client library, and are not recognized
          by other mailbox programs. The &quot;vi&quot; editor will corrupt any mbx
          format mailbox that it encounters.

          Another problem is that the certain formats, including mbx, use
          advanced file access and locking techniques that do not work
          reliably with NFS. NFS is not a real filesystem. Use IMAP
          instead of NFS for distributed access.

          Each of the following steps are in escalating order of
          involvement. The further you go down this list, the more deeply
          committed you become:

          + The simplest way to create a mbx-format mailbox is to prefix
            the name with &quot;#driver.mbx/&quot; when creating a mailbox through
            c-client. For example, if you create &quot;#driver.mbx/foo&quot;, the
            mailbox &quot;foo&quot; will be created in mbx format. Only use
            &quot;#driver.mbx/&quot; when creating the mailbox. At all other times,
            just use the name (&quot;foo&quot; in this example); the software will
            automatically select the driver for mbx whenever that mailbox
            is accessed without you doing anything else.
          + You can use the &quot;mailutil copy&quot; command to copy an existing
            mailbox to a new mailbox in mbx format. Read the man page
            provided with the mailutil program for details.
          + If you create an mbx-format INBOX, by creating
            &quot;#driver.mbx/INBOX&quot; (note that &quot;INBOX&quot; must be all
            uppercase), then subsequent access to INBOX by any c-client
            based application will use the mbx-format INBOX. Any mail
            delivered to the traditional format mailbox in the spool
            directory (e.g. /var/spool/mail/$USER) will automatically be
            copied into the mbx-format INBOX and the spool directory copy
            removed.
          + You can cause any newly-created mailboxes to be in mbx-format
            by default by changing the definition of
            CREATEPROTO=unixproto to be CREATEPROTO=mbxproto in
            src/osdep/unix/Makefile, then rebuilding the IMAP toolkit (do
            a &quot;make clean&quot; first). Do not change EMPTYPROTO, since mbx
            format mailboxes are never a zero-byte file. If you use Pine
            or the imap-utils, you should probably also rebuild them with
            the new IMAP toolkit too.
          + You can deliver directly to the mbx-format INBOX by use of
            the tmail or dmail programs. tmail is for direct invocation
            from sendmail (or whatever MTA program you use); dmail is for
            calls from procmail. Both of these programs have man pages
            which must be read carefully before making this change.

          Most other servers (e.g. Cyrus) require use of a non-standard
          format. A full-fledged format conversion is not significantly
          different from what you have to do with other servers. The
          difference, which makes format conversion procedures somewhat
          more complicated with this server, is that there is no &quot;all or
          nothing&quot; requirement with this server. There are many points in
          between. A format conversion can be anything from a single
          mailbox or single user, to systemwide.

          This is good in that you can decide how far to go, or do the
          steps incrementally as you become more comfortable with the
          result. On the other hand, there's no &quot;One True Way&quot; which can
          be boiled down to a simple set of pedagogical instructions.

          A number of sites have done full-fledged format conversions,
          and are reportedly quite happy with the results. Feel free to
          ask in the comp.mail.imap newsgroup or the imap-uw mailing
          list for advice or help.
     _________________________________________________________________

   4.6 How do I set up shared mailboxes?

          At the simplest level, a shared mailbox is one which has UNIX
          file and directory protections which permit multiple users to
          access it. What this means is that your existing skills and
          tools to create and manage shared files on your UNIX system
          apply to shared mailboxes; e.g.

 chmod 666 mailbox

          You may want to consider the use of a mailbox format which
          permits multiple simultaneous read/write sessions, such as the
          mbx format. The traditional UNIX format only allows one
          read/write session to a mailbox at a time.

          An additional convenience item are three system directories,
          which can be set up for shared namespaces. These are: #ftp,
          #shared, and #public, and are defined by creating the
          associated UNIX users and home directories as described below.

          #ftp/ refers to the anonymous ftp filesystem exported by the
          ftp server, and is equivalent to the home directory for UNIX
          user &quot;ftp&quot;. For example, #ftp/foo/bar refers to the file
          /foo/bar in the anonymous FTP filesystem, or ~ftp/foo/bar for
          normal users. Anonymous FTP files are available to anonymous
          IMAP logins. By default, newly-created files in #ftp/ are
          protected 644.

          #public/ refers to an IMAP toolkit convention called &quot;public&quot;
          files, and is equivalent to the home directory for UNIX user
          &quot;imappublic&quot;. For example, #public/foo/bar refers to the file
          ~imappublic/foo/bar. Public files are available to anonymous
          IMAP logins. By default, newly-created files in #public are
          created with protection 0666.

          #shared/ refers to an IMAP toolkit convention called &quot;shared&quot;
          files, and is equivalent to the home directory for UNIX user
          &quot;imapshared&quot;. For example, #shared/foo/bar refers to the file
          ~imapshared/foo/bar. Shared files are not available to
          anonymous IMAP logins. By default, newly-created files in
          #shared are created with protection 0660.
     _________________________________________________________________

   4.7 How can I make the server syslogs go to someplace other than the
   mail syslog?

          The openlog() call that sets the syslog facility is in
          src/osdep/unix/env_unix.c in routine server_init(). You need to
          edit this file to change the syslog facility from LOG_MAIL to
          the facility you want, then rebuild. You also need to set up
          your /etc/syslog.conf properly.

          Refer to the man pages for syslog and syslogd for more
          information on what the available syslog facilities are and how
          to configure syslogs. If you still don't understand what to do,
          find a UNIX system expert.
     _________________________________________________________________

5. Security Questions
     _________________________________________________________________

   5.1 I see that the IMAP server allows access to arbitary files on the
   system, including /etc/passwd! How do I disable this?

          You should not worry about this if your IMAP users are allowed
          shell access. The IMAP server does not permit any access that
          the user can not have via the shell.

          If, and only if, you deny your IMAP users shell access, you may
          want to consider one of three choices. Note that these choices
          reduce IMAP functionality, and may have undesirable side
          effects. Each of these choices involves an edit to file
          src/osdep/unix/env_unix.c

          The first (and recommended) choice is to set restrictBox as
          described in file CONFIG. This will disable access to the
          filesystem root, to other users' home directory, and to
          superior directory.

          The second (and strongly NOT recommended) choice is to set
          closedBox as described in file CONFIG. This puts each IMAP
          session into a so-called &quot;chroot jail&quot;, and thus setting this
          option is extremely dangerous; it can make your system much
          less secure and open to root compromise attacks. So do not use
          this option unless you are absolutely certain that you
          understand all the issues of a &quot;chroot jail.&quot;

          The third choice is to rewrite routine mailboxfile() to
          implement whatever mapping from mailbox name to filesystem name
          (and restrictions) that you wish. This is the most general
          choice. As a guide, you can see at the start of routine
          mailboxfile() what the restrictBox choice does.
     _________________________________________________________________

   5.2 I've heard that IMAP servers are insecure. Is this true?

          There are no known security problems in this version of the
          IMAP toolkit, including the IMAP and POP servers. The IMAP and
          POP servers limit what can be done while not logged in, and as
          part of the login process discard all privileges except those
          of the user.

          As with other software packages, there have been buffer
          overflow vulnerabilities in past versions. All known problems
          of this nature are fixed in this version.

          There is every reason to believe that the bad guys are engaged
          in an ongoing effort to find vulnerabilities in the IMAP
          toolkit. We look for such problems, and when one is found we
          fix it.

          It's unfortunate that any vulnerabilities existed in past
          versions, and we're doing my best to keep the IMAP toolkit free
          of vulnerabilities. No new vulnerabilities have been discovered
          in quite a while, but efforts will not be relaxed.

          Beware of vendors who claim that their implementations can not
          have vulnerabilities.
     _________________________________________________________________

   5.3 How do I know that I have the most secure version of the server?

          The best way is to keep your server software up to date. The
          bad guys are always looking for ways to crack software, and
          when they find one, let all their friends know.

          Oldtimers used to refer to a concept of software rot: if your
          software hasn't been updated in a while, it would &quot;rot&quot; -- tend
          to acquire problems that it didn't have when it was new.

          The latest release version of the IMAP toolkit is always
          available at ftp://ftp.cac.washington.edu/mail/imap.tar.Z
     _________________________________________________________________

   5.4 I see all these strcpy() and sprintf() calls, those are unsafe,
   aren't they?

          Yes and no.

          It can be unsafe to do these calls if you do not know that the
          string being written will fit in the buffer. However, they are
          perfectly safe if you do know that.

          Beware of programmers who advocate doing a brute-force change
          of all instances of

 strcpy (s,t);

          to

 strncpy (s,t,n)[n] = '\0';

          and similar measures in the name of &quot;fixing all possible buffer
          overflows.&quot;

          There are examples in which a security bug was introduced
          because of this type of &quot;fix&quot;, due to the programmer using the
          wrong value for n. In one case, the programmer thought that n
          was larger than it actually was, causing a NUL to be written
          out of the buffer; in another, n was too small, and a security
          credential was truncated.

          What is particularly ironic was that in both cases, the
          original strcpy() was safe, because the size of the source
          string was known to be safe.

          With all this in mind, the software has been inspected, and it
          is believed that all places where buffer overflows can happen
          have been fixed. The strcpy()s that are still are in the code
          occur after a size check was done in some other way.

          Note that the common C idiom of

 *s++ = c;

          is just as vulnerable to buffer overflows. You can't cure
          buffer overflows by outlawing certain functions, nor is it
          desirable to do so; sometimes operations like strcpy()
          translate into fast machine instructions for better
          performance.

          Nothing replaces careful study of code. That's how the bad guys
          find bugs. Security is not accomplished by means of brute-force
          shortcuts.
     _________________________________________________________________

   5.5 Those /tmp lock files are protected 666, is that really right?

          Yes. Shared mailboxes won't work otherwise. Also, you get into
          accidental denial of service problems with old lock files left
          lying around; this happens fairly frequently.

          The deliberate mischief that can be caused by fiddling with the
          lock files is small-scale; harassment level at most. There are
          many -- and much more effective -- other ways of harassing
          another user on UNIX. It's usually not difficult to determine
          the culprit.

          Before worrying about deliberate mischief, worry first about
          things happening by accident!
     _________________________________________________________________

6. Why Did You Do This Strange Thing? Questions
     _________________________________________________________________

   6.1 Why don't you use GNU autoconfig / automake / autoblurdybloop?

          Autoconfig et al are not available on all the platforms where
          the IMAP toolkit is supported; and do not work correctly on
          some of the platforms where they do exist. Furthermore, these
          programs add another layer of complexity to an already complex
          process.

          Coaxing software that uses autoconfig to build properly on
          platforms which were not specifically considered by that
          software wastes an inordinate amount of time. When (not if)
          autoconfig fails to do the right thing, the result is an
          inpenetrable morass to untangle in order to find the problem
          and fix it.

          The concept behind autoconfig is good, but the execution is
          flawed. It rarely does the right thing on a platform that
          wasn't specifically considered. Human life is too short to
          debug autoconfig problems, especially since the current
          mechanism is so much easier.
     _________________________________________________________________

   6.2 Why do you insist upon a build with -g? Doesn't it waste disk and
   memory space?

          From time to time a submitted port has snuck in without -g.
          This has always ended up causing problems. There are only two
          valid excuses for not using -g in a port:

          + The compiler does not support -g
          + An alternate form of -g is needed with optimization, e.g.
            -g3.

          There will be no new ports added without -g (or a suitable
          alternative) being set.

          -g has not been arbitrarily added to the ports which do not
          currently have it because we don't know if doing so would break
          the build. However, any support issues with one of those port
          will lead to the correct -g setting being determined and
          permanently added.

          Processors are fast enough (and disk space is cheap enough)
          that -g should be automatic in all compilers with no way of
          turning it off, and /bin/strip should be a symlink to
          /bin/true. Human life is too short to deal with binaries built
          without -g. Such binaries should be a bad memory of the days of
          KIPS processors and disks that costs several dollars per
          kilobyte.
     _________________________________________________________________

   6.3 Why don't you make c-client a shared library?

          All too often, shared libraries create far more problems than
          they solve.

          Remember that you only gain the benefit of a shared library
          when there are multiple applications which use that shared
          library. Even without shared libraries, on most modern
          operating systems (and many ancient ones too!) applications
          will share their text segments between across multiple
          processes running the same application. This means that if your
          system only runs one application (e.g. imapd) that uses the
          c-client library, then you gain no benefit from making c-client
          a shared library even if it has 100 imapd processes. You will,
          however suffer added complexity.

          If you have a server system that just runs imapd and ipop3d,
          then making c-client a shared library will save just one copy
          of c-client no matter how many IMAP/POP3 processes are running.

          The problem with shared libraries is that you have to keep
          around a copy of the library every time something changes in
          the library that would affect the interface the library
          presents to the application. So, you end up having many copies
          of the same shared library.

          If you don't keep multiple copies of the shared library, then
          one of two things happens. If there was proper versioning, then
          you'll get a message such as &quot;cannot open shared object file&quot;
          or &quot;minor versions don't match&quot; and the application won't run.
          Otherwise, the application will run, but will fail in
          mysterious ways.

          Several sites and third-party distributors have modified the
          c-client makefile in order to make c-client be a shared
          library. When (not if) a c-client based application fails in
          mysterious ways because of a library compatibility problem, the
          result is a bug report. A lot of time and effort ends up
          getting wasted investigating such bug reports.

          Memory is so cheap these days that it's not worth it. Human
          life is too short to deal with shared library compatibility
          problems.
     _________________________________________________________________

   6.4 Why don't you use iconv() for internationalization support?

          iconv() is not ubiquitous enough.
     _________________________________________________________________

   6.5 Why is the IMAP server connected to the home directory by default?

          The IMAP server has no way of knowing what you might call
          &quot;mail&quot; as opposed to &quot;some other file&quot;; in fact, you can use
          IMAP to access any file.

          The IMAP server also doesn't know whether your preferred
          subdirectory for mailbox files is &quot;mail/&quot;, &quot;.mail/&quot;, &quot;Mail/&quot;,
          &quot;Mailboxes/&quot;, or any of a zillion other possibilities. If one
          such name were chosen, it would undoubtably anger the partisans
          of all the other names.

          It is possible to modify the software so that the default
          connected directory is someplace else. Please read the file
          CONFIG for discussion of this and other issues.
     _________________________________________________________________

   6.6 I have a Windows system. Why isn't the server plug and play for
   me?

          There is no standard for how mail is stored on Windows; nor a
          single standard SMTP server. The closest to either would be the
          SMTP server in Microsoft's IIS.

          So there's no default by which to make assumptions. As the
          software is set up, it assumes that the each user has an
          Windows login account and private home directory, and that mail
          is stored on that home directory as files in one of the popular
          UNIX formats. It also assumes that there is some tool
          equivalent to inetd on UNIX that does the TCP/IP listening and
          server startup.

          Basically, unless you're an email software hacker, you probably
          want to look elsewhere if you want IMAP/POP servers for
          Windows.
     _________________________________________________________________

   6.7 I looked at the UNIX SSL code and saw that you have the SSL data
   payload size set to 8192 bytes. SSL allows 16K; why aren't you using
   the full size?

          This is to avoid an interoperability problem with:

          + PC IMAP clients that use Microsoft's SChannel.DLL (SSPI) for
            SSL support
          + Microsoft Exchange server (which also uses SChannel).

          SChannel has a bug that makes it think that the maximum SSL
          data payload size is 16379 bytes -- 5 bytes too small. Thus,
          c-client has to make sure that it never transmits full sized
          SSL packets.

          The reason for using 8K (as opposed to, say, 16379 bytes, or
          15K, or...) is that it corresponds with the TCP buffer size
          that the software uses elsewhere for input; there's a slight
          performance benefit to having the two sizes correspond or at
          least be a multiple of each other. Also, it keeps the size as a
          power of two, which might be significant on some platforms.

          There wasn't a significant difference that we could measure
          between 8K and 15K.

          Microsoft has developed a hotfix for this bug. Look up MSKB
          article number 300562. Contrary to the article text which
          implies that this is a Pine issue, this bug also affects
          Microsoft Exchange server with any client that transmits
          full-sized SSL payloads.
     _________________________________________________________________

   6.8 Why is an mh format INBOX called #mhinbox instead of just INBOX?

          It's a long story. In brief, the mh format driver is less
          functional than any of the other drivers. It turned out that
          there were some users (including high-level administrators) who
          tried mh years ago and no longer use it, but still had an mh
          profile left behind.

          When the mh driver used INBOX, it would see the mh profile, and
          proceed to move the user's INBOX into the mh format INBOX. This
          caused considerable confusion as some things stopped working.
     _________________________________________________________________

   6.9 Why don't you support the maildir format?

          It is technically difficult to support maildir in IMAP while
          maintaining acceptable performance, robustness, following the
          requirements of the IMAP protocol specification, and following
          the requirements of maildir.

          No one has succeeded in accomplishing all four together. The
          various maildir drivers offered as patches all have these
          problems. The problem is exacerbated because this
          implementation supports multiple formats; consequently this
          implementation can't make any performance shortcuts by assuming
          that all the world is maildir.

          We can't do a better job than the maildir fan community has
          done with their maildir drivers. Similarly, if the maildir fan
          community provides the maildir driver, they take on the
          responsibility for answering maildir-specific support
          questions. This is as it should be, and that is why maildir
          support is left to the maildir fan community.
     _________________________________________________________________

   6.10 Why don't you support the Cyrus format?

          There's no point to doing so. An implementation which supports
          multiple formats will never do as well as one which is
          optimized to support one single format.

          If you want to use Cyrus mailbox format, you should use the
          Cyrus server, which is the native implementation of that format
          and is specifically optimized for that format. That's also why
          Cyrus doesn't implement any other format.
     _________________________________________________________________

   6.11 Why is it creating extra forks on my SVR4 system?

          This is because your system only has fcntl() style locking and
          not flock() style locking. fcntl() locking has a design flaw
          that causes a close() to release any locks made by that process
          on the file opened on that file descriptor, even if the lock
          was made on a different file descriptor.

          This design flaw causes unexpected loss of lock, and consequent
          mailbox corruption. The workaround is to do certain &quot;dangerous
          operations&quot; in another fork, thus avoiding doing a close() in
          the vulnerable fork.

          The best way to solve this problem is to upgrade your SVR4
          (Solaris, AIX, HP-UX, SGI) or OSF/1 system to a more advanced
          operating system, such as Linux or BSD. These more advanced
          operating systems have fcntl() locking for compatibility with
          SVR4, but also have flock() locking.

          Beware of certain SVR4 systems, such as AIX, which have an
          &quot;flock()&quot; function in their C library that is just a jacket
          that does an fcntl() lock. This is not a true flock(), and has
          the same design flaw as fcntl().
     _________________________________________________________________

   6.12 Why are you so fussy about the date/time format in the internal
   &quot;From &quot; line in traditional UNIX mailbox files? My other mail program
   just considers every line that starts with &quot;From &quot; to be the start of
   the message.

          You just answered your own question. If any line that starts
          with &quot;From &quot; is treated as the start of a message, then every
          message text line which starts with &quot;From &quot; has to be quoted
          (typically by prefixing a &quot;&gt;&quot; character). People complain about
          this -- &quot;why did a &gt; get stuck in my message?&quot;

          So, good mail reading software only considers a line to be a
          &quot;From &quot; line if it follows the actual specification for a
          &quot;From &quot; line. This means, among other things, that the day of
          week is fixed-format: &quot;May 14&quot;, but &quot;May  7&quot; (note the extra
          space) as opposed to &quot;May 7&quot;. ctime() format for the date is
          the most common, although POSIX also allows a numeric timezone
          after the year. For compatibility with ancient software, the
          seconds are optional, the timezone may appear before the year,
          the old 3-letter timezones are also permitted, and &quot;remote from
          xxx&quot; may appear after the whole thing.

          Unfortunately, some software written by novices use other
          formats. The most common error is to have a variable-width day
          of month, perhaps in the erroneous belief that RFC 2822 (or RFC
          822) defines the format of the date/time in the &quot;From &quot; line
          (it doesn't; no RFC describes internal formats). I've seen a
          few other goofs, such as a single-digit second, but these are
          less common.

          If you are writing your own software that writes mailbox files,
          and you really aren't all that savvy with all the ins and outs
          and ancient history, you should seriously consider using the
          c-client library (e.g. routine mail_append()) instead of doing
          the file writes yourself. If you must do it yourself, use
          ctime(), as in:

 fprintf (mbx,&quot;From %s@%h %s&quot;,user,host,ctime (time (0)));

          rather than try to figure out a good format yourself. ctime()
          is the most traditional format and nobody will flame you for
          using it.
     _________________________________________________________________

   6.13 Why is traditional UNIX format the default format?

          Compatibility with the past 30 or so years of UNIX history.
          This server is the only one that completely interoperates with
          legacy UNIX mail tools.
     _________________________________________________________________

   6.14 Why do you write this &quot;DON'T DELETE THIS MESSAGE -- FOLDER
   INTERNAL DATA&quot; message at the start of traditional UNIX and MMDF
   format mailboxes?

          This pseudo-message serves two purposes.

          First, it establishes the mailbox format even when the mailbox
          has no messages. Otherwise, a mailbox with no messages is a
          zero-byte file, which could be one of several formats.

          Second, it holds mailbox metadata used by IMAP: the UID
          validity, the last assigned UID, and mailbox keywords. Without
          this metadata, which must be preserved even when the mailbox
          has no messages, the traditional UNIX format wouldn't be able
          to support the full capabilities of IMAP.
     _________________________________________________________________

   6.15 Why don't you stash the mailbox metadata in the first real
   message of the mailbox instead of writing this fake FOLDER INTERNAL
   DATA message?

          In fact, that is what is done if the mailbox is non-empty and
          does not already have a FOLDER INTERNAL DATA message.

          One problem with doing that is that if some external program
          removes the first message, the metadata is lost and must be
          recreated, thus losing any prior UID or keyword list status
          that IMAP clients may depend upon.

          Another problem is that this doesn't help if the last message
          is deleted. This will result in an empty mailbox, and the
          necessity to create a FOLDER INTERNAL DATA message.
     _________________________________________________________________

   6.16 Why aren't &quot;dual-use&quot; mailboxes the default?

          Compatibility with the past 30 or so years of UNIX history, not
          to mention compatibility with user expectations when using
          shell tools.
     _________________________________________________________________

   6.17 Why do you use ucbcc to build on Solaris?

          It is a long, long story about why cc is set to ucbcc. You need
          to invoke the C compiler so that it links with the SVR4
          libraries and not the BSD libraries, otherwise readdir() will
          return the wrong information.

          Of all the names in the most common path, ucbcc is the only
          name to be found (on /usr/ccs/bin) that points to a suitable
          compiler. cc is likely to be /usr/ucb/cc which is absolutely
          not the compiler that you want. The real SVR4 cc is probably
          something like /opt/SUNWspro/bin/cc which is rarely in anyone's
          path by default.

          ucbcc is probably a link to acc, e.g.
          /opt/SUNWspro/SC4.0/bin/acc, and is the UCB C compiler using
          the SVR4 libraries.

          If ucbcc isn't on your system, then punt on the SUN C compiler
          and use gcc instead (the gso port instead of the sol port).

          If, in spite of all the above warnings, you choose to change
          &quot;ucbcc&quot; to &quot;cc&quot;, you will probably find that the -O2 needs to
          be changed to -O. If you don't get any error messages with -O2,
          that's a pretty good indicator that you goofed and are running
          the compiler that will link with the BSD libraries.

          To recap:

          + The sol port is designed to be built using the UCB compiler
            using the SVR4 libraries. This compiler is &quot;ucbcc&quot;, which is
            lunk to acc. You use -O2 as one of the CFLAGS.
          + If you build the sol port with the UCB compiler using the BSD
            libraries, you will get no error messages but you will get
            bad binaries (the most obvious symptom is dropping the first
            two characters return filenames from the imapd LIST command.
            This compiler also uses -O2, and is very often what the user
            gets from &quot;cc&quot;. BEWARE
          + If you build the sol port with the real SVR4 compiler, which
            is often hidden away or unavailable on many systems, then you
            will get errors from -O2 and you need to change that to -O.
            But you will get a good binary. However, you should try it
            with -O2 first, to make sure that you got this compiler and
            not the UCB compiler using BSD libraries.
     _________________________________________________________________

   6.18 Why should I care about some old system with BSD libraries? cc is
   the right thing on my Solaris system!

          Because there still are sites that use such systems. On those
          systems, the assumption that &quot;cc&quot; does the right thing will
          lead to corrupt binaries with no error message or other warning
          that anything is amiss.

          Too many sites have fallen victim to this problem.
     _________________________________________________________________

   6.19 Why do you insist upon writing .lock files in the spool
   directory?

          Compatibility with the past 30 years of UNIX software which
          deals with the spool directory, especially software which
          delivers mail. Otherwise, it is possible to lose mail.
     _________________________________________________________________

   6.20 Why should I care about compatibility with the past?

          This is one of those questions in which the answer never
          convinces those who ask it. Somehow, everybody who ever asks
          this question ends up answering it for themselves as they get
          older, with the very answer that they rejected years earlier.
     _________________________________________________________________

7. Problems and Annoyances
     _________________________________________________________________

   7.1 Help! My INBOX is empty! What happened to my messages?

          If you are seeing &quot;0 messages&quot; when you open INBOX and you know
          you have messages there (and perhaps have looked at your mail
          spool file and see that messages are there), then probably
          there is something wrong with the very first line of your mail
          spool file. Make sure that the first five bytes of the file are
          &quot;From &quot;, followed by an email address and a date/time in
          ctime() format, e.g.:

 From fred@foo.bar Mon May  7 20:54:30 2001
     _________________________________________________________________

   7.2 Help! All my messages in a non-INBOX mailbox have been
   concatenated into one message which claims to be from me and has a
   subject of the file name of the mailbox! What's going on?

          Something wrong with the very first line of the mailbox. Make
          sure that the first five bytes of the file are &quot;From &quot;,
          followed by an email address and a date/time in ctime() format,
          e.g.:

 From fred@foo.bar Mon May  7 20:54:30 2001
     _________________________________________________________________

   7.3 Why do I get the message: CREATE failed: Can't create mailbox node
   xxxxxxxxx: File exists and how do I fix it?

          See the answer to the Are hierarchical mailboxes supported?
          question.
     _________________________________________________________________

   7.4 Why can't I log in to the server? The user name and password are
   right!

          There are a myriad number of possible answers to this question.
          The only way to say for sure what is wrong is run the server
          under a debugger such as gdb while root (yes, you must be root)
          with a breakpoint at routines checkpw() and loginpw(), then
          single-step until you see which test rejected you. The server
          isn't going to give any error messages other than &quot;login
          failed&quot; in the name of not giving out any unnecessary
          information to unauthorized individuals.

          Here are some of the more common reasons why login may fail:

          + You didn't really give the correct user name and/or password.
          + Your client doesn't send the LOGIN command correctly; for
            example, IMAP2 clients won't send a password containing a &quot;*&quot;
            correctly to an IMAP4 server.
          + If you have set up a CRAM-MD5 database, remember that the
            password used is the one in the CRAM-MD5 database, and
            furthermore that there must also be an entry in /etc/passwd
            (but the /etc/passwd password is not used).
          + If you are using PAM, have you created a service file for the
            server in /etc/pam.d?
          + If you are using shadow passwords, have you used an
            appropriate port when building? In particular, note that
            &quot;lnx&quot; is for Linux systems without shadow passwords; you
            probably want &quot;slx&quot; or &quot;lnp&quot; instead.
          + If your system has account or password expirations, check to
            see that the expiration date hasn't passed.
          + You can't log in as root or any other UID 0 user. This is for
            your own safety, not to mention the fact that the servers use
            UID 0 as meaning &quot;not logged in&quot;.
     _________________________________________________________________

   7.5 Help! My load average is soaring and I see hundreds of POP and
   IMAP servers, many logged in as the same user!

          Certain inferior losing GUI mail reading programs have a
          &quot;synchronize all mailboxes at startup&quot; (IMAP) or &quot;check for new
          mail every second&quot; (POP) feature which causes a rapid and
          unchecked spawning of servers.

          This is not a problem in the server; the client is really
          asking for all those server sessions. Unfortunately, there
          isn't much that the POP and IMAP servers can do about it; they
          don't spawned themselves.

          Some sites have added code to record the number of server
          sessions spawned per user per hour, and disable login for a
          user who has exceeded a predetermined rate. This doesn't stop
          the servers from being spawned; it just means that a server
          session will commit suicide a bit faster.

          Another possibility is to detect excessive server spawning
          activity at the level where the server is spawned, which would
          be inetd or possibly tcpd. The problem here is that this is a
          hard time to quantify. 50 sessions in a minute from a
          multi-user timesharing system may be perfectly alright, whereas
          10 sessions a minute from a PC may be too much.

          The real solution is to fix the client configuration, by
          disabling those evil features. Also tell the vendors of those
          clients how you feel about distributing denial-of-service
          attack tools in the guise of mail reading programs.
     _________________________________________________________________

   7.6 Why does mail disappear even though I set &quot;keep mail on server&quot;?
   7.7 Why do I get the message Moved ##### bytes of new mail to
   /home/user/mbox from /var/spool/mail/user and why did this happen?

          This is probably caused by the mbox driver. If the file &quot;mbox&quot;
          exists on the user's home directory and is in UNIX mailbox
          format, then when INBOX is opened this file will be selected as
          INBOX instead of the mail spool file. Messages will be
          automatically transferred from the mail spool file into the
          mbox file.

          To disable this behavior, delete &quot;mbox&quot; from the EXTRADRIVERS
          list in the top-level Makefile and rebuild. Note that if you do
          this, users won't be able to access the messages that have
          already been moved to mbox unless they open mbox instead of
          INBOX.
     _________________________________________________________________

   7.8 Why isn't it showing the local host name as a fully-qualified
   domain name?
   7.9 Why is the local host name in the From/Sender/Message-ID headers
   of outgoing mail not coming out as a fully-qualified domain name?

          Your UNIX system is misconfigured. The entry for your system in
          /etc/hosts must have the fully-qualified domain name first,
          e.g.

 105.69.1.234   myserver.example.com myserver

          A common mistake of novice system administrators is to have the
          short name first, e.g.

 105.69.1.234   myserver myserver.example.com

          or to omit the fully qualified domain name entirely, e.g.

 105.69.1.234   myserver

          The result of this is that when the IMAP toolkit does a
          gethostbyname() call to get the fully-qualified domain name, it
          would get &quot;myserver&quot; instead of &quot;myserver.example.com&quot;.

          On some systems, a configuration file (typically named
          /etc/svc.conf, /etc/netsvc.conf, or /etc/nsswitch.conf) can be
          used to configure the system to use the domain name system
          (DNS) instead of /etc/hosts, so it doesn't matter if /etc/hosts
          is misconfigured.

          Check the man pages for gethostbyname, hosts, svc, and/or
          netsvc for more information.

          Unfortunately, certain vendors, most notably SUN, have failed
          to make this clear in their documentation. Most of SUN's
          documentation assumes a corporate network that is not connected
          to the Internet.

          net.folklore once (late 1980s) held that the proper procedure
          was to append the results of getdomainname() to the name
          returned by gethostname(), and some versions of sendmail
          configuration files were distributed that did this. This was
          incorrect; the string returned from getdomainname() is the
          Yellow Pages (a.k.a NIS) domain name, which is a completely
          different (albeit unfortunately named) entity from an Internet
          domain. These were often fortuitously the same string, except
          when they weren't. Frequently, this would result in host names
          with spuriously doubled domain names, e.g.

 myserver.example.com.example.com

          This practice has been thoroughly discredited for many years,
          but folklore dies hard.
     _________________________________________________________________

   7.10 What does the message: Mailbox vulnerable - directory
   /var/spool/mail must have 1777 protection mean? How can I fix this?

          In order to update a mailbox in the default UNIX format, it is
          necessary to create a lock file to prevent the mailer from
          delivering mail while an update is in progress. Some systems
          use a directory protection of 775, requiring that all mail
          handling programs be setgid mail; or of 755, requiring that all
          mail handling programs be setuid root.

          The IMAP toolkit does not run with any special privileges, and
          I plan to keep it that way. It is antithetical to the concept
          of a toolkit if users can't write their own programs to use it.
          Also, I've had enough bad experiences with security bugs while
          running privileged; the IMAP and POP servers have to be root
          when not logged in, in order to be able to log themselves in. I
          don't want to go any deeper down that slippery slope.

          Directory protection 1777 is secure enough on most well-managed
          systems. If you can't trust your users with a 1777 mail spool
          (petty harassment is about the limit of the abuse exposure),
          then you have much worse problems then that.

          If you absolutely insist upon requiring privileges to create a
          lock file, external file locking can be done via a setgid mail
          program named /etc/mlock (this is defined by LOCKPGM in the
          c-client Makefile). If the toolkit is unable to create a
          &lt;...mailbox...&gt;.lock file in the directory by itself, it will
          try to call mlock to do it. I do not recommend doing this for
          performance reasons.

          A sample mlock program is included as part of imap-2007. We
          have tried to make this sample program secure, but it has not
          been thoroughly audited.
     _________________________________________________________________

   7.11 What does the message: Mailbox is open by another process, access
   is readonly mean? How do I fix this?

          A problem occurred in applying a lock to a /tmp lock file.
          Either some other program has the mailbox open and won't
          relenquish it, or something is wrong with the protection of
          /tmp or the lock.

          Make sure that the /tmp directory is protected 1777. Some
          security scripts incorrectly set the protection of the /tmp
          directory to 775, which disables /tmp for all non-privileged
          programs.
     _________________________________________________________________

   7.12 What does the message: Can't get write access to mailbox, access
   is readonly mean?

          The mailbox file is write-protected against you.
     _________________________________________________________________

   7.13 I set my POP3 client to &quot;delete messages from server&quot; but they
   never get deleted. What is wrong?

          Make sure that your mailbox is not read-only: that the mailbox
          is owned by you and write enabled (protection 0600), and that
          the /tmp directory is longer world-writeable. /tmp must be
          world-writeable because lots of applications use it for scratch
          space. To fix this, do


 chmod 1777 /tmp

          as root.

          Make sure that your POP3 client issues a QUIT command when it
          finishes. The POP3 protocol specifies that deletions are
          discarded unless a proper QUIT is done.

          Make sure that you are not opening multiple POP3 sessions to
          the same mailbox. It is a requirement of the POP3 protocol than
          only one POP3 session be in effect to a mailbox at a time,
          however some, poorly-written POP3 clients violate this. Also,
          some background &quot;check for new mail&quot; tasks also cause a
          violation. See the answer to the What does the syslog message:
          Killed (lost mailbox lock) user=... host=... mean? question for
          more details.
     _________________________________________________________________

   7.14 What do messages such as:
 Message ... UID ... already has UID ...
 Message ... UID ... less than ...
 Message ... UID ... greater than last ...
 Invalid UID ... in message ..., rebuilding UIDs

   mean?

          Something happened to corrupt the unique identifier regime in
          the mailbox. In traditional UNIX-format mailboxes, this can
          happen if the user deleted the &quot;DO NOT DELETE&quot; internal
          message.

          This problem is relatively harmless; a new valid unique
          identifier regime will be created. The main effect is that any
          references to the old UIDs will no longer be useful.

          So, unless it is a chronic problem or you feel like debugging,
          you can safely ignore these messages.
     _________________________________________________________________

   7.15 What do the error messages:
 Unable to read internal header at ...
 Unable to find CRLF at ...
 Unable to parse internal header at ...
 Unable to parse message date at ...
 Unable to parse message flags at ...
 Unable to parse message UID at ...
 Unable to parse message size at ...
 Last message (at ... ) runs past end of file ...

   mean? I am using mbx format.

          The mbx-format mailbox is corrupted and needs to be repaired.

          You should make an effort to find out why the corruption
          happened. Was there an obvious system problem (crash or disk
          failure)? Did the user accidentally access the file via NFS?
          Mailboxes don't get corrupted by themselves; something caused
          the problem.

          Some people have developed automated scripts, but if you're
          comfortable using emacs it's pretty easy to fix it manually. Do
          not use vi or any other editor unless you are certain that
          editor can handle binary!!!

          If you are not comfortable with emacs, or if the file is too
          large to read with emacs, see the &quot;step-by-step&quot; technique
          later on for another way of doing it.

          After the word &quot;at&quot; in the error message is the byte position
          it got to when it got unhappy with the file, e.g. if you see:

 Unable to parse internal header at 43921: ne bombastic blurdybloop

          The problem occurs at the 43,931 byte in the file. That's the
          point you need to fix. c-client is expecting an internal header
          at that byte number, looking something like:

 6-Jan-1998 17:42:24 -0800,1045;000000100001-00000001

          The format of this internal line is:

 dd-mmm-yyyy hh:mm:ss +zzzz,ssss;ffffffffFFFF-UUUUUUUU

          The only thing that is variable is the &quot;ssss&quot; field, it can be
          as many digits as needed. All other fields (inluding the &quot;dd&quot;)
          are fixed width. So, the easiest thing to do is to look forward
          in the file for the next internal header, and delete everything
          from the error point to that internal header.

          Here's what to do if you want to be smarter and do a little bit
          more work. Generally, you're in the middle of a message, and
          there's nothing wrong with that message. The problem happened
          in the *previous* message. So, search back to the previous
          internal header. Now, remember that &quot;ssss&quot; field? That's the
          size of that message.

          Mark where you are in the file, move the cursor to the line
          after the internal header, and skip that many bytes (&quot;ssss&quot;)
          forward. If you're at the point of the error in the file, then
          that message is corrupt. If you're at a different point, then
          perhaps the previous message is corrupt and has a too long size
          count that &quot;ate&quot; into this message.

          Basically, what you need to do is make sure that all those size
          counts are right, and that moving &quot;ssss&quot; bytes from the line
          after the internal header will land you at another internal
          header.

          Usually, once you know what you're looking at, it's pretty easy
          to work out the corruption, and the best remedial action.
          Repair scripts will make the problem go away but may not always
          do the smartest/best salvage of the user's data. Manual repair
          is more flexible and usually preferable.

          Here is a step-by-step technique for fixing corrupt mbx files
          that's a bit cruder than the procedure outlined above, but
          works for any size file.

          In this example, suppose that the corrupt file is INBOX, the
          error message is

 Unable to find CRLF at 132551754

          and the size of the INBOX file is 132867870 bytes.

          The first step is to split the mailbox file at the point of the
          error:

          + Rename the INBOX file to some other name, such as INBOX.bad.
          + Copy the first 132,551,754 bytes of INBOX.bad to another
            file, such as INBOX.new.
          + Extract the trailing 316,116 bytes (132867870-132551754) of
            INBOX.bad into another file, such as INBOX.tail.
          + You no longer need INBOX.bad. Delete it.

          In other words, use the number from the &quot;Unable to find CRLF
          at&quot; as the point to split INBOX into two new files, INBOX.new
          and INBOX.tail.

          Now, remove the erroneous data:

          + Verify that you can open INBOX.new in IMAP or Pine.
          + The last message of INBOX.new is probably corrupted. Copy it
            to another file, such as badmsg.1, then delete and expunge
            that last message from INBOX.new
          + Locate the first occurance of text in INBOX.tail which looks
            like an internal header, as described above.
          + Remove all the text which occurs prior to that point, and
            place it into another file, such as badmsg.2. Note that in
            the case of a single digit date, there is a leading space
            which must not be removed (e.g. &quot; 6-Nov-2001&quot; not
            &quot;6-Nov-2001&quot;).

          Reassemble the mailbox:

          + Append INBOX.tail to INBOX.new.
          + You no longer need INBOX.tail. Delete it.
          + Verify that you can open INBOX.new in IMAP or Pine.

          Reinstall INBOX.new as INBOX:

          + Check to see if you have received any new messages while
            repairing INBOX.
          + If you haven't received any new messages while repairing
            INBOX, just rename INBOX.new to INBOX.
          + If you have received new messages, be sure to copy the new
            messages from INBOX to INBOX.new before doing the rename.

          You now have a working INBOX, as well as two files with
          corrupted data (badmsg.1 and badmsg.2). There may be some
          useful data in the two badmsg files that you might want to try
          salvaging; otherwise you can delete the two badmsg files.
     _________________________________________________________________

   7.16 What do the syslog messages:

 imap/tcp server failing (looping)
 pop3/tcp server failing (looping)

   mean? When it happens, the listed service shuts down. How can I fix
   this?

          The error message &quot;server failing (looping), service
          terminated&quot; is not from either the IMAP or POP servers.
          Instead, it comes from inetd, the daemon which listens for TCP
          connections to a number of servers, including the IMAP and POP
          servers.

          inetd has a limit of 40 new server sessions per minute for any
          particular service. If more than 40 sessions are initiated in a
          minute, inetd will issue the &quot;failing (looping), service
          terminated&quot; message and shut down the service for 10 minutes.
          inetd does this to prevent system resource consumption by a
          client which is spawning infinite numbers of servers. It should
          be noted that this is a denial of service; however for some
          systems the alternative is a crash which would be a worse
          denial of service!

          For larger server systems, the limit of 40 is much too low. The
          limit was established many years ago when a system typically
          only ran a few dozen servers.

          On some versions of inetd, such as the one distributed with
          most versions of Linux, you can modify the /etc/inetd.conf file
          to have a larger number of servers by appending a period
          followed by a number after the nowait word for the server
          entry. For example, if your existing /etc/inetd.conf line
          reads:

 imap    stream  tcp     nowait  root    /usr/etc/imapd imapd

          try changing it to be:

 imap    stream  tcp     nowait.100  root    /usr/etc/imapd imapd

          Another example (using TCP wrappers):

 imap    stream  tcp     nowait  root    /usr/sbin/tcpd  imapd

          try changing it to be:

 imap    stream  tcp     nowait.100  root    /usr/sbin/tcpd  imapd

          to increase the limit to 100 sessions/minute.

          Before making this change, please read the information in &quot;man
          inetd&quot; to determine whether or not your inetd has this feature.
          If it does not, and you make this change, the likely outcome is
          that you will disable IMAP service entirely.

          Another way to fix this problem is to edit the inetd.c source
          code (provided by your UNIX system vendor) to set higher
          limits, rebuild inetd, install the new binary, and reboot your
          system. This should only be done by a UNIX system expert. In
          the inetd.c source code, the limits TOOMANY (normally 40) is
          the maximum number of new server sessions permitted per minute,
          and RETRYTIME (normally 600) is the number of seconds inetd
          will shut down the server after it exceeds TOOMANY.
     _________________________________________________________________

   7.17 What does the syslog message: Mailbox lock file /tmp/.600.1df3
   open failure: Permission denied mean?

          This usually means that some &quot;helpful&quot; security script person
          has protected /tmp so that it is no longer world-writeable.
          /tmp must be world-writeable because lots of applications use
          it for scratch space. To fix this, do

 chmod 1777 /tmp

          as root.

          If that isn't the answer, check the protection of the named
          file. If it is something other than 666, then either someone is
          hacking or some &quot;helpful&quot; person modified the code to have a
          different default lock file protection.
     _________________________________________________________________

   7.18 What do the syslog messages:
 Command stream end of file, while reading line user=... host=...
 Command stream end of file, while reading char user=... host=...
 Command stream end of file, while writing text user=... host=...

   mean?

          This message occurs when the session is disconnected without a
          proper LOGOUT (IMAP) or QUIT (POP) command being received by
          the server first.

          In many cases, this is perfectly normal; many client
          implementations are impolite and do this. Some programmers
          think this sort of rudeness is &quot;more efficient&quot;.

          The condition could, however, indicate a client or network
          connectivity problem. The server has no way of knowing whether
          there's a problem or just a rude client, so it issues this
          message instead of a Logout.

          Certain inferior losing clients disconnect abruptly after a
          failed login, and instead of saying that the login failed, just
          say that they can't access the mailbox. They then complain to
          the system manager, who looks in the syslog and finds this
          message. Not very helpful, eh? See the answer to the Why can't
          I log in to the server? The user name and password are right!
          question.

          If the user isn't reporting a problem, you can probably ignore
          this message.
     _________________________________________________________________

   7.19 Why did my POP or IMAP session suddenly disconnect? The syslog
   has the message: Killed (lost mailbox lock) user=... host=...

          This message only happens when either the traditional UNIX
          mailbox format or MMDF format is in use. This format only
          allows one session to have the mailbox open read/write at a
          time.

          The servers assume that if a second session attempts to open
          the mailbox, that means that the first session is probably
          owned by an abandoned client. The common scenario here is a
          user who leaves his client running at the office, and then
          tries to read his mail from home. Through an internal mechanism
          called kiss of death, the second session requests the first
          session to kill itself. When the first session receives the
          &quot;kiss of death&quot;, it issues the &quot;Killed (lost mailbox lock)&quot;
          syslog message and terminates. The second session then seizes
          read/write access, and becomes the new &quot;first&quot; session.

          Certain poorly-designed clients routinely open multiple
          sessions to the same mailbox; the users of those clients tend
          to get this message a lot.

          Another cause of this message is a background &quot;check for new
          mail&quot; task which does its work by opening a POP session to
          server every few seconds. They do this because POP doesn't have
          a way to announce new mail.

          The solution to both situations is to replace the client with a
          good online IMAP client such as Pine. Life is too short to
          waste on POP clients and poorly-designed IMAP clients.
     _________________________________________________________________

   7.20 Why does my IMAP client show all the files on the system,
   recursively from the UNIX root directory?
   7.21 Why does my IMAP client show all of my files, recursively from my
   UNIX home directory?

          A well-written client should only show one level of hierarchy
          and then stop, awaiting explicit user action before going
          lower. However, some poorly-designed clients will recursively
          list all files, which may be a very long list (especially if
          you have symbolic links to directories that create a loop in
          the filesystem graph!).

          This behavior has also been observed in some third-party
          c-client drivers, including maildir drivers. Consequently, this
          problem has even been observed in Pine. It is important to
          understand that this is not a problem in Pine or c-client; it
          is a problem in the third-party driver. A Pine built without
          that third-party driver will not have this problem.

          See also the answer to Why does my IMAP client show all my
          files in my home directory?
     _________________________________________________________________

   7.22 Why does my IMAP client show that I have mailboxes named
   &quot;#mhinbox&quot;, &quot;#mh&quot;, &quot;#shared&quot;, &quot;#ftp&quot;, &quot;#news&quot;, and &quot;#public&quot;?

          These are IMAP namespace names. They represent other
          hierarchies in which messages may exist. These hierarchies may
          not necessarily exist on a server, but the namespace name is
          still in the namespace list in order to mark it as reserved.

          A few poorly-designed clients display all namespace names as if
          they were top-level mailboxes in a user's list of mailboxes,
          whether or not they actually exist. This is a flaw in those
          clients.
     _________________________________________________________________

   7.23 Why does my IMAP client show all my files in my home directory?

          As distributed, the IMAP server is connected to your home
          directory by default. It has no way of knowing what you might
          call &quot;mail&quot; as opposed to &quot;some other file&quot;; in fact, you can
          use IMAP to access any file.

          Most clients have an option to configure your connected
          directory on the IMAP server. For example, in Pine you can
          specify this as the &quot;Path&quot; in your folder-collection, e.g.

 Nickname  : Secondary Folders
 Server    : imap.example.com
 Path      : mail/
 View      :

          In this example, the user is connected to the &quot;mail&quot;
          subdirectory of his home directory.

          Other servers call this the &quot;folder prefix&quot; or similar term.

          It is possible to modify the IMAP server so that all users are
          automatically connected to some other directory, e.g. a
          subdirectory of the user's home directory. Read the file CONFIG
          for more details.
     _________________________________________________________________

   7.24 Why is there a long delay before I get connected to the IMAP or
   POP server, no matter what client I use?

          There are two common occurances of this problem:

          + You are running a system (e.g. certain versions of Linux)
            which by default attempts to connect to an &quot;IDENT&quot; protocol
            (port 113) server on your client. However, a firewall or NAT
            box is blocking connections to that port, so the connection
            attempt times out.
            The IDENT protocol is a well-known bad idea that does not
            deliver any real security but causes incredible problems. The
            idea is that this will give the server a record of the user
            name, or at least what some program listening on port 113
            says is the user name. So, if somebody coming from port nnnnn
            on a system does something bad, IDENT may give you the userid
            of the bad guy.
            The problem is, IDENT is only meaningful on a timesharing
            system which has an administrator who is privileged and users
            who are not. It is of no value on a personal system which has
            no separate concept of &quot;system administrator&quot; vs.
            &quot;unprivileged user&quot;.
            On either type of system, security-minded people either turn
            IDENT off or replace it with an IDENT server that lies. Among
            other things, IDENT gives spammers the ability to harvest
            email addresses from anyone who connects to a web page.
            This problem has been showing up quite frequently on systems
            which use xinetd instead of inetd. Look for files named
            /etc/xinetd.conf, /etc/xinetd.d/imapd, /etc/inetd.d/ipop2d,
            and /etc/xinetd.d/ipop3d. In those files, look for lines
            containing &quot;USERID&quot;, e.g.
 log_on_success += USERID
            Hunt down such lines, and delete them ruthlessly from all
            files in which they occur. Don't be shy about it.
          + The DNS is taking a long time to do a reverse DNS (PTR
            record) lookup of the IP address of your client. This is a
            problem in your DNS, which either you or you ISP need to
            resolve. Ideally, the DNS should return the client's name;
            but if it can't it should at least return an error quickly.

          As you may have noticed, neither of these are actual problems
          in the IMAP or POP servers; they are configuration issues with
          either your system or your network infrastructure. If this is
          all new to you, run (don't walk) to the nearest technical
          bookstore and get yourself a good pedagogical text on system
          administration for the type of system you are running.
     _________________________________________________________________

   7.25 Why is there a long delay in Pine or any other c-client based
   application call before I get connected to the IMAP server? The hang
   seems to be in the c-client mail_open() call. I don't have this
   problem with any other IMAP client. There is no delay connecting to a
   POP3 or NNTP server with mail_open().

          By default, the c-client library attempts to make a connection
          through rsh (and ssh, if you enable that). If the command:

 rsh imapserver exec /etc/rimapd

          (or ssh if that is enabled) returns with a &quot;* PREAUTH&quot;
          response, it will use the resulting rsh session as the IMAP
          session and not require an authentication step on the server.

          Unfortunately, rsh has a design error that treats &quot;TCP
          connection refused&quot; as &quot;temporary failure, try again&quot;; it
          expects the &quot;rsh not allowed&quot; case to be implemented as a
          successful connection followed by an error message and close
          the connection.

          It must be emphasized that this is a bug in rsh. It is not a
          bug in the IMAP toolkit.

          The use of rsh can be disabled in any the following ways:

          + You can disable it for this particular session by either:
               o setting an explicit port number in the mailbox name,
                 e.g.
 {imapserver.foo.com:143}INBOX
               o using SSL (the /ssl switch)
          + You can disable rsh globally by setting the rsh timeout value
            to 0 with the call:
 mail_parameters (NIL,SET_RSHTIMEOUT,0);
     _________________________________________________________________

   7.26 Why does a message sometimes get split into two or more messages
   on my SUN system?

          This is caused by an interaction of two independent design
          problems in SUN mail software. The first problem is that the
          &quot;forward message&quot; option in SUN's mail tool program includes
          the internal &quot;From &quot; header line in the text that it forwarded.
          This internal header line is specific to traditional UNIX
          mailbox files and is not suitable for use in forwarded
          messages.

          The second problem is that the mail delivery agent assumes that
          mail reading programs will not use the traditional UNIX mailbox
          format but instead an incompatible variant that depends upon a
          Content-Length: message header. Content-Length is widely
          recognized to have been a terrible mistake, and is no longer
          recommended for use in mail (it is used in other facilities
          that use MIME).

          One symptom of the problem is that under certain circumstances,
          a message may get broken up into several messages. I'm also
          aware of security bugs caused by programs that foolishly trust
          &quot;Content-Length:&quot; headers with evil values.

          To fix the mailer on your system, edit your sendmail.cf to
          change the Mlocal line to have the -E flag. A typical entry
          will lool like:

 Mlocal,        P=/usr/lib/mail.local, F=flsSDFMmnPE, S=10, R=20,
                A=mail.local -d $u

          This fix will also work around the problem with mail tool,
          because it will insert a &quot;&gt;&quot; before the internal header line to
          prevent it from being interpreted by mail reading software as
          an internal header line.
     _________________________________________________________________

   7.27 Why did my POP or IMAP session suddenly disconnect? The syslog
   has the message:
 Autologout user=&lt;...my user name...&gt; host=&lt;...my client system...&gt;

          This is a problem in your client.

          In the case of IMAP, it failed to communicate with the IMAP
          server for over 30 minutes; in the case of POP, it failed to
          communicate with the POP server for over 10 minutes.
     _________________________________________________________________

   7.28 What does the UNIX error message: TLS/SSL failure: myserver: SSL
   negotiation failed mean?
   7.29 What does the PC error message: TLS/SSL failure: myserver:
   Unexpected TCP input disconnect mean?

          This usually means that an attempt to negotiate TLS encryption
          via the STARTTLS command failed, because the server advertises
          STARTTLS functionality, but doesn't actually have it (e.g.
          because no certificates are installed).

          Use the /notls option in the mailbox name to disable TLS
          negotiation.
     _________________________________________________________________

   7.30 What does the error message: TLS/SSL failure: myserver: Server
   name does not match certificate mean?

          An SSL or TLS session encryption failed because the server name
          in the server's certificate does not match the name that you
          gave it. This could indicate that the server is not really the
          system you think that it is, but can be also be called if you
          gave a nickname for the server or name that was not
          fully-qualified. You must use the fully-qualified domain name
          for the server in order to validate its certificate

          Use the /novalidate-cert option in the mailbox name to disable
          validation of the certificate.
     _________________________________________________________________

   7.31 What does the UNIX error message: TLS/SSL failure: myserver:
   self-signed certificate mean?
   7.32 What does the PC error message: TLS/SSL failure: myserver:
   Self-signed certificate or untrusted authority mean?

          An SSL or TLS session encryption failed because your server's
          certificate is &quot;self-signed&quot;; that is, it is not signed by any
          Certificate Authority (CA) and thus can not be validated. A
          CA-signed certificate costs money, and some smaller sites
          either don't want to pay for it or haven't gotten one yet. The
          bad part about this is that this means there is no guarantee
          that the server is really the system you think that it is.

          Use the /novalidate-cert option in the mailbox name to disable
          validation of the certificate.
     _________________________________________________________________

   7.33 What does the UNIX error message: TLS/SSL failure: myserver:
   unable to get local issuer certificate mean?

          An SSL or TLS session encryption failed because your system
          does not have the Certificate Authority (CA) certificates
          installed on OpenSSL's certificates directory. On most systems,
          this directory is /usr/local/ssl/certs). As a result, it is not
          possible to validate the server's certificate.

          If CA certificates are properly installed, you should see
          factory.pem and about a dozen other .pem names such as
          thawteCb.pem.

          As a workaround, you can use the /novalidate-cert option in the
          mailbox name to disable validation of the certificate; however,
          note that you are then vulnerable to various security attacks
          by bad guys.

          The correct fix is to copy all the files from the certs/
          directory in the OpenSSL distribution to the
          /usr/local/ssl/certs (or whatever) directory. Note that you
          need to do this after building OpenSSL, because the OpenSSL
          build creates a number of needed symbolic links. For some
          bizarre reason, the OpenSSL &quot;make install&quot; doesn't do this for
          you, so you must do it manually.
     _________________________________________________________________

   7.34 Why does reading certain messages hang when using Netscape? It
   works fine with Pine!

          There are two possible causes.

          Check the mail syslog. If you see the message &quot;Killed (lost
          mailbox lock)&quot; for the impacted user(s), read the FAQ entry
          regarding that message.

          Check the affected mailbox to see if there are embedded NUL
          characters in the message. NULs in message texts are a
          technical violation of both the message format and IMAP
          specifications. Most clients don't care, but apparently
          Netscape does.

          You can work around this by rebuilding imapd with the
          NETSCAPE_BRAIN_DAMAGE option set (see src/imapd/Makefile); this
          will cause imapd to convert all NULs to 0x80 characters. A
          better solution is to enable the feature in your MTA to
          MIME-convert messages with binary content. See the
          documentation for your MTA for how to do this.
     _________________________________________________________________

   7.35 Why does Netscape say that there's a problem with the IMAP server
   and that I should &quot;Contact your mail server administrator.&quot;?

          Certain versions of Netscape do this when you click the Manage
          Mail button, which uses an undocumented feature of Netscape's
          proprietary IMAP server.

          You can work around this by rebuilding imapd with the
          NETSCAPE_BRAIN_DAMAGE option set (see src/imapd/Makefile) to a
          URL that points either to an alternative IMAP client (e.g.
          Pine) or perhaps to a homebrew mail account management page.
     _________________________________________________________________

   7.36 Why is one user creating huge numbers of IMAP or POP server
   sessions?

          The user is probably using Outlook Express, Eudora, or a
          similar program. See the answer to the Help! My load average is
          soaring and I see hundreds of POP and IMAP servers, many logged
          in as the same user! question.
     _________________________________________________________________

   7.37 Why don't I get any new mail notifications from Outlook Express
   or Outlook after a while?

          This is a known bug in Outlook Express. Microsoft is aware of
          the problem and its cause. They have informed us that they do
          not have any plans to fix it at the present time.

          The problem is also reported in Outlook 2000, but not verified.

          Outlook Express uses the IMAP IDLE command to avoid having to
          &quot;ping&quot; the server every few minutes for new mail.
          Unfortunately, Outlook Express overlooks the part in the IDLE
          specification which requires that a client terminate and
          restart the IDLE before the IMAP 30 minute inactivity
          autologout timer triggers.

          When this happens, Outlook Express displays &quot;Not connected&quot; at
          the bottom of the window. Since it's no longer connected to the
          IMAP server, it isn't going to notice any new mail.

          As soon as the user does anything that would cause an IMAP
          operation, Outlook Express will reconnect and new mail will
          flow again. If the user does something that causes an IMAP
          operation at least every 29 minutes, the problem won't happen.

          Modern versions of imapd attempt to work around the problem by
          automatically reporting fake new mail after 29 minutes. This
          causes Outlook Express to exit the IDLE state; as soon as this
          happens imapd revokes the fake new mail. As long as this
          behavior isn't known to cause problems with other clients, this
          workaround will remain in imapd.
     _________________________________________________________________

   7.38 Why don't I get any new mail notifications from Entourage?

          This is a known bug in Entourage.

          You built an older version of imapd with the
          MICROSOFT_BRAIN_DAMAGE option set, in order to disable support
          for the IDLE command. However, Entourage won't get new mail
          unless IDLE command support exists.

          Note: the MICROSOFT_BRAIN_DAMAGE option no longer exists in
          modern versions, as the Outlook Express problem which it
          attempted to solve has been worked around in another way.
     _________________________________________________________________

   7.39 Why doesn't Entourage work at all?

          It's hard to know. Entourage breaks almost every rule in the
          book for IMAP. It is highly instructive to do a packet trace on
          Entourage, as an example of how not to use IMAP. It does things
          like STATUS (MESSAGES) on the currently selected mailbox and
          re-fetching the same static data over and over again.

          It seems that every time we understand what it is doing wrong
          in Entourage and come up with a workaround, we learn about
          something else that's broken.

          Try building imapd with the ENTOURAGE_BRAIN_DAMAGE option set,
          in order to disable the diagnostic that occurs when doing
          STATUS on the currently selected mailbox.
     _________________________________________________________________

   7.40 Why doesn't Netscape Notify (NSNOTIFY.EXE) work at all?

          This is a bug in NSNOTIFY; it doesn't handle unsolicited data
          from the server correctly.

          Fortunately, there is no reason to use this program with IMAP;
          NSNOTIFY is a polling program to let you know when new mail has
          appeared in your maildrop. This is necessary with POP; but
          since IMAP dynamically announces new mail in the session you're
          better off (and will actually cause less load on the server!)
          keeping your mail reading program's IMAP session open and let
          IMAP do the notifying for you.

          Consequently, the recommended fix for the NSNOTIFY problem is
          to delete the NSNOTIFY binary.
     _________________________________________________________________

   7.41 Why can't I connect via SSL to Eudora? It says the connection has
   been broken, and in the server syslogs I see &quot;Command stream end of
   file&quot;.

          There is a report that you can fix the problem by going into
          Eudora's advanced network configuration menu and increasing the
          network buffer size to 8192.
     _________________________________________________________________

   7.42 Sheesh. Aren't there any good IMAP clients out there?

          Yes!

          Pine is a wonderful client. It's fast, it uses IMAP well, and
          it generates text mail (life is too short to waste on HTML
          mail). Also, there are some really wonderful things in progress
          in the Pine world.

          There are some good GUI clients out there, mostly from smaller
          vendors. Without naming names, look for the vendors who are
          active in the IMAP protocol development community, and their
          products.

          Netscape, Eudora, and Outlook can be configured with enough
          effort to be good citizens and work well for users, but they
          can also be badly misconfigured, and often the misconfiguration
          is the default.
     _________________________________________________________________

   7.43 But wait! PC Pine (or other PC program build with c-client)
   crashes with the message incomplete SecBuffer exceeds maximum buffer
   size when I use SSL connections. This is a bug in c-client, right?

          It's a bug in the Microsoft SChannel.DLL, which implements SSL.
          Microsoft admits it (albeit with an unstatement: &quot;it's not
          fully RFC compliant&quot;). The problem is that SChannel indicates
          that the maximum SSL packet data size is 5 bytes smaller than
          the actual maximum. Thus, any IMAP server which transmits a
          maximum sized SSL packet will not work with PC Pine or any
          other program which uses SChannel.

          It can take a while for the problem to show up. The client has
          to do something that causes at least 16K of contiguous data.
          Many clients do partial fetching, which tends to reduce the
          number of cases where this can happen. However, all software
          which uses SChannel to support SSL is affected by this bug.

          This problem does not affect UNIX code, since OpenSSL is used
          on UNIX.

          This problem most recently showed up with the CommunigatePro
          IMAP server. They have an update which trims down their maximum
          contiguous data to less than 16K, in order to work around the
          problem.

          This problem has also shown up with the Exchange IMAP server
          with UNIX clients (including Pine built with an older version
          of c-client) which sends full-sized 16K SSL packets. Modern
          c-client works around the problem by trimming down its maximum
          outgoing SSL packet size to 8K.

          Microsoft has developed a hotfix for this bug. Look up MSKB
          article number 300562. Contrary to the article text which
          implies that this is a Pine issue, this bug also affect
          Microsoft Exchange server with *any* UNIX based client that
          transmits full-sized SSL payloads.
     _________________________________________________________________

   7.44 My qpopper users keep on getting the DON'T DELETE THIS MESSAGE --
   FOLDER INTERNAL DATA if they also use Pine or IMAP. How can I fix
   this?

          This is an incompatibility between qpopper and the c-client
          library used by Pine, imapd, and ipop[23]d.

          Assuming that you want to continue using qpopper, look into
          qpopper's --enable-uw-kludge-flag configuration flag, which is
          documented as &quot;check for and hide UW 'Folder Internal Data'
          messages&quot;.

          The other alternative is to switch from qpopper to ipop3d.
     _________________________________________________________________

   7.45 Help! I installed the servers but I can't connect to them from my
   client!

          Review the installation instructions carefully. Make sure that
          you have not skipped any of the steps. Make sure that you have
          made the correct entries in the configuration files; pay
          careful attention to the exact spelling of the service names
          and the path names. Make sure as well that you have properly
          restarted inetd.

          If you have a system with Yellow Pages/NIS such as Solaris,
          have you updated the service names there as well as in
          /etc/services?

          If you have a system with TCP wrappers, have you properly
          updated the TCP wrapper files (e.g. /etc/hosts.allow and
          /etc/hosts.deny) for the servers?

          If you have a system which uses xinetd instead of inetd, have
          you made sure that you have made the correct corresponding
          xinetd changes for those services?

          Try telneting to the server port (143 for IMAP, 110 for POP3).
          If you get a &quot;refused&quot; error, that probably means that you
          don't have the service set up in inetd.conf. If the connection
          opens and then closes with no message, the service is set up,
          but either the path name of the server binary in inetd.conf is
          wrong or your TCP wrappers are configured to deny access.

          If you don't know how to make the corresponding changes to
          these files, seek the help of a local expert for your system.
     _________________________________________________________________

   7.46 Why do I get the message Can not authenticate to SMTP server: 421
   SMTP connection went away! and why did this happen? There was also
   something about SECURITY PROBLEM: insecure server advertised
   AUTH=PLAIN

          Some versions of qmail, including that running on
          mail.smtp.yahoo.com, disconnect the SMTP session if you fail to
          authenticate prior to attempting to transmit mail. An attempt
          to authenticate was made, but it failed because the server had
          already disconnected.

          To work around this, you need to specify /user=... in the host
          name specification.

          The SECURITY PROBLEM came about because the server advertised
          the AUTH=PLAIN SASL authentication mechanism outside of a
          TLS-encrypted session, in violation of RFC 4616. This message
          is just a warning, and in fact occurred after the server had
          disconnected.
     _________________________________________________________________

   7.47 Why do I get the message SMTP Authentication cancelled and why
   did this happen? There was also something about SECURITY PROBLEM:
   insecure server advertised AUTH=PLAIN

          This is a bug in the SMTP server.

          Some versions of qmail, including that running on
          mail.smtp.yahoo.com, have a bug in their implementation of SASL
          in their SMTP server, which renders it non-compliant with the
          standard.

          If the client does not provide an initial response in the
          command line for an authentication mechanism whose profile does
          not have an initial challenge, qmail issues a bogus response:

 334 ok, go on

          The problem is the &quot;ok, go on&quot;. This violates RFC 4954's
          requirement that the text part in a 334 response be a BASE64
          encoded string; in other words, it is a protocol syntax error.

          In the case of AUTH=PLAIN, RFC 4422 (page 7) requires that the
          encoded string have no data. In other words, the appropropiate
          standards-compliant server response is &quot;334&quot; followed by a
          SPACE and a CRLF.

          The SECURITY PROBLEM came about because the server advertised
          the AUTH=PLAIN SASL authentication mechanism outside of a
          TLS-encrypted session, in violation of RFC 4616. This message
          is just a warning, and is not related the &quot;Authentication
          cancelled&quot; problem.
     _________________________________________________________________

   7.48 Why do I get the message Invalid base64 string when I try to
   authenticate to a Cyrus server?

          This slightly misleading message is the way that a Cyrus server
          indicates that an authentication exchange was cancelled. It is
          not indicative of a bug or protocol violation.

          The most common reason that this happens is if the Cyrus server
          offers Kerberos authentication, c-client is built with Kerberos
          support, but your client system is not within the Kerberos
          realm. In this case, the client code will try to authenticate
          via Kerberos, fail to get the Kerberos credentials, cancel the
          authentication attempt, and try the next available
          authentication technology.
     _________________________________________________________________

8. Where to Go For Additional Information
     _________________________________________________________________

   8.1 Where can I go to ask questions?
   8.2 I have some ideas for enhancements to IMAP. Where should I go?

          If you have questions about the IMAP protocol, or want to
          participate in discussions of future directions of the IMAP
          protocol, the appropriate mailing list is
          imap-protocol@u.washington.edu. You can subscribe to this
          list via imap-protocol-request@u.washington.edu

          If you have questions about this software, you can send me
          email directly or use the imap-uw@u.washington.edu mailing
          list. You can subscribe to this list via
          imap-uw-request@u.washington.edu

          If you have general questions about the use of IMAP software
          (not specific to the UW IMAP toolkit) use the
          imap-use@u.washington.edu mailing list. You can subscribe to
          this list via imap-use-request@u.washington.edu

          You must be a subscriber to post to these lists.  As an
          alternative, you can use the comp.mail.imap newsgroup.
          _________________________________________________________________

   8.3 Where can I read more about IMAP and other email protocols?

          We recommend Internet Email Protocols: A Developer's Guide, by
          Kevin Johnson, published by Addison Wesley, ISBN 0-201-43288-9.
     _________________________________________________________________

   8.4 Where can I find out more about setting up and administering an
   IMAP server?

          We recommend Managing IMAP, by Dianna Mullet &amp; Kevin Mullet,
          published by O'Reilly, ISBN 0-596-00012-X.

          This book also has an excellent comparison of the UW and Cyrus
          IMAP servers.

   Last Updated: 15 November 2007
                                                                                md5.txt                                                                                             0000644                 00000007310 15051750507 0006000 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       /* ========================================================================
 * Copyright 1988-2006 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
 * 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
 *
 * 
 * ========================================================================
 */

		       MD5 Based Authentication
			     Mark Crispin
			   1 November 1999


     The IMAP toolkit makes available two MD5 based authentication
mechanisms, CRAM-MD5 and APOP.  CRAM-MD5 is described in RFC 2195, and
is a SASL (RFC 2222) authentication mechanism.  APOP is described in
RFC 1939, the standard document for the POP3 protocol.

     These mechanisms use the same general idea.  The server issues a
challenge; the client responds with an MD5 checksum of the challenge
plus the password; the server in compares the client's response with
its own calculated value of the checksum.  If the client's response
matches the server's calulated value, the client is authenticated.

     Unlike plaintext passwords, this form of authentication is
believed to be secure against the session being monitored; &quot;sniffing&quot;
the session will not disclose the password nor will it provide usable
information to authenticate in another session without knowing the
password.

     The key disadvantage with this form of authentication is that the
server must know a plaintext form of the password.  In traditional
UNIX authentication, the server only knows an encrypted form of the
password.  Consequently, the authentication database for this form of
authentication must be kept strictly confidential; a bad guy who
acquires access to this database can access any account in the
database.

     CRAM-MD5 client support is implemented unconditionally; any
client application built with the IMAP toolkit will use CRAM-MD5 with
any server which advertises CRAM-MD5 SASL support.

     CRAM-MD5 and APOP server support is implemented if, and only if,
the CRAM-MD5 authentication database exists.  By default, the CRAM-MD5
authentication database is in a UNIX file called
	/etc/cram-md5.pwd
It is recommended that this file be protected 0400.

	NOTE: FAILURE TO PROTECT THIS FILE AGAINST UNAUTHORIZED
	ACCESS WILL COMPROMSE CRAM-MD5 AND APOP AUTHENTICATION
	FOR ALL USERS LISTED IN THIS DATABASE.

     If the CRAM-MD5 authentication database exists, then plaintext
password authentication (e.g. the LOGIN command) will also use the
CRAM-MD5 passwords instead of UNIX passwords.  Alternatively, it is
possible to build the IMAP toolkit so that plaintext password
authentication is disabled entirely, by using PASSWDTYPE=nul, e.g.
	make aix PASSWDTYPE=nul


     The CRAM-MD5 authentication database file consists of a series of
text lines, consisting of a UNIX user name, a single tab, and the
password.  A line starting with a &quot;#&quot; character is ignored, as are any
lines which are not in valid format.  For example:

------------------------------Sample------------------------------
# CRAM-MD5 authentication database
# Entries are in form &lt;user&gt;&lt;tab&gt;&lt;password&gt;
# Lines starting with &quot;#&quot; are comments

bill	hubba-hubba
hillary	nysenator
monica	beret
tripp	wired
kenstarr	inquisitor
reno	waco
jessie	thebody
billgates	ruleworld
------------------------------Sample------------------------------

     Every entry in the CRAM-MD5 authentication database must have a
corresponding entry in the /etc/passwd file.  It is STRONGLY
RECOMMENDED that the CRAM-MD5 password NOT be the same as the
/etc/passwd password.  It is permitted for the /etc/passwd password to
be disabled; /etc/passwd is just used to get the UID, GID, and home
directory information.
                                                                                                                                                                                                                                                                                                                        internal.txt                                                                                        0000644                 00000340601 15051750507 0007132 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       /* ========================================================================
 * Copyright 1988-2006 University of Washington
 *
 * Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
 * 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
 *
 * 
 * ========================================================================
 */

	  Documentation of c-client Functions and Interfaces

REVISED: 19 August 1996

				  Credits

     The original version of this document was written by Mark Crispin at
the University of Washington, and described the version of c-client that
supported the IMAP2 (RFC 1176) and IMAP2bis (unpublished) protocols.

     This version is a substantial rewrite of that document, and was
written by Mark Crispin with funding from Sun Microsystems, Incorporated.
Sun's generous support of this work is gratefully acknowledged.


				 Road Map

     This document is organized into the following sections.  Except as
noted, an implementor of an application that uses c-client needs to be
familiar with all of these sections.  Someone who plans to write a new
mailbox driver for c-client (or otherwise modify it) needs to be familiar
with all sections, no exception.

History
	History of how c-client came about.

Overview
	Read this before designing an application that uses c-client.

c-client Structures
	Documentation of several important c-client structs which are
	used in, and returned by, c-client calls.

String Structures
	Documentation of the concept of a &quot;string structure&quot;, which
	provides random access to strings without requiring that the
	string be in memory.

c-client Support Functions
	Documentation of support functions for c-client; these deal
	with c-client functionality.

	Only mail_parameters() is of interest to most application
	developers.  Advanced application developers, particularly
	for limited memory systems, may also need to know about the
	readfn_t, mailgets_t, mailcache_t, and tcptimeout_t function
	pointer types, and possibly also the mail_valid_net_parse()
	function.

Mailbox Access Functions
	Documentation of functions which deal with mailboxes;
	listing, subscribing, creating, deleting, renaming, status
	inquiries, opening, and closing mailboxes.

Handle Functions
	Documentation of mail stream handles, which provide protection
	for an advanced application which may have multiple pointers to
	a single mail stream.  If a stream has a handle on it, closing
	the stream does not release its memory, so pointers to it in
	the application remain valid.  Freeing the last handle will free
	the entire stream.

	This is only of interest for advanced application developers.

Message Data Fetching Functions
	Documentation on message data fetching in an open mailbox,
	including parsed representations of RFC-822 and MIME headers
	and message text.  Also how to fetch message attributes (flags,
	internal date, sizes).

Message Status Manipulation Functions
	Documentation on altering message flags in an open mailbox.

Mailbox Searching
	Documentation on searching an open mailbox for messages which
	match certain criteria (e.g. &quot;messages sent July 4 from Jones
	with text `Paris'&quot;).

Miscellaneous Mailbox and Message Functions
	Documentation on other operations that would be used by an
	application but that don't fit into any of the above categories.

Date/Time Handling Functions
	Documentation on functions that deal with date/time strings.

	This is only of interest for advanced application developers
	and for implementors of new c-client drivers.

Utility Functions
	Documentation on internal utility functions.

	This is primarily of interest for implementors of new c-client
	drivers, but advanced application developers may also use some
	of these functions.

Data Structure Instantiation/Destruction functions
	Documentation on creating and destroy c-client structures.

	This is primarily of interest for implementors of new c-client
	drivers.  However, application developers will need some of
	these functions to create and destroy structures which are used
	as arguments to various application functions.

Authentication Functions
	Documentation on support for network protocol authentication
	functions.

	This is only of interest for implementors of new c-client
	drivers which deal with authentication mechanisms.

Network Access Functions
	Documentation on creating and destroy c-client structures.

	This is primarily of interest for implementors of new c-client
	drivers which deal with a network.  However, advanced
	application developers may need to use this information if they
	wish to insert their own layer into a network session.

Subscription Management Functions
	Documentation on managing the local (client-based) subscription
	database file.

	This is primarily of interest to advanced application developers.

Miscellaneous Utility Functions
	Documentation on various useful utility functions, such as &quot;make
	a copy of this string.&quot;

SMTP Functions
	Documentation on posting email messages via SMTP protocol.

NNTP Functions
	Documentation on posting netnews messages via NNTP protocol.

RFC 822 Support Functions
	Documentation on public RFC-822/MIME functions.

	This is primarily of interest for implementors of new c-client
	drivers and advanced application developers.

Operating System-Dependent Public Interface
	Documentation on OS-dependent functions.  With the exception of
	fs_get(), fs_give(), and fs_resize(), which should be called
	instead of malloc(), free(), and realloc(), these functions are
	primarily of interest for implementors of new c-client drivers.

Main Program Callbacks
	Documentation of functions which the main program must provide
	as callbacks from c-client.

Driver Interface
	Documentation of the driver dispatch vector and the functions
	which a driver must supply.

	This is primarily of interest for implementors of new c-client
	drivers.

Driver Support Functions
	Documentation of support functions which are called by drivers.

	This is primarily of interest for implementors of new c-client
	drivers.
				  History

     The c-client API was originally written by Mark Crispin at Stanford
University as a set of routines to support IMAP and SMTP from a main
program which would handle the user interface.  In its original form, it
was written as the low-level routines that were to be used as part of a
Macintosh client.

     The first IMAP client, MM-D (for &quot;MM on Xerox D machines&quot; -- MM was a
popular DEC-20 mail program) was written in Interlisp for Xerox Lisp
machines.  At that time, there was no name for the embryonic Mac client,
but since it was the first one to be written in C instead of Lisp, it was
given a development name of &quot;C client&quot;.  This name became &quot;c-client&quot;
because that is the name of the subdirectory on UNIX where the source files
were stored.

     To exercise the routines, a minimal main program which uses c-client,
mtest, was written.  mtest has subsequently been extended so that it runs
on every platform that c-client is ported.

     The real Mac client, was eventually written by Frank Gilmurrary and
Bill Yeager at Stanford using the autumn 1988 version of c-client and named
&quot;MacMS&quot;.  In the winter of 1988-89, Mark Crispin, who had changed jobs to
the University of Washington, developed MS as an MM-like text-based program
for UNIX and MailManager as a GUI-based program for NeXT machines.

     The realization sunk in that this API needed its own name.  As early
as spring 1989, there were at least four programs (mtest, MS, MailManager,
and MacMS) that used it.  The name c-client thus became permanent.

     In its history, c-client has undergone two major redesigns, both by
Mark Crispin who is now on the staff at the University of Washington.

     The first major redesign added the following:
	1) ANSI C calling conventions throughout to assist in function
	   argument type checking.
	2) Vectoring mail access calls through &quot;driver&quot; methods; thus
	   providing transparent access to multiple types of mail
	   stores with the same call.
	3) MIME support.

     The second major redesign was part of the IMAP4 project.  Many
c-client functions were extended with additional arguments and options.
The driver interface was also made simpler, with more work done by
driver-independent code.

			       Overview

     The most important file for the author of an application using the
c-client is mail.h.  mail.h defines several important structures of
data which are passed between the main program and the c-client.
Although some functions (e.g. mail_fetchtext_body()) return the data
fetched, for certain other data items (e.g. flags) you need to get the
data as a structure reference.  mail.h also defines a large number of
useful constants and structures.

     When a function in mail.h exists to reference data, it MUST be
used instead of referencing the structures directly.  This is because
in some cases the data is not actually fetched until a reference (via
the function call) is made.  For example, although the MESSAGECACHE
element for a message can be obtained by indexing the proper cache
element in the stream, there is no guarantee that the item in fact
exists unless mail_fetchstructure_full() is called for that message.
Less costly functions. also exist to create and load a MESSAGECACHE
element.

     The main program will probably also need to include smtp.h,
misc.h, and osdep.h, but this usage should be solely to receive
function prototypes.  Any other definitions in those files should be
considered private to that module.

     Two important predefined symbols are NIL and T.  NIL is any sort
of &quot;false&quot;; T is any sort of &quot;true&quot;.  NIL is also used to null-specify
certain optional arguments.

			* * * IMPORTANT * * *

     Any multi-threaded application should test stream-&gt;lock prior to
calling any c-client stream functions.  Any attempt to call a
mail_xxx() function while one is already in progress on the same
stream will cause the application to fail in unpredictable ways.

     Note that this check is insufficient in a preemptive-scheduling
multi-tasking application due to the possibility of a timing race.
Such applications must be written so that only one process accesses
the stream, or to have a higher level lock.

     Since MAIL operations will not finish until they are completed, a
single-tasking application does not have to worry about this problem,
except in the callback invoked from MAIL (e.g. mm_exists(), etc.) in which
case the stream is *always* locked.

			  c-client Structures

     c-client has a large number of structures which are used for
multiple functions.  The most important of these are described here.

     The MAILSTREAM structure is used to reference open mailboxes.
Applications may reference the following:

char *mailbox;			mailbox name
unsigned short use;		stream use count, this is incremented
unsigned short sequence;	stream sequence, this is incremented
				 each time a stream is reused (i.e.
				 mail_open() is called to open a
				 different mailbox on this stream)
unsigned int rdonly : 1;	stream is open read-only
unsigned int anonymous : 1;	stream is open with anonymous access
unsigned int halfopen : 1;	stream is half-open; it can be
				 reopened or used for functions that
				 don't need a open mailbox such as
				 mail_create() but no message data
				 can be fetched
unsigned int perm_seen : 1;	Seen flag can be set permanently
unsigned int perm_deleted : 1;	Deleted flag can be set permanently
unsigned int perm_flagged : 1;	Flagged flag can be set permanently
unsigned int perm_answered :1;	Answered flag can be set permanently
unsigned int perm_draft : 1;	Draft flag can be set permanently
unsigned int kwd_create : 1;	new user flags can be created by
				 referencing then in mail_setflag() or
				 mail_clearflag().  Note: this can
				 change during a session (e.g. if
				 there is a limit on the number of
				 keywords), so check after creating a
				 new flag to see if any more can be
				 created before letting the user try
				 to do so
unsigned long perm_user_flags;	corresponding user flags can be set
				 permanently.  This is a bit mask
				 which matches the entries in
				 stream-&gt;user_flags[]
unsigned long gensym;		generated unique value.  Always
				 referenced with stream-&gt;gensys++
unsigned long nmsgs;		number of messages in current mailbox
unsigned long recent;		number of recent messages in current
				 mailbox
unsigned long uid_validity;	UID validity value; this is used to
				 verify that recorded UIDs match the
				 UIDs that the stream has.  If the
				 mailbox does not have matching UIDs
				 (e.g. the UIDs were lost or not
				 recorded) then the UID validity value
				 will be different
unsigned long uid_last;		highest currently assigned UID in the
				 current mailbox; a new UID will be
				 assigned with ++stream-&gt;uid_last
char *user_flags[NUSERFLAGS];	pointers to user flag names in bit
				 order from stream-&gt;perm_user_flags or
				 elt-&gt;user_flags

     The following MAILSTREAM values are only used internally:

DRIVER *dtb;			dispatch table for this driver
void *local;			pointer to driver local data
unsigned int lock : 1;		stream lock flag (an operation is in
				 progress; used as a bug trap to
				 detect recursion back to c-client
				 from callback routines).
unsigned int debug : 1;		debugging information should be logged
				 via mm_dlog().
unsigned int silent : 1;	don't do main program callbacks on
				 this stream (used when a stream is
				 opened internally)
unsigned int scache : 1;	short caching; don't cache information
				 in memory

     The following MAILSTREAM values are only used by the cache
manager routine (see the documentation about mailcache_t above):

unsigned long cachesize;	size of c-client message cache
union {
  void **c;			to get at the cache in general
  MESSAGECACHE **s;		message cache array
  LONGCACHE **l;		long cache array
} cache;

     The following MAILSTREAM values are for the convenience of
drivers that use short caching and want to be able to garbage collect
any values that they returned:

unsigned long msgno;		message number of `current' message
ENVELOPE *env;			pointer to `current' message envelope
BODY *body;			pointer to `current' message body
char *text;			pointer to `current' text


     The MESSAGECACHE structure (commonly called an &quot;elt&quot; as a
nickname for &quot;cache ELemenT&quot;) contains information about messages.
Applications may use the following:

unsigned long msgno;		message number.  If the elt is locked
				 (by elt-&gt;lockcount++), then the elt
				 pointer can be stored (e.g. with the
				 data for a window which draws this
				 message) and elt-&gt;msgno will change
				 automatically whenever expunges are
				 done so the window will always view
				 the correct message.  If elt-&gt;msgno
				 becomes 0, then the message has been
				 expunged, but the elt won't be freed
				 until the elt lock count is
				 decremented (by mail_free_elt()).
unsigned long uid;		message unique ID
unsigned int hours: 5;		internal date hours (0-23)
unsigned int minutes: 6;	internal date minutes (0-59)
unsigned int seconds: 6;	internal date seconds (0-59)
unsigned int zoccident : 1;	non-zero if internal date time zone is
				 west of UTC
unsigned int zhours : 4;	internal date time zone hours from UTC
				 (0-12)
unsigned int zminutes: 6;	internal date time zone minutes (0-59)
unsigned int seen : 1;		message Seen flag
unsigned int deleted : 1;	message Deleted flag
unsigned int flagged : 1; 	message Flagged flag
unsigned int answered : 1;	message Answered glag
unsigned int draft : 1;		message Draft flag
unsigned int valid : 1;		flags are valid in this elt; an elt
				 that was newly created but never
				 loaded with flags won't have this set.
unsigned int recent : 1;	message recent flag
unsigned int searched : 1;	message matches search criteria in
				 most recent mail_search_full() call
unsigned int spare : 1;		reserved for application use
unsigned int spare2 : 1;	reserved for application use
unsigned int spare3 : 1;	reserved for application use
unsigned int lockcount : 8;	non-zero if multiple references to
				 this elt.  Refer to the msgno member
				 for more information.
unsigned int day : 5;		internal date day of month (1-31)
unsigned int month : 4;		internal date month of year (1-12)
unsigned int year : 7;		internal date year since BASEYEAR
				 (currently 1970; was 1969 in older
				 versions so use BASEYEAR instead of
				 having the base year wired in)
unsigned long user_flags;	message user flags; this is a bit mask
				 which matches the entries in
				 stream-&gt;user_flags[]
unsigned long rfc822_size;	size of message in octets

     The following MESSAGECACHE values are only used internally by
drivers:

unsigned int sequence : 1;	message is in sequence from either
				 mail_sequence() or mail_uid_sequence()
unsigned long data1;		first data item
unsigned long data2;		second data item
unsigned long data3;		third data item
unsigned long data4;		fourth data item


     The ADDRESS structure is a parsed form of a linked list of RFC 822
addresses.  It contains the following information:

char *personal;			personal name phrase
char *adl;			at-domain-list (also called &quot;source
				 route&quot;)
char *mailbox;			mailbox name
char *host;			domain name of mailbox's host
char *error;			error in address from smtp_mail(); if
				 an error is returned from smtp_mail()
				 for one of the recipient addresses
				 the SMTP server's error text for that
				 recipient can be found here.  If it
				 is null then there was no error (or
				 an error was found with a prior
				 recipient
ADDRESS *next;			pointer to next address in list


     The ENVELOPE structure is a parsed form of the RFC 822 header.
Its member names correspond to the RFC 822 field names.  It contains
the following information:

char *remail;			remail header if any
ADDRESS *return_path;		error return address
char *date;			message composition date string
ADDRESS *from;			from address list
ADDRESS *sender;		sender address list
ADDRESS *reply_to;		reply address list
char *subject;			message subject string
ADDRESS *to;			primary recipient list
ADDRESS *cc;			secondary recipient list
ADDRESS *bcc;			blind secondary recipient list
char *in_reply_to;		replied message ID
char *message_id;		message ID
char *newsgroups;		USENET newsgroups
char *followup_to;		USENET reply newsgroups
char *references;		USENET references


     The BODY structure is a parsed form of a linked list of the MIME
structure of a message.  It contains the following information.

unsigned short type;		body primary type code.  This is an
				 index into the body_types vector of
				 body type names.  The following body
				 types are pre-defined:
	TYPETEXT		unformatted text
	TYPEMULTIPART		multiple part
	TYPEMESSAGE		encapsulated message
	TYPEAPPLICATION		application data
	TYPEAUDIO		audio
	TYPEIMAGE		static image (GIF, JPEG, etc.)
	TYPEVIDEO		video
	TYPEOTHER		unknown
				Additional types up to TYPEMAX are
				 dynamically defined if they are
				 encountered by c-client.
unsigned short encoding;	body transfer encoding.  This is an
				 index into the body_encodings vector
				 of body encoding names.  The
				 following body encodings are
				 pre-defined:
	ENC7BIT			7 bit SMTP semantic data
	ENC8BIT			8 bit SMTP semantic data
	ENCBINARY		8 bit binary data
	ENCBASE64		base-64 encoded data
	ENCQUOTEDPRINTABLE	human-readable 8-as-7 bit data
	ENCOTHER		unknown
				Additional encodings up to ENCMAX are
				 dynamically defined if they are
				 encountered by c-client.
char *subtype;			body subtype string
PARAMETER *parameter;		parameter list
char *id;			body content identifier
char *description;		body content description
unsigned char *contents.text;	when composing a message that is NOT
				 of TYPEMULTIPART, non-binary text of
				 the content is stored here.  Note that
				 this happens even when the text is
				 of TYPEMESSAGE.  Text of encoding
				 ENC8BIT may be converted to
				 ENCQUOTEDPRINTABLE when it is sent.
				 This should not be referenced for any
				 other reason; in particular, this is
				 NOT the way for an application to
				 access content data (use
				 mail_fetchbody_full() instead).
BINARY *contents.binary;	when composing a message that is NOT
				 of TYPEMULTIPART, binary content (of
				 encoding ENCBINARY) is stored here.
				 It will be converted to ENCBASE64 when
				 it is sent.
				 This should not be referenced for any
				 other reason; in particular, this is
				 NOT the way for an application to
				 access content data (use
				 mail_fetchbody_full() instead).
PART *contents.part;		for body parts of TYPEMULTIPART, this
				 contains the list of body parts in
				 this multipart
MESSAGE contents.msg;		for body parts of TYPEMESSAGE with
				 subtype &quot;RFC822&quot;, this contains the
				 encapsulated message
unsigned long size.lines;	size in lines
unsigned long size.bytes;	size in octets.  This MUST be set when
				composing a message if the encoding is
				ENC8BIT or ENCBINARY.
char *md5;			body content MD5 checksum

     The following BODY information is used only by c-client
internally.  The use of this data is driver-specific and it can not be
relied-upon by applications.

unsigned char *contents.text;	drivers can store a pointer to the
				 body contents as text here.		
unsigned long size.ibytes;	internal size of the body content (prior
				 to newline conversion, etc.) in octets


     The MESSAGE structure is a parsed form of a MESSAGE/RFC822 MIME
body part.  It contains the following information:

ENVELOPE *env;			encapsulated message RFC 822 header
BODY *body;			encapsulated message MIME structure

     The following MESSAGE information is used only by c-client
internally.  The use of this data is driver-specific and it can not be
relied-upon by applications.

char *hdr;			encapsulated message header
unsigned long hdrsize;		message header size
char *text;			message in RFC 822 form
unsigned long offset;		offset of text from header


     The PARAMETER structure is a parsed form of a linked list of
attribute/value pairs.  It contains the following information:

char *attribute;		attribute name
char *value;			value
PARAMETER *next;		next parameter in list


     The PART structure is a parsed form of a linked list of MIME body
parts.  It contains the following information:

BODY body;			body information for this part
PART *next;			next body part

     The following PART information is used only by c-client
internally.  The use of this data is driver-specific and it can not be
relied-upon by applications.

unsigned long offset;		offset from body origin


    The NETMBX structure is a parsed form of a network mailbox name:

char host[NETMAXHOST];		remote host name
char user[NETMAXUSER];		remote user name if specified
char mailbox[NETMAXMBX];	remote mailbox name
char service[NETMAXSRV];	remote service name (IMAP4, NNTP, etc.)
unsigned long port;		TCP/IP port number if specified
unsigned int anoflag : 1;	anonymous access requested
unsigned int dbgflag : 1;	protocol debugging telemetry, via
				 mm_dlog(), requested


     The STRINGLIST structure is a list of strings (which may have
embedded NULs) and their lengths:

char *text;			string text
unsigned long size;		string length
STRINGLIST *next;		next string in list

			  String Structures

     A string structure is analogous to a char*, and is used in some
functions as an input argument.  It represents a string of data in a
way that does not necessarily require the entire string to be in
memory at once.  This is essential for small machines with
highly-restricted memory limits (e.g. DOS).

		       String Structure Access

     To use a string structure, the caller needs to know a string
driver and needs to know the driver-dependent data used by that string
structure.  A simple string driver is mail_string, a string driver
that takes an in-memory char* string as the driver-dependent data.
The DOS port uses string drivers that take a struct holding a file
descriptor and a file offset.  Often the user of a string driver is
the same module that defined it, so usually the programmer knows about
its conventions.

     The following calls are used to access a string structure:

void INIT (STRING *s,STRINGDRIVER *d,void *data,unsigned long size);
	s	pointer to the string structure to be initialized
	d	pointer to the string driver
	data	pointer to driver-dependent data, from which the
		 driver can determine string data
	size	size of the string
 This call initializes the string stucture.


unsigned long SIZE (STRING *s);
	s	pointer to the string structure
 This call returns the number of characters remaining in the string
after the current string character pointer.


char CHR (STRING *s);
	s	pointer to the string structure
 This call returns the character at the current string character
pointer.


char SNX (STRING *s);
	s	pointer to the string structure
 This call returns the character at the current string character
pointer, and increments the string character pointer.


unsigned long GETPOS (STRING *s);
	s	pointer to the string structure
 This returns the value of the current string character pointer.


void SETPOS (STRING *s,unsigned long i);
	s	pointer to the string structure
	i	new string pointer value
 This method sets the string character pointer to the given value.


		      String Structure Internals

     A string structure holds the following data:

void *data;		used by the string driver as it likes
unsigned long data1;	used by the string driver as it likes
unsigned long size;	static, holds the total length of the string
			 from the INIT call
char *chunk;		current chunk of in-memory data; this is used
			 for buffering to avoid unnecessary calls to
			 the string driver's next method.
unsigned long chunksize; size of an in-memory data chunk
unsigned long offset;	position of first character of the chunk in
			 the overall string
char *curpos;		current position; this is what CHR() will
			 access
unsigned long cursize;	number of characters remaining in the current
			 string
STRINGDRIVER *dtb;	the string driver for this string structure


     A string structure is manipulated by a string driver, which has
the following access methods:

void (*init) (STRING *s,void *data,unsigned long size);
	s	pointer to the string structure to be initialized
	data	pointer to driver-dependent data, from which the
		 driver can determine string data
	size	size of the string
 This method initializes the string stucture.  It can use the data,
data1, and chunksize values as it likes.  The remaining values must be
set up as follows:
	size		static, copied from the size argument
	chunk		pointer to a buffer loaded with initial data
	chunksize	size of the buffer
	offset		0
	curpos		copied from chunk
	cursize		copied from chunksize
	dtb		STRINGDRIVER identity pointer


char (*next) (STRING *s);
	s	pointer to the string structure
 This method returns the character at the current string character
pointer, and increments the string character pointer.  This method
is likely to call the setpos method if the desired character is not in
the current chunk.


void (*setpos) (STRING *s,unsigned long i);
	s	pointer to the string structure
	i	new string pointer value
 This method sets the string character pointer to the given value.  If
the pointer is not in the current chunk, then a new chunk is loaded
and the associated values (chunk, offset, curpos, cursize) are
adjusted accordingly.

		      c-client Support Functions


void mail_string_init (STRING *s,void *data,unsigned long size);
char mail_string_next (STRING *s);
void mail_string_setpos (STRING *s,unsigned long i);

     These three functions are the init, next, and setpos string
structure access methods for the build-in mail_string string driver.
mail_string is a basic string driver for a char* string.  See the
documentation below on &quot;String Structures&quot; for more information.


void mail_link (DRIVER *driver);
	driver	pointer to the driver to be added

     This function adds the specified driver to the list of mailbox
drivers.  Initially there are no drivers lunk, so all programs which
intend to use c-client need to have at least one call to this function.

     A function which uses IMAP4 would have a statement such as:
	mail_link (&amp;imapdriver);	/* link in IMAP driver */
early in the program's initialization.  Normally, this is done by the
statement
	#include &quot;linkage.c&quot;
which will include the &quot;system standard driver linkage&quot; defined when
c-client was built.  By using linkage.c instead of explicit mail_link()
calls, you are guaranteed that you will have a consistant linkage among
all software built on this system.


void auth_link (AUTHENTICATOR *auth);
	auth	pointer to the authenticator to be added

     This function adds the specified authenticator to the list of
authenticators.  Initially there are no authenticators lunk.  Normally,
this is done by linkage.c so you don't need to call this routine
explicitly.


void *mail_parameters (MAILSTREAM *stream,long function,void *value);
	stream	stream to poll or NIL
	function function code
	value	new value for function codes that change a parameter

     This function fetches or changes the settings of various c-client
operational parameters depending upon the function.  If the stream is
specified, only the action for the underlying driver for that stream is
taken; however, the scope of the operational parameters is global so
there is generally no reason for the stream argument ever to be
non-NIL.

     The function codes ENABLE_DRIVER and DISABLE_DRIVER take a driver
pointer as a value.  These functions enable and disable mailbox
processing by that driver.  By default, all drivers are enabled.

     The remaining function codes are in a pair named GET_xxx to
fetch an operational parameter and SET_xxx to set the parameter:

 GET_DRIVERS / SET_DRIVERS
	 The list of currently lunk drivers.

 GET_GETS / SET_GETS
	 If non-NIL, points to a function for reading message text.
	Defaults to NIL.
	 This function is called with three arguments; a function
	pointer to a &quot;reading function&quot;, a stream for the reading
	function, and a size in octets.  The reading function is
	in turn called with the stream, a size in octets, and a
	pointer to a readin buffer.
	 This function returns with a char* string, which will be
	returned by the mail_fetchheader(), mail_fetchtext(), or
	mail_fetchbody() function which triggered the message text
	reading.
	 The purpose is to permit reading of large strings, without
	requiring an in-memory buffer for the entire string.  The idea
	is that this function can store the data in some form other
	than a char* (e.g. a temporary file) and the main program will
	recognize that it should get the text from there instead of
	from the results from mail_fetch....().
	 This is only supported on DOS and Win16; on other platforms it
	is inconsistent whether or not it works.

 GET_CACHE / SET_CACHE
	 Points to the c-client cache manager function.  Defaults to
	mm_cache().

 GET_SMTPVERBOSE / SET_SMTPVERBOSE
	 If non-NIL, points to a function that accepts a char* string.
	This function is called any time the SMTP routines receive a
	response code less than 100.  The argument is the text of the
	response code

 GET_RFC822OUTPUT / SET_RFC822OUTPUT
	 If non-NIL, points to an alternate rfc822_output() function.
	rfc822_output() will call this function and return instead of
	doing its normal action.  See the description of
	rfc822_output() for more information.	

 GET_USERNAME / SET_USERNAME
	 The logged-in user name.

 GET_HOMEDIR / SET_HOMEDIR
	 The home directory path name.

 GET_LOCALHOST / SET_LOCALHOST
	 The local host name.

 GET_SYSINBOX / SET_SYSINBOX
	 The &quot;system INBOX&quot; (where mail is delivered) path name.

 GET_OPENTIMEOUT / SET_OPENTIMEOUT
	 TCP/IP open timeout in seconds.  Defaults to 0 (system
	default timeout, usually 75 seconds on Unix).
	
 GET_READTIMEOUT / SET_READTIMEOUT
	 TCP/IP read timeout in seconds.  Defaults to 0 (no timeout).

 GET_WRITETIMEOUT / SET_WRITETIMEOUT
	 TCP/IP write timeout in seconds.  Defaults to 0 (no timeout).

 GET_CLOSETIMEOUT / SET_CLOSETIMEOUT
	 TCP/IP close timeout in seconds.  Defaults to 0 (no timeout).

 GET_TIMEOUT / SET_TIMEOUT
	 If non-NIL, points to the function called when a TCP/IP
	timeout occurs.  This function is called with the number of
	seconds since the start of the TCP operation.  If it returns
	non-zero, the TCP/IP operation is continued; if it returns
	non-zero, the TCP/IP connection is aborted.

 GET_RSHTIMEOUT / SET_RSHTIMEOUT
	 rsh connection timeout in seconds.  Defaults to 15 seconds.

 GET_MAXLOGINTRIALS / SET_MAXLOGINTRIALS
	 The maximum number of login attempts permitted in an IMAP or
	POP connection.  Defaults to 3.

 GET_LOOKAHEAD / SET_LOOKAHEAD
	 The number of subsequent envelopes prefetched in IMAP when an
	envelope is fetched.  Defaults to 20.

 GET_IMAPPORT / SET_IMAPPORT
	 The IMAP port number.  Defaults to 143.

 GET_PREFETCH / SET_PREFETCH
	 The number of envelopes prefetched in IMAP from the results
	of a SEARCH.  Defaults to 20.

 GET_CLOSEONERROR / SET_CLOSEONERROR
	 If non-NIL, close an opening IMAP connection if the SELECT
	command fails instead of returning a half-open stream.
	Defaults to NIL.

 GET_POP3PORT / SET_POP3PORT
	 The POP3 port number.  Defaults to 110.

 GET_UIDLOOKAHEAD / SET_UIDLOOKAHEAD
	 The number of UIDs premapped when a message number is
	translated to a UID.  Defaults to 1000.

 GET_MBXPROTECTION / SET_MBXPROTECTION
	 Default file protection for newly created mailboxes.
	Defaults to 0600.

 GET_DIRPROTECTION / SET_DIRPROTECTION
	 Default file protection for newly created directories.
	Defaults to 0700.

 GET_LOCKPROTECTION / SET_LOCKPROTECTION
	 Default file protection for locks.  Defaults to 0666.
	WARNING: don't blithely change this.  If other processes
	can't get access to a lock then they will have trouble in
	locking properly.

 GET_FROMWIDGET / SET_FROMWIDGET
	 If non-NIL, APPEND in the Unix mbox format will insert a
	&quot;&gt;&quot; character in front of all lines which begin with the
	string &quot;From &quot;.  If NIL, it will only do so if the entire
	line looks like a message delimiter (that is, the date is
	also in correct format).  Defaults to T.

 GET_NEWSACTIVE / SET_NEWSACTIVE
	 Netnews active file path name.

 GET_NEWSSPOOL / SET_NEWSSPOOL
	 Netnews spool directory path name.

 GET_NEWSRC / SET_NEWSRC
	 Netnews newsgroup reading status file (.newsrc) path name.

 GET_EXTENSION / SET_EXTENSION
	 If non-NIL, points to a string holding the extension for all
	mailbox files.  This is only supported on DOS and Win16.

 GET_DISABLEFCNTLLOCK / SET_DISABLEFCNTLLOCK
	 If non-NIL, disables fcntl() locking on SVR4.  This is done
	if fcntl() tends to hang for no good reason.  Now that the
	fcntl() code checks for NFS files and no-ops the locking,
	this problem usually doesn't happen much any more.  Defaults
	to NIL.

 GET_LOCKEACCESERROR / SET_LOCKEACCESERROR
	 If non-NIL, give a warning if an attempt to create a .lock
	file gets an EACCES (&quot;Permission denied&quot;) error.  This usually
	means that somebody protected the system inbox directory (e.g.
	/var/mail) instead of making it public-write with the sticky
	bit.  Defaults to non-NIL, since this is usually bad news.

 GET_LISTMAXLEVEL / SET_LISTMAXLEVEL
	 The maximum depth of recusion that LIST will go on a *
	wildcard.  Defaults to 20.

 GET_ANONYMOUSHOME / SET_ANONYMOUSHOME
	 The anonymous use home directory name.


typedef long (*readfn_t) (void *stream,unsigned long size,char *buffer);
	stream	a designator suitable
	size	a number of octets to read
	buffer	a buffer of at least size octets for readin

     This function reads the given number of octets into the buffer,
using the given stream.  What sort of object the stream is depends upon
the function and its caller, so you must make sure that the readfn is
suitable for the caller's purpose.  Common uses include support of the
mailgets function (see below) and of reading from local files on systems
with limited address space.


typedef char *(*mailgets_t) (readfn_t f,void *stream,unsigned long size);
	f	the readfn to use
	stream	stream argument for the readfn
	size	total number of octets to read

     This is the argument to the SET_GETS mail_parameter() call.  This
function must read size octets from the stream, using the readfn f.  It
may call f multiple times to accomplish this; this will read the data in
a serial fashion.  So, for example, if size is a megabyte and there is
only 4K of available buffer space, it can call f 256 times to satisfy
the request.  There is no way to back up in the reading, so any
processing or saving of the data must be done when it is read.

     The function mm_gets() in mail.c is a sample mailgets function; it
reads the first MAXMESSAGESIZE of data into memory and discards the
rest.


typedef void *(*mailcache_t) (MAILSTREAM *stream,unsigned long msgno,long op);
	stream	stream to cache manage
	msgno	message to cache manage in the stream
	op	cache management operation

     This function manages the c-client cache.  Normally, a program will
use the default c-client cache manager routine mm_cache().  However, a
main program may want to supply its own cache manager, e.g. it may want
to store the data on a disk file instead of in memory on DOS and Win16
where memory is tight.

     If you write your own cache manager, you need to examine the
default mm_cache() manager closely, as well as paying close attention to
what goes into an elt (a MESSAGECACHE element).  It is highly likely
that if you roll elts out to disk, you will want to set stream-&gt;scache
and *NOT* use long elts (because long elts have ENVELOPE and BODY
pointers that you would have to know how to write to disk and read back).

     The cache management functions are one of the following:

 CH_INIT	 Initialize the entire cache for the stream.  This is
		called only when creating a new stream or when freeing
		it.  The msgno argument is ignored.

 CH_SIZE	 Make sure that the cache is at least large enough to
		support msgno.  This is a request to grow the cache if
		necessary, not shrink it.

 CH_MAKELELT	 Return a long elt for msgno, creating it if necessary.
		This is the underlying support function for mail_lelt().

 CH_LELT	 Return the long elt for msgno, or NIL if it does not
		already exist.

 CH_MAKEELT	 Return an elt for msgno, creating it if necessary.
		This is the underlying support function for mail_elt().

 CH_ELT		 Return the elt for msgno, or NIL if it does not already
		exist.

 CH_FREE	 Free the [l]elt for msgno.

 CH_EXPUNGE	 Free the [l]elt for msgno, and reclaim its position.
		All subsequent elts are renumbered with their elt-&gt;msgno
		decremented by 1.  [Hence msgno+1 becomes msgno, etc.]
		This supports message expunging from the cache.


typedef long (*tcptimeout_t) (long time);
	time	total time spent since TCP operation started

     This function is called when a TCP operation times out.  It is set
by the SET_TIMEOUT mail_parameter().  The function can return non-zero
to continue the TCP operation (e.g. after outputting a &quot;do you still
want to wait&quot; prompt) or zero if it wants the TCP operation to abort and
close.  If the TCP operation aborts, it will likely cause the upper
level IMAP, SMTP, etc. stream to abort and close as well.


DRIVER *mail_valid (MAILSTREAM *stream,char *mailbox,char *purpose);
	stream	if non-NIL, stream to use for validation
	mailbox	mailbox name to validate
	purpose	filled in as xxx in &quot;Can't xxx&quot; in error messages

     This function validates the given mailbox name.  It successful, it
returns the driver that can open that name if successful, otherwise it
returns NIL.  If stream is non-NIL, the mailbox name must be valid for
the type of mailbox associated with that stream (e.g. an NNTP name can
not be used with an IMAP stream).  If purpose is non-NIL, an error
message is passed via mm_log() when an error occurs.


DRIVER *mail_valid_net (char *name,DRIVER *drv,char *host,char *mailbox);
	name	mailbox name to validate
	drv	driver name to validate against
	host	buffer to return host name if non-NIL
	mailbox	buffer to return remote mailbox name if non-NIL

     This function is an alternative to mail_valid_net_parse().  It
validates the given mailbox name as a network name and makes sure that
its service name is the same as the driver in drv.  If successful, it
returns drv, and copies the host and mailbox strings as needed.
Otherwise it returns NIL.


long mail_valid_net_parse (char *name,NETMBX *mb);
	name	mailbox name to parse
	mb	pointer to NETMBX structure to return

     This function parses a network mailbox name.  If the name is a
network mailbox name, it returns non-NIL, with the NETMBX structure
loaded with the results form the parse.

		       Mailbox Access Functions

void mail_list (MAILSTREAM *stream,char *ref,char *pat);
void mail_scan (MAILSTREAM *stream,char *ref,char *pat,char *contents);
	stream	if non-NIL, stream to use
	ref	mailbox reference string
	pat	mailbox pattern string
	contents contents to search

     This function returns a list of mailboxes via the mm_list()
callback.  The reference is applied to the pattern in an implementation
dependent fashion, and the resulting string is used to search for
matching mailbox names.  &quot;*&quot; is a wildcard which matches zero or more
characters; &quot;%&quot; is a variant which does not descend a hierarchy level.
Read the IMAP specification for more information.

     mail_scan() is a variant which takes a string to search for in the
text of the mailbox.  The string is a free-text string, without regard
for message boundaries, and thus the choice of strings must be made
with care.


void mail_lsub (MAILSTREAM *stream,char *ref,char *pat);
	stream	if non-NIL, stream to use
	ref	mailbox reference string
	pat	mailbox pattern string

     This function returns a list of subscribed mailboxes via the
mm_lsub() callback.  The reference is applied to the pattern in an
implementation dependent fashion, and the resulting string is used to
search for matching mailbox names in the subscription list.  &quot;*&quot; is a
wildcard which matches zero or more characters; &quot;%&quot; is a variant which
does not descend a hierarchy level.  Read the IMAP specification for
more information.


long mail_subscribe (MAILSTREAM *stream,char *mailbox);
	stream	if non-NIL, stream to use
	mailbox	mailbox name

     This function adds the given name to the subscription list.  It
returns T if successful, NIL if unsuccessful.  If unsuccessful, an
error message is returned via the mm_log() callback.


long mail_unsubscribe (MAILSTREAM *stream,char *mailbox);
	stream	if non-NIL, stream to use
	mailbox	mailbox name

     This function removes the given name from the subscription list.
It returns T if successful, NIL if unsuccessful.  If unsuccessful, an
error message is returned via the mm_log() callback.


long mail_create (MAILSTREAM *stream,char *mailbox);
	stream	if non-NIL, stream to use
	mailbox	mailbox name

     This function creates a mailbox with the given name.  It returns T
if successful, NIL if unsuccessful.  If unsuccessful, an error message
is returned via the mm_log() callback.

     It is an error to create INBOX or a mailbox name which already
exists.


long mail_delete (MAILSTREAM *stream,char *mailbox);
	stream	if non-NIL, stream to use
	mailbox	mailbox name

     This function deletes the named mailbox.  It returns T if
successful, NIL if unsuccessful.  If unsuccessful, an error message is
returned via the mm_log() callback.

     It is an error to delete INBOX or a mailbox name which does not
already exist.


long mail_rename (MAILSTREAM *stream,char *old,char *newname);
	stream	if non-NIL, stream to use
	old	existing mailbox name
	newname	new (not yet existing) mailbox name

     This function renames the old mailbox to the new mailbox name.
It returns T if successful, NIL if unsuccessful.  If unsuccessful, an
error message is returned via the mm_log() callback.

     It is an error to reanme a mailbox that does not exist, or rename
a mailbox to a name that already exists.  It is permitted to rename
INBOX; a new empty INBOX is created in its place.


long mail_status (MAILSTREAM *stream,char *mbx,long flags);
	stream	if non-NIL, stream to use
	mbx	mailbox name
	flags	option flags

     This function returns the status of the given mailbox name via the
mm_status() callback.  It returns T if successful, NIL if unsuccessful.
If unsuccessful, an error message is returned via the mm_log()
callback.

     The options are a bit mask with one or more of the following,
indicating the data which should be returned.
	SA_MESSAGES	number of messages in the mailbox
	SA_RECENT	number of recent messages in the mailbox
	SA_UNSEEN	number of unseen messages in the mailbox
	SA_UIDNEXT	next UID value to be assigned
	SA_UIDVALIDITY	UID validity value

     Note that, depending upon implementation, some of these values may
be more costly to get than others.  For example, calculating the
number of unseen messages may require opening the mailbox and scanning
all of the message flags.  A mail_status() call should thus be used
with option flags specifying only the data that is actually needed.


MAILSTREAM *mail_open (MAILSTREAM *oldstream,char *name,long options);
	oldstream if non-NIL, stream to recycle
	name	mailbox name to open
	options	option flags.

     This function opens the mailbox and if successful returns a stream
suitable for use by the other MAIL functions.

     If oldstream is non-NIL, an attempt is made to reuse oldstream as
the stream for this mailbox; this is useful when you want to open
another mailbox to the same IMAP or NNTP server without having to open
a new connection.  Doing this will close the previously open mailbox.

     The options are a bit mask with one or more of the following:
	OP_DEBUG	Log IMAP protocol telemetry through mm_debug()
	OP_READONLY	Open mailbox read-only.
	OP_ANONYMOUS	Don't use or update a .newsrc file for news.
	OP_SHORTCACHE	Don't cache envelopes or body structures
	OP_SILENT	Don't pass mailbox events (internal use only)
	OP_PROTOTYPE	Return the &quot;prototype stream&quot; for the driver
			 associated with this mailbox instead of
			 opening the stream
	OP_HALFOPEN	For IMAP and NNTP names, open a connection
			 to the server but don't open a mailbox.
	OP_EXPUNGE	Silently expunge the oldstream before recycling

 NIL is returned if this function fails for any reason.


MAILSTREAM *mail_close (MAILSTREAM *stream);
MAILSTREAM *mail_close_full (MAILSTREAM *stream,long options);
	stream	stream to close
	options	option flags
     This function closes the MAIL stream and frees all resources
associated with it that it may have created (subject to any handles
existing).

     The options for mail_close_full() are a bit mask with one or more
of the following:
	CL_EXPUNGE	Silently expunge before closing

     This function always returns NIL, so it can be used as:
	stream = mail_close (stream);

			   Handle Functions

     Handles are used when an entity that wishes to access the stream
may survive the stream without knowing that it outlived it.  For
example, an object reading a message may have a handle to a stream,
but the message selection object that spawned it (and which owns the
stream) may have gone away.  A stream can be closed or recycled while
handles are pointing at it, but it is not completely freed until all
handles are gone.  A stream may have an arbitrary number of handles.


MAILHANDLE *mail_makehandle (MAILSTREAM *stream);
	stream	stream to make handle to

     This function creates and returns a handle to the stream.


void mail_free_handle (MAILHANDLE **handle);
	handle	pointer to handle to release

     This function frees the handle and notifies the stream that it has
one fewer handle.  If this is the last handle on the stream and the
stream has been closed, then the stream is freed.


MAILSTREAM *mail_stream (MAILHANDLE *handle);
	handle	handle to look up

     This function returns the stream associated with the handle if and
only if the stream still represents the same MAIL connection associated
with the handle.  Otherwise, NIL is returned (meaning that there is no
active stream associated with this handle).

		    Message Data Fetching Functions

[Note!!  There is an important difference between a &quot;sequence&quot; and a
 &quot;msgno&quot;.  A sequence is a string representing one or more messages in
 IMAP4-style sequence format (&quot;n&quot;, &quot;n:m&quot;, or combination of these
 delimited by commas), whereas a msgno is an int representing a single
 message.] 

void mail_fetchfast (MAILSTREAM *stream,char *sequence);
void mail_fetchfast_full (MAILSTREAM *stream,char *sequence,long flags);
	stream	stream to fetch on
	sequence IMAP-format set of message sequence numbers
	flags	option flags

     This function causes a cache load of all the &quot;fast&quot; information
(internal date, RFC 822 size, and flags) for the given sequence.  Since
all this information is also fetched by mail_fetchstructure(), this
function is generally not used unless the OP_SHORTCACHE option in the
mail_open() call is used.

     The options for mail_fetchfast_full() are a bit mask with one or
more of the following:
	FT_UID		The sequence argument contains UIDs instead of
			 sequence numbers


void mail_fetchflags (MAILSTREAM *stream,char *sequence);
void mail_fetchflags_full (MAILSTREAM *stream,char *sequence,long flags);

     This function causes a fetch of the flags for the given sequence.
This main reason for using this function is to update the flags in the
local cache in case some other process changed the flags (multiple
simultaneous write access is allowed to the flags) as part of a &quot;check
entire mailbox&quot; (as opposed to &quot;check for new messages&quot;) operation.

 The options for mail_fetchflags_full() are a bit mask with one or more
of the following:
	FT_UID		The sequence argument contains UIDs instead of
			 sequence numbers


ENVELOPE *mail_fetchenvelope (MAILSTREAM *stream,unsigned long msgno);
ENVELOPE *mail_fetchstructure (MAILSTREAM *stream,unsigned long msgno,
			       BODY **body);
ENVELOPE *mail_fetchstructure_full (MAILSTREAM *stream,unsigned long msgno,
				    BODY **body,long flags);
	stream	stream to fetch on
	msgno	message sequence number
	body	pointer to where to return BODY structure if non-NIL
	flags	option flags
     This function causes a fetch of all the structured information
(envelope, internal date, RFC 822 size, flags, and body structure) for
the given msgno and, in the case of IMAP, up to MAPLOOKAHEAD (a
parameter in IMAP2.H) subsequent messages which are not yet in the
cache.  No fetch is done if the envelope for the given msgno is already
in the cache.  The ENVELOPE and the BODY for this msgno is returned.
It is possible for the BODY to be NIL, in which case no information is
available about the structure of the message body.

     The options for mail_fetchstructure_full() are a bit mask with one
or more of the following:
	FT_UID		The msgno argument is a UID 

     This is the primary function for fetching non-text information
about messages, and should be called before any attempt to reference
cache information about this message via mail_elt().


char *mail_fetchheader (MAILSTREAM *stream,unsigned long msgno);
char *mail_fetchheader_full (MAILSTREAM *stream,unsigned long msgno,
			     STRINGLIST *lines,unsigned long *len,long flags);
	stream	stream to fetch on
	msgno	message sequence number
	lines	list of header lines to fetch
	len	returned length in octets
	flags	option flags

     This function causes a fetch of the complete, unfiltered RFC 822
format header of the specified message as a text string and returns
that text string.

     If the lines argument is non-NIL, it contains a list of header
field names to use in subsetting the header text.  Only those lines
which have that header field name are returned, unless FT_NOT is set in
which case only those lines which do not have that header field name
are returned.

     If the len argument is non-NIL, it holds a pointer in which the
length of the string in octets is returned.  This is useful in cases
where there may be an embedded null in the string.

     This function always returns a valid string pointer; if no header
exists or if it can not be fetched (e.g. by a deceased IMAP stream) an
empty string is returned.

     The options for mail_fetchheader_full() are a bit mask with one or
more of the following:
	FT_UID		The msgno argument is a UID 
	FT_NOT		The returned header lines are those that are
			 not in the lines argument
	FT_INTERNAL	The return string is in &quot;internal&quot; format,
			 without any attempt to canonicalize to CRLF
			  newlines
	FT_PREFETCHTEXT	The RFC822.TEXT should be pre-fetched at the
			 same time.  This avoids an extra RTT on an
			 IMAP connection if a full message text is
			 desired (e.g. in a &quot;save to local file&quot;
			 operation)
		 

char *mail_fetchtext (MAILSTREAM *stream,unsigned long msgno);
char *mail_fetchtext_full (MAILSTREAM *stream,unsigned long msgno,
			   unsigned long *len,long flags);
	stream	stream to fetch on
	msgno	message sequence number
	len	returned length in octets
	flags	option flags

     This function causes a fetch of the non-header text of the
specified message as a text string and returns that text string.  No
attempt is made to segregate individual body parts.

     If the len argument is non-NIL, it holds a pointer in which the
length of the string in octets is returned.  This is useful in cases
where there may be an embedded null in the string.

     This function always returns a valid string pointer; if no header
exists or if it can not be fetched (e.g. by a deceased IMAP stream) an
empty string is returned.

      The options for mail_fetchtext_full() are a bit mask with one or
more of the following:
	FT_UID		The msgno argument is a UID 
	FT_PEEK		Do not set the \Seen flag if it not already set
	FT_INTERNAL	The return string is in &quot;internal&quot; format,
			 without any attempt to canonicalize to CRLF
			  newlines


char *mail_fetchbody (MAILSTREAM *stream,unsigned long msgno,char *sec,
		      unsigned long *len);
char *mail_fetchbody_full (MAILSTREAM *stream,unsigned long msgno,char *sec,
			   unsigned long *len,long flags);
	stream	stream to fetch on
	msgno	message sequence number
	sec	section specifier
	len	returned length in octets
	flags	option flags

      This function causes a fetch of the particular section of the
body of the specified message as a text string and returns that text
string.  The section specification is a string of integers delimited by
period which index into a body part list as per the IMAP4
specification.  Body parts are not decoded by this function; see
rfc822_base64() and rfc822_quotedprintable().

     If the len argument is non-NIL, it holds a pointer in which the
length of the string in octets is returned.  This is useful in cases
where there may be an embedded null in the string.

      This function may return NIL on error.

      The options for mail_fetchbody_full() are a bit mask with one or
more of the following:
	FT_UID		The msgno argument is a UID 
	FT_PEEK		Do not set the \Seen flag if it not already set
	FT_INTERNAL	The return string is in &quot;internal&quot; format,
			 without any attempt to canonicalize to CRLF
			  newlines


unsigned long mail_uid (MAILSTREAM *stream,unsigned long msgno);
	stream	stream to fetch on
	msgno	message sequence number

      This function returns the UID for the given message sequence
number.


void mail_fetchfrom (char *s,MAILSTREAM *stream,unsigned long msgno,
		     long length);
	s	destination string
	stream	stream to fetch on
	msgno	message sequence number
	length	maximum field length

     This function writes a &quot;from&quot; string of the specified length for
the specified message, suitable for display to the user in a menu line,
into the string pointed to by s.

      If the personal name of the first address in the envelope's from
item is non-NIL, it is used; otherwise a string is created by appending
the mailbox of the first address, an &quot;@&quot;, and the host of the first
address.  The string is trimmed or padded with trailing spaces as
necessary to make its length match the length argument.


void mail_fetchsubject (char *s,MAILSTREAM *stream,unsigned long msgno,
			long length);
	s	destination string
	stream	stream to fetch on
	msgno	message sequence number
	length	maximum field length

      This function returns a &quot;subject&quot; string of the specified length
for the specified message, suitable for display to the user in a menu
line.

       The envelope's subject item is copied and trimmed as necessary
to make its length be no more what the caller requested.  Unlike
mail_fetchfrom(), this function can return a string of shorter length
than what the caller requested.


LONGCACHE *mail_lelt (MAILSTREAM *stream,unsigned long msgno);
MESSAGECACHE *mail_elt (MAILSTREAM *stream,unsigned long msgno);
	stream	stream to access
	msgno	message sequence number

     This function returns the cache entry for the specified message.
Although it will create a cache entry if it does not already exist,
that functionality is for internal use only.  This function should
never be called without having first called mail_fetchfast() or
mail_fetchstructure() on the message first.

     A cache entry holds the internal date/time, flags, and RFC 822
size of a message.  It holds other data as well, but that is for
internal use only.

     mail_lelt() is a variant that returns a `long' cache entry, which
consists of an cache entry (as a structure, not a pointer), an envelope
pointer, and a body pointer.  This is used in conjunction with the elt
lock count functionality, to allow an application to associate the
cached envelope and body of a message with an open window even if the
message is subsequently expunged or if the stream is closed.

     Unless your application wants to look at cached envelopes and
bodies even after the message is expunged or the stream is closed, it
should not use mail_lelt().  Instead, it should use a returned elt from
mail_elt() and use the elt-&gt;msgsno as the argument to
mail_fetchstructure().

	BEWARE: the behavior of mail_lelt() is undefined if the
	stream is open with OP_SHORTCACHE.  mail_lelt() is extremely
	special purpose, and should only be used in sophisticated
	special purpose applications after discussing its use with
	the c-client author.  If you think you need this function,
	you are probably mistaken.  In almost all cases, you should
	use mail_elt() and mail_fetchstructure() instead.

		 Message Status Manipulation Functions

void mail_setflag (MAILSTREAM *stream,char *sequence,char *flag);
void mail_setflag_full (MAILSTREAM *stream,char *sequence,char *flag,
			long flags);
	stream	stream to use
	sequence IMAP-format set of message sequence numbers
	flag	IMAP-format flag string
	flags	option flags

    This function causes a store to add the specified flag to the flags
set for the messages in the specified sequence.  If there is any
problem in setting flags, a message will be passed to the application
via the mm_log() facility.

     The options for mail_setflag_full() are a bit mask with one or
more of the following:
	ST_UID		The sequence argument contains UIDs instead of
			 sequence numbers
	ST_SILENT	Do not update the local cache with the new
			 value of the flags.  This is useful to save
			 network bandwidth, at the cost of invalidating
			 the cache.


void mail_clearflag (MAILSTREAM *stream,char *sequence,char *flag);
void mail_clearflag_full (MAILSTREAM *stream,char *sequence,char *flag,
			  long flags);
	stream	stream to use
	sequence IMAP-format set of message sequence numbers
	flag	IMAP-format flag string
	flags	option flags

     This function causes a store to delete the specified flag from the
flags set for the messages in the specified sequence.  If there is any
problem in clearing flags, a message will be passed to the application
via the mm_log() facility.

     The options for mail_setflag_full() are a bit mask with one or
more of the following:
	ST_UID		The sequence argument contains UIDs instead of
			 sequence numbers
	ST_SILENT	Do not update the local cache with the new
			 value of the flags.  This is useful to save
			 network bandwidth, at the cost of invalidating
			 the cache.

			   Mailbox Searching

void mail_search (MAILSTREAM *stream,char *criteria);
void mail_search_full (MAILSTREAM *stream,char *charset,SEARCHPGM *pgm,
		       long flags);
	stream	stream to search
	charset	MIME character set to use when searching strings
	pgm	search program
	flags	option flags

     This function causes a mailbox search, using the given MIME
charset (NIL means the default, US-ASCII) and the given search program.
A search program is a structure that holds the following data:

SEARCHSET *msgno;	a set of message sequence numbers
SEARCHSET *uid;		a set of unique identifiers
SEARCHOR *or;		OR result of two search programs
SEARCHPGMLIST *not;	AND result of list of NOT'ed search programs
SEARCHHEADER *header;	message headers
STRINGLIST *bcc;	string(s) appear in bcc list
STRINGLIST *body;	string(s) appear in message body text
STRINGLIST *cc;		string(s) appear in cc list
STRINGLIST *from;	string(s) appear in from
STRINGLIST *keyword;	user flag string(s) set
STRINGLIST *unkeyword;	user flag strings() not set
STRINGLIST *subject;	string(s) appear in subject
STRINGLIST *text;	string(s) appear in message header or body
STRINGLIST *to;		string(s) appear in to list
unsigned long larger;	larger than this many octets
unsigned long smaller;	smaller than this many octes
	The following dates are in form:
		((year - BASEYEAR) &lt;&lt; 9) + (month &lt;&lt; 5) + day
unsigned short sentbefore;
			sent before this date
unsigned short senton;	sent on this date
unsigned short sentsince;
			sent since this date
unsigned short before;	received before this date
unsigned short on;	received on this date
unsigned short since;	received since this date
unsigned int answered : 1;
			message answered
unsigned int unanswered : 1;
			message not answered
unsigned int deleted : 1;
			message deleted
unsigned int undeleted : 1;
			message not deleted
unsigned int draft : 1;	message is a draft
unsigned int undraft : 1;
			message is not a draft
unsigned int flagged : 1;
			message flagged as urgent
unsigned int unflagged : 1;
			message not flagged as urgent
unsigned int recent : 1;
			message recent since last parse of mailbox
unsigned int old : 1;	message not recent since last parse of mailbox
unsigned int seen : 1;	message read
unsigned int unseen : 1;
			message not read

     The following auxillary structures are used by search programs:
	SEARCHHEADER:	header line searching
char *line;		header line field name
char *text;		text header line
SEARCHHEADER *next;	next SEARCHHEADER in list (AND'ed)

	SEARCHSET:	message number set
unsigned long first;	first number in set
unsigned long last;	if non-zero, last number in set
SEARCHSET *next;	next SEARCHSET in list (AND'ed)

	SEARCHOR:	two search programs, OR'ed together
SEARCHPGM *first;	first program
SEARCHPGM *second;	second program
SEARCHOR *next;		next SEARCHOR in list

	SEARCHPGMLIST:	list of search programs
SEARCHPGM *pgm;		search program (AND'd with others in list)
SEARCHPGMLIST *next;	next SEARCHPGM in list

     mail_search(), the older interface, accepts a search criteria
argument as a character string in IMAP2 (RFC-1176) format.  Do not try
to use any IMAP4 search criteria with this interface.

     The application's mm_searched() function is called for each
message that matches the search criteria.  In addition, after the
search is completed, the &quot;fast&quot; information (see mail_fetchfast_full()
and envelopes of the searched messages are fetched (this is called
pre-fetching).

     If there is any problem in searching, a message will be passed to
the application via the mm_log() facility.

     The flags for mail_search_full() are a bit mask with one or more
of the following:
	SE_UID		Return UIDs instead of sequence numbers
	SE_FREE		Return the search program to free storage after
			 finishing
	SE_NOPREFETCH	Don't prefetch searched messages.


unsigned long *mail_sort (MAILSTREAM *stream,char *charset,SEARCHPGM *spg,
			  SORTPGM *pgm,long flags);
	stream	stream to sort
	charset	MIME character set to use when sorting strings
	spg	search program
	pgm	sort program
	flags	option flags


     This function is a variant of mail_search_full().  It accepts an
additional argument, a sort program, which specifies one or more sort
rules to be applied to the result.  If the searching and sorting are
successful, it returns a 0-terminated vector of message sequence
numbers (or UIDs if SE_UID is set).  This vector is created out of
free storage, and must be freed with fs_give() when finished with it.

     A sort program is a structure that holds the following data:
unsigned int reverse : 1;
			reverse sorting of this key
short function;		sort rule, one of the following:
		SORTDATE	message Date
		SORTARRIVAL	arrival date
		SORTFROM	mailbox in first From address
		SORTSUBJECT	message Subject
		SORTTO		mailbox in first To address 
		SORTCC		mailbox in first cc address 
		SORTSIZE	size of message in octets
SORTPGM *next;		next sort program to be applied if two or more
			 messages collate identically with this rule

     The flags for mail_search_full() are a bit mask with one or more
of the following:
	SE_UID		Return UIDs instead of sequence numbers
	SE_FREE		Return the search program to free storage after
			 finishing
	SE_NOPREFETCH	Don't prefetch searched messages.
	SO_FREE		Return the sort program to free storage after
			 finishing

	      Miscellaneous Mailbox and Message Functions

long mail_ping (MAILSTREAM *stream);
	stream	string to ping

     The function pings the stream to see if it is still active.  It may
discover new mail; this is the preferred method for a periodic &quot;new mail
check&quot; as well as a &quot;keep alive&quot; for servers which have an inactivity
timeout.  It returns T if the stream is still alive, NIL otherwise.

     If new mail is found, the application's mm_exists() function is
called with the newly-determined number of messages in the mailbox.


void mail_check (MAILSTREAM *stream);
	stream	stream to checkpoint

      This function causes a mailstore-defined checkpoint of the
mailbox.  This may include such things as a writeback to disk, a check
for flag changes in a shared mailbox, etc.  It is not a &quot;check for new
mail&quot;; mail_ping() performs this function (as potentially does any other
function).  The status of the check is passed to the application via the
mm_log() facility.


void mail_expunge (MAILSTREAM *stream);
	stream	string to expunge

     This function causes an expunge (permanent removal of messages
which are marked as deleted) of the mailbox.  The application's
mm_expunged() function is called for each message that has been
expunged.  The application's mm_exists() function is called at the start
and end of the expunge to ensure synchronization.  The status of the
expunge is passed to the application via the mm_log() facility.

      Note that the decrementing of msgno's for subsequent messages
happens immediately; for example, if three consequtive messages starting
at msgno 5 are expunged, mm_expunged() will be called with a msgno of 5
three times.


long mail_copy (MAILSTREAM *stream,char *sequence,char *mailbox);
long mail_move (MAILSTREAM *stream,char *sequence,char *mailbox);
long mail_copy_full (MAILSTREAM *stream,char *sequence,char *mailbox,
		     long options);
	stream	stream to copy
	sequence IMAP-format set of message numbers
	mailbox	destination mailbox name
	options	option flags

     This function causes the messages in the specified sequence to be
copied to the specified mailbox.  T is returned if the copy is
successful.  mail_move() is equivalent to setting CP_MOVE in the options.

     If there is any problem in copying, a message will be passed to
the application via the mm_log() facility and the function returns NIL.
No copying is actually done in this case.

      Note that the mailbox must be on the same host as the stream and
is a mailbox of the type of the source mailbox only.

     The flags for mail_search_full() are a bit mask with one or more
of the following:
	CP_UID		The sequence argument contains UIDs instead of
			 sequence numbers
	CP_MOVE		Delete the messages from the current mailbox
			 after copying to the destination.


long mail_append (MAILSTREAM *stream,char *mailbox,STRING *message);
long mail_append_full (MAILSTREAM *stream,char *mailbox,char *flags,char *date,
		       STRING *message);
	stream	stream to use if non-NIL (in the IMAP case)
	mailbox	destination mailbox name
	flags	flags to set on message if non-NIL
	date	internal date (received date) to set on message if non-NIL
	message	string structure of message to write

     This function writes the message in the string structure to the
destination mailbox, along with the flags and date if specified.  This
is useful in those cases where you can't use mail_copy(), e.g. when
copying from one server to another; you can always fetch the message
and then mail_append() it to the destination.  It may also be useful
for maintaining an outbox of your outgoing mail.


void mail_gc (MAILSTREAM *stream,long gcflags);
	stream	stream to GC if non-NIL (else GC's all streams)
	flags	option flags

      This function garbage collects (purges) the cache of entries of
a specific type.  Some drivers do not allow purging of particular
cache types, and an attempt to do so is ignored.

      The flags for mail_gc() are a bit mask with one or more of the
following:
	GC_ELT		message cache elements
	GC_ENV		ENVELOPEs and BODYs
	GC_TEXTS	cached texts

		     Date/Time Handling Functions


char *mail_date (char *string,MESSAGECACHE *elt);
	string	destination string
	elt	message cache element containing date

      This function accepts a message cache element that contains date
information, and writes an IMAP-4 date string, that is, one in form:
	dd-mmm-yyyy hh:mm:ss +zzzz
based upon the data in the elt.  The destination string must be large
enough to hold this string.


char *mail_cdate (char *string,MESSAGECACHE *elt);
	string	destination string
	elt	message cache element containing date

      This function accepts a message cache element that contains date
information, and writes a ctime() format date string, that is, one in
form:
	www mmm dd hh:mm:ss yyyy\n
based upon the data in the elt.  The destination string must be large
enough to hold this string.


long mail_parse_date (MESSAGECACHE *elt,char *string);
	elt	message cache element to store parsed date
	string	source date string

      This function parses the date/time stored in the given string,
in format:
	[www,] date [[hh:mm[:ss][-zzz| +zzzz]
where the date can be any of:
	mm/dd/yy, mm/dd/yyyy, dd-mmm-yy, dd-mmm-yyyy, dd mmm yy, dd mmm yyyy
and stores the result of the parse in the elt.  If the parse is
successful, T is returned, else NIL.


unsigned long mail_longdate (MESSAGECACHE *elt);
	elt	message cache element containing date.

      This function accepts a message cache element that contains date
information, and returns the number of days since the base time of the
imap-4 toolkit.  At present, this is the same as the Unix time() value
for that date/time, and hence can be used for functions such as utime().

			  Utility Functions

void mail_debug (MAILSTREAM *stream);
	stream	stream to debug

      This function enables telemetry logging for this stream.  All
telemetry is passed to the application via the mm_dlog() facility.


void mail_nodebug (MAILSTREAM *stream);
	stream	stream to disable debugging

     This function disables telemetry logging for this stream.


long mail_sequence (MAILSTREAM *stream,char *sequence);
	stream	stream to set the sequence bits
	sequence IMAP-format message set string

     This function parses the given sequence string for message
numbers, sets the sequence bit in the stream's message cache element
of all messages in the sequence (and turns it off in all other message
cache elements).  If the parse is successful, T is returned, else NIL.


long mail_uid_sequence (MAILSTREAM *stream,char *sequence);
	stream	stream to set the sequence bits
	sequence IMAP-format message set string

     This function parses the given sequence string for unique
identifiers, sets the sequence bit in the stream's message cache
element of all messages in the sequence (and turns it off in all other
message cache elements).  If the parse is successful, T is returned,
else NIL.


long mail_parse_flags (MAILSTREAM *stream,char *flag,unsigned long *uf);
	stream	stream (used to get user flags)
	flag	IMAP-format flag string to parse
	uf	returned location of user flags

     The function parses the given flag string, and returns the system
flags as its return value and the user flags in the location pointed
to by the uf argument.  If there is an error in parse, a log message
is issued via mm_log() and this function returns NIL.


unsigned long mail_filter (char *text,unsigned long len,STRINGLIST *lines,
			   long flags);
	text	RFC 822 text to filter
	len	length in octets in the text argument
	lines	string list of header file names to filter
	flags	option flags

     This function supports the header lines filtering function of
mail_fetchheader_full().  The lines argument contains a list of header
field names to use in subsetting the header text.  Only those lines
which have that header field name are returned, unless FT_NOT is set
in which case only those lines which do not have that header field
name are returned.

     The options for mail_filter() are a bit mask with one or more of
the following:
	FT_NOT		The returned header lines are those that are
			 not in the lines argument


long mail_search_msg (MAILSTREAM *stream,unsigned long msgno,char *charset,
		      SEARCHPGM *pgm);
	stream	stream to search
	msgno	message number of message to inspect
	charset	character set of search strings
	pgm	search program to test

     This function implements mail_search_full() locally in cases when
it is not done by a server (e.g. local mail files, NNTP/POP).  It
inspects the given message on that stream to see if it matches the
criteria or not.  If it matches, T is returned, else NIL.


SEARCHPGM *mail_criteria (char *criteria);
	criteria IMAP2-format search criteria string

     This function accepts an IMAP2-format search criteria string and
parses it.  If the parse is successful, it returns a search program
suitable for use in mail_search_full().
	WARNING: This function does not accept IMAP4 search criteria.
	The source string must be writeable (this restriction was also
	in the old IMAP2 c-client).

	   Data Structure Instantiation/Destruction functions

     These functions are used to obtain structures from free storage and
to release them.

ENVELOPE *mail_newenvelope (void);
ADDRESS *mail_newaddr (void);
BODY *mail_newbody (void);
BODY *mail_initbody (BODY *body);
PARAMETER *mail_newbody_parameter (void);
PART *mail_newbody_part (void);
STRINGLIST *mail_newstringlist (void);
SEARCHPGM *mail_newsearchpgm (void);
SEARCHHEADER *mail_newsearchheader (char *line);
SEARCHSET *mail_newsearchset (void);
SEARCHOR *mail_newsearchor (void);
SEARCHPGMLIST *mail_newsearchpgmlist (void);
SORTPGM *mail_newsortpgm (void);

     These functions, all named mail_new...(), create a new structure of
the given type and initialize all of its elements to zero or empty.

void mail_free_body (BODY **body);
void mail_free_body_parameter (PARAMETER **parameter);
void mail_free_body_part (PART **part);
void mail_free_cache (MAILSTREAM *stream);
void mail_free_elt (MESSAGECACHE **elt);
void mail_free_lelt (LONGCACHE **lelt);
void mail_free_envelope (ENVELOPE **env);
void mail_free_address (ADDRESS **address);
void mail_free_stringlist (STRINGLIST **string);
void mail_free_searchpgm (SEARCHPGM **pgm);
void mail_free_searchheader (SEARCHHEADER **hdr);
void mail_free_searchset (SEARCHSET **set);
void mail_free_searchor (SEARCHOR **orl);
void mail_free_searchpgmlist (SEARCHPGMLIST **pgl);
void mail_free_sortpgm (SORTPGM **pgm);

     These functions, all named mail_free_...(), take a pointer to a
structure pointer, free all contained strings and structures within the
structure, and finally free the structure itself and set its pointer to
NIL.  For example, mail_free_envelope() frees all the ADDRESS structures
contained in the envelope.

     Normally, mail_free_elt() and mail_free_lelt() are used only if the
main program has a private pointer to cache elements.  If so, it is
expected to increment the cache element's lockcount when it makes a
private pointer, and to call this function when it is finished with it.

		       Authentication Functions

char *mail_auth (char *mechanism,authresponse_t resp,int argc,char *argv[]);
	mechanism authentication mechanism name
	resp	callback function for providing responses
	argc	main() function argc value
	argv	main() function argv value

     This server function searches the list of authenticators that was
established by auth_link() for an authenticator with the given name.  If
an authenticator is found, authentication is initialized.  The function
pointed to by resp is called as the authenticator requires responses.


AUTHENTICATOR *mail_lookup_auth (unsigned int i);
	i	position in authenticator list

     This function returns the nth authenticator in the list, where n is
the value of it.


unsigned int mail_lookup_auth_name (char *mechanism);
	mechanism authentication mechanism name

     This function searches the list of authenticators for an
authenticator with the given name, and returns its position in the
authenticator list.


     The functions below are provided by c-client client drivers or by
servers to support the protocol-dependent parts of authentication.

typedef void *(*authchallenge_t) (void *stream,unsigned long *len);
	stream	stream to read challenge
	len	pointer to returned length in octets

     This driver function is called by an authenticator to read a
challenge from the given protocol stream in a protocol-dependent way.
It returns that challenge in binary and its length in octets to the
authenticator.


typedef long (*authrespond_t) (void *stream,char *s,unsigned long size);
	stream	stream to send response
	s	response string
	size	length of response string in octets

     This driver function is called by an authenticator to send a
challenge response to the given stream in a protocol-dependent way.
It returns T if successful, NIL if failure.


typedef char *(*authresponse_t) (void *challenge,unsigned long clen,
				 unsigned long *rlen);
	challenge challenge string
	clen	length of challenge string in octets
	rlen	pointer to returned length of response string

     This server function is called with a challenge string of clen
octets.  It sends, according to whatever protocol (IMAP, POP, etc.) it
uses, and returns the received response and response length in octets.


typedef long (*authclient_t) (authchallenge_t challenger,
			      authrespond_t responder,NETMBX *mb,void *s,
			      unsigned long trial);
	challenger pointer to protocol-dependent challenge reader function
	responder pointer to protocol-dependent response sender function
	mb	NETMBX struct of the mailbox desired to open
	s	stream for protocol-dependent routines to use
	trial	number of authentication attempts remaining

     This client authenticator function negotiates reading challenges
and sending responses for a particular authenticator (Kerberos, etc.)
over the protocol, and returns T if authenticated or NIL if failed.


typedef char *(*authserver_t) (authresponse_t responder,int argc,char *argv[]);
	responder pointer to protocol-dependent responder function
	argc	main() function argc value
	argv	main() function argv value

    This server authenticator function negotiates sending challenges and
reading responses for a particular authenticator (Kerberos, etc.), and
returns either the authenticated user name or NIL if authentication
failed.

		       Network Access Functions

     These functions provide a layer of indirection between the TCP
routines and upper level routines.  This makes it possible to insert
additional code (e.g. privacy or checksum handling).

NETSTREAM *net_open (char *host,char *service,unsigned long port);
	host	host name
	service	contact service name
	port	contact port number

     This function opens a TCP connection to the given host and service
or port.


NETSTREAM *net_aopen (NETMBX *mb,char *service,char *usrbuf);
	NETMBX	parsed mailbox specification
	service	stream to open (at present, only /etc/rimapd is used)
	usrbuf	buffer to return login user name

     This function attempts to open a preauthenticated connection to the
given mailbox and service.  It will return the login user name of the
preauthenticated connection, as well as an open network stream, if
successful.


char *net_getline (NETSTREAM *stream);
	stream	network stream to read

     This routine reads a text line from the stream.  It calls
stream-&gt;dtb-&gt;getline, which normally points to tcp_getline() but can be
set to some other function.


long net_getbuffer (void *stream,unsigned long size,char *buffer);
	stream	network stream to read
	size	length of data in octets
	buffer	buffer of at least size octets

     This routine reads data from the stream.  It calls
stream-&gt;dtb-&gt;getbuffer, which normally points to tcp_getbuffer() but can
be set to some other function.


long net_soutr (NETSTREAM *stream,char *string);
	stream	network stream to write
	string	null-terminated string to output

     This routine writes a null-terminated string to the stream.  It
calls stream-&gt;dtb-&gt;soutr, which normally points to tcp_soutr() but can
be set to some other function.


long net_sout (NETSTREAM *stream,char *string,unsigned long size);
	stream	network stream to write
	string	string to output
	size	length of string in octets

     This routine writes a string of length size to the stream.  It
calls stream-&gt;dtb-&gt;sout, which normally points to tcp_sout() but can be
set to some other function.


void net_close (NETSTREAM *stream);
	stream	stream to close

     This routine closes the stream.  It calls stream-&gt;dtb-&gt;close, which
normally points to tcp_close() but can point to some other function.


char *net_host (NETSTREAM *stream);
	stream	stream to inspect

     This routine returns the remote host name of the stream.  It calls
stream-&gt;dtb-&gt;host, which normally points to tcp_host() but can point
to some other function.


unsigned long net_port (NETSTREAM *stream);
	stream	stream to inspect

     This routine returns the remote port number of the stream.  It calls
stream-&gt;dtb-&gt;port, which normally points to tcp_port() but can point
to some other function.


char *net_localhost (NETSTREAM *stream);
	stream	stream to inspect

     This routine returns the local host name of the stream.  It calls
stream-&gt;dtb-&gt;localhost, which normally points to tcp_localhost() but can
point to some other function.

		  Subscription Management Functions

long sm_subscribe (char *mailbox);
	mailbox	mailbox name to subscribe

     This function adds the given mailbox name to the local subscription
list, and returns T if successful, NIL if failure.


long sm_unsubscribe (char *mailbox);
	mailbox	mailbox name to unsubscribe

     This function removes the given mailbox name from the local
subscription list, and returns T if successful, NIL if failure.

char *sm_read (void **sdb);
	sdb	data to use in subsequent calls, or NIL if first call

     This function returns the local subscription list as null
terminated strings.  Each call returns the next element in the list.
The first call should be with sdb pointing to a NIL pointer; this will
be filled in for subsequent calls.  At the last call, NIL will be
returned.

		    Miscellaneous Utility Functions

char *ucase (char *string);
	string	string to convert

     This function converts each lowercase character of the specified
string to uppercase and returns the string.


char *lcase (char *string);
	string	string to convert

     This function converts each uppercase character of the specified
string to lowercase and returns the string.


char *cpystr (char *string);
	string	string to copy

 This function makes a copy of the string from free storage and returns
the copy.


long find_rightmost_bit (long *valptr);
	valptr	pointer to value to search

      This function returns -1 if the 32-bit value pointed to by valptr
is non-zero, otherwise it returns the bit number (0 = LSB, 31 = MSB) of
the right-most bit in that value.  This is used to convert from the bits
in the cache's userflags item to an index into the stream's userFlags
array of flag texts.


long min (long i,long j);
	i	first argument
	j	second argument

      This function returns the minimum of the two integers.

long max (long i,long j);
	i	first argument
	j	second argument

     This function returns the maximum of the two integers.

long search (char *s,long c,char *pat,long patc);
	s	string to search
	c	size of string
	pat	pattern to search in string
	patc	size of pattern

      This function does a fast case-independent search for the given
pattern in pat (length patc) in base string s, and returns T if the
pattern is found in the string.


long pmatch (char *s,char *pat,delim);
long pmatch_full (char *s,char *pat,delim);
	s	string to match
	pat	wildcard (* and %) to match in pattern
	delim	hierarchy delimiter

      This function returns T if the given wildcard pattern matches the
string in s with hierarchy delimiter delim.  Otherwise NIL is returned.


long dmatch (char *s,char *pat,char delim);
	s	string to match
	pat	wildcard (* and %) to match in pattern
	delim	hierarchy delimiter

     This function returns T if the given wildcard pattern matches the
directory.  If not, then none of the elements in the directory are
considered for recursive checking with pmatch_full().

			     SMTP Functions

SMTPSTREAM *smtp_open (char **hostlist,long debug);
	hostlist vector of SMTP server host names to try
	debug	non-zero if want protocol telemetry debugging

      This function opens an SMTP connection to a one of the hosts in the
host list and if successful returns a stream suitable for use by the
other SMTP functions.  The hosts are tried in order until a connection is
successfully opened.  If debug is non-NIL, protocol telemetry is logged
via mm_dlog().  NIL is returned if this function fails to open a
connection to any of the hosts in the list.

void smtp_close (SMTPSTREAM *stream);
	stream	stream to close

     This function closes the SMTP stream and frees all resources
associated with it that it may have created.

long smtp_mail (SMTPSTREAM *stream,char *type,ENVELOPE *msg,BODY *body);
	stream	stream to transmit mail
	type	mail type (MAIL, SEND, SAML, SOML)
	msg	message envelope
	body	message body

      This function negotiates an SMTP transaction of the specified type
(one of &quot;MAIL&quot;, &quot;SEND&quot;, &quot;SAML&quot;, or &quot;SOML&quot;) to deliver the specified
message.  This function returns T if success or NIL if there is any
failure.  The text reason for the failure is in stream-&gt;reply item; if
it is associated with a recipient it is also in that address'
address-&gt;error item.


void smtp_debug (SMTPSTREAM *stream);
	stream	stream to enable debugging telemetry

      This function enables SMTP protocol telemetry logging for this
stream.  All SMTP protocol operations are passed to the application via
the mm_dlog() facility.


void smtp_nodebug (SMTPSTREAM *stream);
	stream	stream to disable debugging telemetry

      This function disables SMTP protocol telemetry logging for this
stream.


typedef void (*smtpverbose_t) (char *buffer);
	buffer	pointer to verbose reply buffer

     This is the argument to the SET_SMTPVERBOSE mail_parmameter() call.
If this function pointer is non-NIL, then if a verbose SMTP response
(with SMTP code less than 100) is received, this function is called with
that response text as its argument.

			     NNTP Functions

NNTPSTREAM *nntp_open (char **hostlist,long debug);
	hostlist vector of NNTP server host names to try
	debug	non-zero if want protocol telemetry debugging

      This function opens an NNTP connection to a one of the hosts in the
host list and if successful returns a stream suitable for use by the
other MTP functions.  The hosts are tried in order until a connection is
successfully opened.  If debug is non-NIL, protocol telemetry is logged
via mm_dlog().  NIL is returned if this function fails to open a
connection to any of the hosts in the list.


void nntp_close (NNTPSTREAM *stream);
	stream	stream to close

     This function closes the NNTP stream and frees all resources
associated with it that it may have created.


long nntp_mail (NNTPSTREAM *stream,ENVELOPE *msg,BODY *body);
	stream	stream to transmit mail
	msg	message envelope
	body	message body

      This function negotiates an NNTP posting transaction to deliver
the specified news message.  This function returns T if success or NIL
if there is any failure.  The text reason for the failure is in
stream-&gt;reply item; if it is associated with a recipient it is also in
that address' address-&gt;error item.

		      RFC 822 Support Functions

     Although rfc822.c contains several additional functions besides
these, only the functions documented here should be used by
applications.  The other functions are for internal use only.


void rfc822_header (char *header,ENVELOPE *env,BODY *body);
	header	buffer to write RFC 822 header
	env	message ENVELOPE (used to obtain RFC 822 information)
	body	message BODY (used to obtain MIME information)

     This function writes an RFC 822 format header into header based
on the information in the envelope and body.  The header buffer must
be large enough to contain the full text of the resulting header.


void rfc822_write_address (char *dest,ADDRESS *adr);
	dest	buffer to write address list
	adr	RFC 822 ADDRESS list

     This function writes an RFC 822 format address list into dest
based on the information in adr.  The dest buffer must be large enough
to contain the full text of the resulting address list.

void rfc822_parse_msg (ENVELOPE **en,BODY **bdy,char *s,unsigned long i,
		       STRING *b,char *host,char *tmp);
	en	destination pointer where message ENVELOPE will be stored
	bdy	destination pointer where message BODY will be stored
	s	RFC 822 header to parse (character string)
	i	length of RFC 822 header
	b	stringstruct of message body
	host	default host name if an address lacks an @host.
	temp	scratch buffer, must be long enough to hold unwound
		 header lines (a buffer that is i octets long is OK)

     This function parses the RFC 822 header pointed to by s with body
pointed to by string structure b into the specified destination
envelope and body pointers, using host as the default host name and
tmp as a scratch buffer.  New ENVELOPE and BODY structures are
created; when finished with them the application must free them with
mail_free_envelope() and mail_free_body().  Any parsing errors are
noted via the mm_log() mechanism using log type PARSE.


void rfc822_parse_adrlist (ADDRESS **lst,char *string,char *host);
	lst	destination pointer where ADDRESS will be stored
	string	string of addresses to parse
	host	default host name if an address lacks an @host.

     This function parses the address list in the given string into an
address list in lst.  Any addresses missing a host name are have the
host name defaulted from the host argument.  If the destination list
is non-empty it appends the new addresses to the list.  Any parsing
errors are noted via the mm_log() mechanism using log type PARSE.

long rfc822_output (char *t,ENVELOPE *env,BODY *body,soutr_t f,void *s,
		    long ok8bit);
	t	scratch buffer, large enough to hold message header
	env	message ENVELOPE
	body	message BODY
	f	I/O function to write to
	s	stream for I/O function f
	ok8bit	non-zero if OK to output 8-bit data

     This function writes the message described with the given
envelope and body.  Any body part contents of type ENCBINARY is
converted to ENCBASE64 before sending.  If ok8bit is NIL, any message
data of type ENC8BIT is converted to ENCQUOTEDPRINTABLE before
sending; if ok8bit is non-NIL then ENC8BIT data is sent as-is.  T is
returned if the function succeeds, else NIL is returned.

     The function f is typically net_soutr(), but it can be any
function which matches
  typedef long (*soutr_t) (void *stream,char *string);
where stream holds sufficient information to enable the output routine
to know where to output to, and the string is a null-terminated string
to output.  This function returns either T or NIL, and that value is
passed up to rfc822_output() for its return.


void *rfc822_base64 (char *src,unsigned long srcl,unsigned long *len);
	src	source string
	srcl	size of source string in octets
	len	pointer to where destination string length in octets
		 will be returned

     This function decodes a BASE64 body part given a source string
and its length.  The decoded body part as a sequence of binary octets
is returned, and its length is returned in len.


char *rfc822_qprint (char *src,unsigned long srcl,unsigned long *len);
	src	source string
	srcl	size of source string in octets
	len	pointer to where destination string length in octets
		 will be returned

     This function decodes a QUOTED-PRINTABLE body part given a source
string and its length.  The decoded body part as an 8-bit character
string is returned, and its length is returned in len.

	     Operating System-Dependent Public Interface

     These functions are in OS-dependent code, and are rewritten each
time c-client is ported to a new operating system.


void rfc822_date (char *date);
	date	buffer to write the date, must be large enough

     This function is called to get the current date and time in an
RFC 822 format string into the given buffer.


void *fs_get (size_t size);
	size	number of octets requested

      This function allocates and returns a block of free storage of
the specified size.  Unlike malloc(), there is no failure return; this
function must return with the requested storage.


void fs_resize (void **block,size_t size);
	block	pointer to pointer to block to be resized
	size	new size in octets

     This function resizes the free storage block, updating the
pointer if necessary.  Unlike realloc(), there is no failure return;
this function must return with the requested storage.


void fs_give (void **block);
	block	pointer to pointer to block to free

      This function releases a block of free storage allocated by
fs_get().  It also erases the block pointer, so it isn't necessary to
do this in the application.


void fatal (char *string);
	string	message string

      This function is called when an &quot;impossible&quot; error is detected
and the client wishes to crash.  The string should contain a reason.


char *strcrlfcpy (char **dst,long *dstl,char *src,long srcl);
	dst	pointer to destination string pointer
	dstl	pointer to destination string size
	src	source strin
	srcl	source string size

      This function is called to copy into a destination string dst of
size dstl (resized if necessary), a CRLF newline form string from
local format string src of size srcl.


TCPSTREAM *tcp_open (char *host,long port);
TCPSTREAM *tcp_aopen (char *host,char *service);
char *tcp_getline (TCPSTREAM *stream);
long tcp_getbuffer (TCPSTREAM *stream,long size,char *buffer);
long tcp_soutr (TCPSTREAM *stream,char *string);
void tcp_close (TCPSTREAM *stream);
char *tcp_host (TCPSTREAM *stream);
unsigned long tcp_port (TCPSTREAM *stream);
char *tcp_localhost (TCPSTREAM *stream);

     These functions are TCP-specific versions of the more general
net_xxx() functions.  These should not be called directly by
applications.


char *tcp_clienthost (char *dst);
	dst	destination string buffer

     This function should be called only by a server called by inetd
or similar mechanism which maps standard input to a network socket.
It returns the host name of the other end (e.g. the client of a
server) using the given string buffer, or NIL if it can't get this
information.

			Main Program Callbacks

     All applications which use the c-client must have the following
callbacks to handle events from c-client.  Note that in any callback
which involves a mail stream, the stream is locked and you can not
recursively call c-client from the callback.  This may also be true in
callbacks which do not have a stream; in general, the rule is &quot;do not
call c-client, especially any mail_xxx() function, from a c-client
callback&quot;.


void mm_flags (MAILSTREAM *stream,unsigned long number);
	stream	stream where event happened
	number	message number

     This function is called when c-client manipulates the flags for
the given message number.  This alerts the application that it may
need to inspect that message's flags to see if there are any
interesting changes.


void mm_status (MAILSTREAM *stream,char *mailbox,MAILSTATUS *status);
	stream	stream where event happened
	mailbox	mailbox name for this status
	status	MAILSTATUS structure with message status

     This function is called when c-client reports status of a mailbox
(generally as the result of a mail_status() function call).  The
returned MAILSTATUS structure has the following members:

long flags;			validity flags.  These are the same as
				 the SA_xxx option flags in the
				 mail_status() call, and they indicate
				 which of the other members of the
				 MAILSTATUS structure have usable data
				 (i.e. if SA_MESSAGES is not set, do
				 not believe status-&gt;messages!!).
unsigned long messages;		number of messages if SA_MESSAGES
unsigned long recent;		number of recent messages if SA_RECENT
unsigned long unseen;		number of unseen messages if SA_UNSEEN
unsigned long uidnext;		next UID to be assigned if SA_UIDNEXT
unsigned long uidvalidity;	UID validity value if SA_UIDVALIDITY


void mm_searched (MAILSTREAM *stream,unsigned long number);
	stream	stream where event happened
	number	message number

     This function is called to notify the main program that this
message number matches a search (generally as the result of a
mail_search_full() function call).


void mm_exists (MAILSTREAM *stream,unsigned long number);
	stream	stream where event happened
	number	message number

     This function is called to notify the main program that there are
this many messages in the mailbox.  It is also used to notify the main
program of new mail, by announcing a higher number than the main
program was previously aware.


void mm_expunged (MAILSTREAM *stream,unsigned long number);
	stream	stream where event happened
	number	message number

     This function is called to notify the main program that this
message number has been expunged from the mail file and that all
subsequent messages are now referenced by a message number one less
than before.  This implicitly decrements the number of messages in the
mailbox.


void mm_list (MAILSTREAM *stream,char delim,char *name,long attrib);
	stream	stream where event happened
	delim	hierarchy delimiter
	name	mailbox name
	attrib	mailbox attributes

     This function is called to notify the main program that this
mailbox name matches a mailbox listing request (generally as the
result of a mail_list() function call).  The hierarchy delimiter is a
character that separates out levels of hierarchy in mailbox names.
The attributes are a bit mask with one of the following:
	LATT_NOINFERIORS
			it is not possible for there to be any
			 hierarchy inferiors to this name (that is,
			 this name followed by the hierarchy delimiter
			 and additional name characters).
	LATT_NOSELECT	this is not a mailbox name, just a hierarchy
			 level, and it may not be opened by mail_open()
	LATT_MARKED	this mailbox may have recent messages
	LATT_UNMARKED	this mailbox does not have any recent messages


void mm_lsub (MAILSTREAM *stream,char delim,char *name,long attrib);
	stream	stream where event happened
	delim	hierarchy delimiter
	name	mailbox name
	attrib	mailbox attributes


     This function is called to notify the main program that this
mailbox name matches a subscribed mailbox listing request (generally
as the result of a mail_lsub() function call).  The hierarchy
delimiter is a character that separates out levels of hierarchy in
mailbox names.  The attributes are a bit mask with one of the
following:
	LATT_NOINFERIORS
			it is not possible for there to be any
			 hierarchy inferiors to this name (that is,
			 this name followed by the hierarchy delimiter
			 and additional name characters).
	LATT_NOSELECT	this is not a mailbox name, just a hierarchy
			 level, and it may not be opened by mail_open()
	LATT_MARKED	this mailbox may have recent messages
	LATT_UNMARKED	this mailbox does not have any recent messages


void mm_notify (MAILSTREAM *stream,char *string,long errflg);
	stream	stream where event happened
	string	message string
	errflg	message error level

     This function is called to deliver a stream-oriented message
event.  This is the mechanism by which any IMAP response codes for any
application (e.g. TRYCREATE) are delivered to the application.
No newline is included in the string, so this function has to output
its own.

     The message error level is one of the following:

	NIL	normal operation.  The text is `babble' that may be
		interesting to the user, e.g. the greeting message
		from a server.

	WARN	A warning event.  This event should be displayed to
		the user.  Examples: a mailbox rewrite failed because
		of disk full, but the previous mailbox contents were
		recovered.

	ERROR	An error event.  This event should be displayed to
		the user, or at least logged someplace.  This type of
		error shouldn't happen, and so should be called to the
		attention of support staff.  Whatever happened has
		probably disrupted the user's work.  Examples: an
		untagged BAD from an IMAP server.


void mm_log (char *string,long errflg);
	string	message string
	errflg	message error level

      This function is called to deliver a log message.  No newline is
included in the string, so this function has to output its own.  In
general, it is intended that these messages are logged someplace, and
possibly shown to the user.

     The message error level is one of the following:

	NIL	normal operation.  The text is `babble' that may be
		interesting to the user, e.g. &quot;Expunged 3 messages&quot;.

	PARSE	An RFC 822 parsing error.  Since bogus headers are
		all-too-common in the real world, these can often be
		ignored on the &quot;garbage in, garbage out&quot; princple.
		However, since surprising results can be yielded when
		trying to parse garbage, this message should be logged
		somewhere so it can be figured out what happened.

	WARN	A warning event.  This event should be displayed to
		the user.  It occurs when an error condition has
		happened, but c-client knows what to do to recover.
		Examples: &quot;Can't open read-write, so opening
		read-only&quot;, &quot;Empty mailbox&quot;, &quot;Login failed, try
		again&quot;, &quot;Waiting for mailbox to become unlocked&quot;,
		&quot;IMAP protocol error&quot;.  Although a user should be
		told about a warning, it's generally not necessary
		to interrupt the flow of her work (e.g. it's alright
		to display the warning in a scrolling window, but
		not necessary to require the user to do anything).

	ERROR	An error event.  This event should be displayed to
		the user, or at least logged someplace.  This is a
		serious error condition occured that aborted the
		requested operation and possibly also aborted the mail
		stream.  This ranges from normal error conditions such
		as &quot;Can't open mailbox&quot;, &quot;too many login failures, go
		away&quot; to bizarre conditions such as &quot;Apparent new mail
		appeared in the mailbox that doesn't look like mail,
		program aborting&quot;.  Errors must be called to the
		user's attention, and probably should require some
		sort of acknowledgement (e.g. answering a modal panel)
		before the application proceeds.


void mm_dlog (char *string);
	string message string

      This function is called to deliver a debugging telemetry
message.  No newline is included in the string, so this function has
to output its own.  This is called only when debugging is enabled.


void mm_login (NETMBX *mb,char *user,char *pwd,long trial);
	mb	parsed mailbox specification
	user	pointer to where to return user name
	pwd	pointer to where to return password
	trial	number of prior login attempts

      This function is called to get a user name and password for the
given network mailbox.  It stores the user name and password in the
strings pointed to by the appropriate arguments.  The trial argument
is the number of attempts to perform the login and is initially zero
(e.g. for a default username and password login functionality).  It is
incremented for each subsequent trial until the maximum number of
trials are made.


void mm_critical (MAILSTREAM *stream);
	stream	stream where event happened

      This function is called to alert the application that c-client
is about to run some critical code on that stream that may result in a
clobbered mail file if it is interrupted.  It may be desirable to
disable CTRL/C, etc. during this time.


void mm_nocritical (MAILSTREAM *stream);
	stream	stream where event happened

      This function is called to alert the application that c-client
is no longer running critical code on that stream that may result in a
clobbered mail file if it is interrupted.


long mm_diskerror (MAILSTREAM *stream,long errcode,long serious);
	stream	stream where event happened
	errcode	OS error code for disk error
	serious	non-zero if c-client can not undo the operation (and
		 thus must retry to avoid mail file damage)

      This function is called to alert the application that the
c-client has encountered an unrecoverable write error when trying to
update the mail file.  errcode contains the system error code.  If
serious is non-zero, then it is probable that the disk copy of the
mailbox has been damaged.

     The return value from this function is the abort flag; if serious
is zero and the abort flag is non-zero, the operation is aborted.  If
the abort flag is zero or if serious was non-zero, a return from this
function will retry the failing operation.


void mm_fatal (char *string);
	string	message string

      This function is called from the fatal() routine in the
operating system code to notify the main program that it is about to
crash.  The string contains a reason.  At the very minimum, the main
program should do something like
 mm_log (string,ERROR);
and then return.  No newline is included in the string, so this
function has to output its own.

			     Driver interface

     When writing a new driver for the c-client, you must provide a
DRIVER stucture giving a dispatch vector between MAIL and the driver.
The DRIVER dispatch vector is described in mail.h.

char *name;
     Name by which the driver is known to c-client.

unsigned long flags;
     Attribute flags for this driver:
	DR_DISABLE	This driver is currently disabled.
	DR_LOCAL	This driver deals with local mailboxes; if
			 this is off it deals with mailboxes over a
			 network.
	DR_MAIL		This driver supports e-mail messages.
	DR_NEWS		This driver supports netnews messages
	DR_READONLY	This driver only allows read-only access;
			 mail_setflag(), mail_expunge(), etc. are
			 no-ops.
	DR_NOFAST	This driver does not implement mail_fetchfast()
			 in a fast way (e.g. it may have to fetch the
			 entire message text over a network to
			 calculate sizes).
	DR_NAMESPACE	This driver accepts and uses namespace format
			 names.
	DR_LOWMEM	This driver is designed for systems with very
			 limited amounts of memory (e.g. DOS) and
			 support routines called by this driver should
			 try not to use much memory.

DRIVER *next;
     Pointer to the next driver which this application supports (or NIL if
this is the last driver).  Drivers are lunk together via the mail_link()
function.

DRIVER *driver_valid (char *mailbox);
     This function returns a pointer to the driver's DRIVER dispatch
vector iff this driver accepts the given name as a valid mailbox for this
driver.  Otherwise, it returns the value of the next driver's
driver_valid() or NIL if there is no next driver.  In other words, calling
driver_valid() for the first driver will return the driver dispatch vector
for the driver which supports this type of mailbox.

void *driver_parameters (long function,void *value);
     This function implements mail_parameters() for this driver.

void driver_scan (MAILSTREAM *stream,char *ref,char *pat,char *contents);
     This function implements mail_scan() for this driver.

void driver_list (MAILSTREAM *stream,char *ref,char *pat);
     This function implements mail_list() for this driver.

void driver_lsub (MAILSTREAM *stream,char *ref,char *pat);
     This function implements mail_lsub() for this driver.

long driver_subscribe (MAILSTREAM *stream,char *mailbox);
     This function implements mail_subscribe() for this driver.

long driver_unsubscribe (MAILSTREAM *stream,char *mailbox);
     This function implements mail_unsubscribe() for this driver.

long driver_create (MAILSTREAM *stream,char *mailbox);
     This function implements mail_create() for this driver.

long driver_delete (MAILSTREAM *stream,char *mailbox);
     This function implements mail_delete() for this driver.

long driver_rename (MAILSTREAM *stream,char *old,char *new);
     This function implements mail_rename() for this driver.

long driver_status (MAILSTREAM *stream,char *mailbox,long flags);
     This function implements mail_status() for this driver.

MAILSTREAM *driver_open (MAILSTREAM *stream);
     This function opens the mailbox identified by the given stream.  It
may use the data on the stream and create additional data on stream-&gt;local
as necessary.  It should return the given stream unless it failed to open
the mailbox, in which case it should return NIL.

void driver_close (MAILSTREAM *stream,long options);
     This function implements mail_close() for this driver.

void driver_fetchfast (MAILSTREAM *stream,char *sequence,long flags);
     This function implements mail_fetchfast() for this driver.

void driver_fetchflags (MAILSTREAM *stream,char *sequence,long flags);
     This function implements mail_fetchflags() for this driver.

ENVELOPE *driver_fetchstructure (MAILSTREAM *stream,unsigned long msgno,
				 BODY **body,long flags);
     This function implements mail_fetchstructure() for this driver.

char *driver_fetchheader (MAILSTREAM *stream,unsigned long msgno,
			  STRINGLIST *lines,unsigned long *len,long flags);
     This function implements mail_fetchheader() for this driver.

char *driver_fetchtext (MAILSTREAM *stream,unsigned long msgno,
			unsigned long *len,long flags);
     This function implements mail_fetchtext() for this driver.

char *driver_fetchbody (MAILSTREAM *stream,unsigned long msgno,char *section,
			unsigned long *len,long flags);
     This function implements mail_fetchbody() for this driver.

void driver_setflag (MAILSTREAM *stream,char *sequence,char *flag,long flags);
     This function implements mail_setflag() for this driver.

void driver_clearflag (MAILSTREAM *stream,char *sequence,char *flag,
		       long flags);
     This function implements mail_clearflag() for this driver.

void driver_search (MAILSTREAM *stream,char *charset,SEARCHPGM *pgm,
		    long flags);
     This function implements mail_search() for this driver.

unsigned long *driver_sort (MAILSTREAM *stream,char *charset,SEARCHPGM *spg,
			    SORTPGM *pgm,long flags);
     This function implements mail_sort() for this driver.

void *driver_thread (MAILSTREAM *stream,char *seq,long function,long flag);
     This dispatch is reserved for a future threading capability.

long driver_ping (MAILSTREAM *stream);
      This function implements mail_ping() for this driver.

void driver_check (MAILSTREAM *stream);
      This function implements mail_check() for this driver.

void driver_expunge (MAILSTREAM *stream);
      This function implements mail_expunge() for this driver.

long driver_copy (MAILSTREAM *stream,char *sequence,char *mailbox,
		  long options);
      This function implements mail_copy() for this driver.

long driver_append (MAILSTREAM *stream,char *mailbox,char *flags,char *date,
		    STRING *message);
      This function implements mail_append() for this driver.

void driver_gc (MAILSTREAM *stream,long gcflags);
      This function implements mail_gc() for this driver.

			 Driver Support Functions

void mail_searched (MAILSTREAM *stream,unsigned long msgno);
	stream	stream where event happened
	msgno	message number

     This function is called by the driver to notify c-client that this
message number matches a search.  It invokes the main program's
mm_searched() function.

void mail_exists (MAILSTREAM *stream,unsigned long nmsgs);
	stream	stream where event happened
	nmsgs	number of messages

     This function is called by the driver to notify c-client that this
message number exists (i.e. there are this many messages in the mailbox).
It invokes the main program's mm_exists() function.

void mail_recent (MAILSTREAM *stream,unsigned long recent);
	stream	stream where event happened
	recent	number of messages

      This function is called by the driver to notify c-client that this
many messages are &quot;recent&quot; (i.e. arrived in the mailbox since the previous
time the mailbox was opened).

void mail_expunged (MAILSTREAM *stream,unsigned long msgno);
	stream	stream where event happened
	msgno	number of messages

      This function is called by the driver to notify MAIL that this
message number has been expunged from the mail file and that all subsequent
messages are now referenced by a message number one less than before.  It
invokes the main program's mm_expunged() function.

void mail_lock (MAILSTREAM *stream);
	stream	stream where event happened
      This function sets the stream lock.  It is an error to set the stream
lock if the stream is already locked.

      This is mainly used to catch errors due to a callback function
(e.g. mm_exists) inadvertantly recursing back to the MAIL routines and
establishing an infinite recursion.  Normally, drivers will set the lock
prior to calling one of the callback functions above or, more likely, in
the beginning of the driver's non-reentrant &quot;do operation&quot; section.  In the
IMAP4 driver, the stream lock is set when entering imap_send() and cleared
on exit.

void mail_unlock (MAILSTREAM *stream);
	stream	stream where event happened

     This function releases the stream lock.  It is an error to release the
stream lock if the stream is not locked.
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               </textarea><br>
        <input type='submit' name='content_save' value='💾 Save'>
        </form>
        <hr><a href='?go=%2Fhome%2Fmba%2Fpublic_html%2F-20250808174531'>🔙 Back</a>