Short Contents
**************

GNU Mailutils
1 Introduction
2 Mailutils Programs
3 Mailutils Libraries
4 Sieve Language
5 Reporting Bugs
6 Getting News About GNU Mailutils
7 Acknowledgement
Appendix A References
Appendix B Date Input Formats
Appendix C Configuring Help Summary
Appendix D GNU Free Documentation License
Function Index
Variable Index
Keyword Index
Program Index
Concept Index


Table of Contents
*****************

GNU Mailutils
1 Introduction
  1.1 What this Book Contains
  1.2 A bit of History, and why use this package?
2 Mailutils Programs
  2.1 Command Line
    2.1.1 Basic Notions About Command Line Options
    2.1.2 Options That are Common for All Utilities.
  2.2 Mailutils Configuration File
    2.2.1 Configuration File Syntax
      2.2.1.1 Comments
      2.2.1.2 Statements
      2.2.1.3 Block Statements
    2.2.2 Include Statement
    2.2.3 Logging Statement
    2.2.4 Debug Statement
    2.2.5 Mailbox Statement
    2.2.6 Locking Statement
    2.2.7 Mailer Statement
    2.2.8 ACL Statement
    2.2.9 Tcp-wrappers Statement
    2.2.10 Description
    2.2.11 Server Settings
      2.2.11.1 General Server Configuration
      2.2.11.2 Server Statement
    2.2.12 Auth Statement
    2.2.13 PAM Statement
    2.2.14 Virtdomain Statement
    2.2.15 Radius Statement
    2.2.16 SQL Statement
    2.2.17 Description
    2.2.18 LDAP Statement
    2.2.19 TLS Statement
    2.2.20 GSASL Statement
  2.3 `frm' and `from' -- List Headers from a Mailbox
  2.4 `mail' -- Send and Receive Mail
    2.4.1 Invoking `mail'
    2.4.2 How to Specify Message Sets
    2.4.3 Composing Mail
    2.4.4 Reading Mail
    2.4.5 Scripting
    2.4.6 How to Alter the Behavior of `mail'
    2.4.7 Personal and System-wide Configuration Files
  2.5 `messages' -- Count the Number of Messages in a Mailbox
  2.6 `movemail' -- Moves Mail from the User Maildrop to the Local File
    2.6.1 Movemail Configuration
    2.6.2 Movemail Options
    2.6.3 Summary of Movemail Usage
  2.7 `readmsg' -- Extract Messages from a Folder
    2.7.1 Invocation of `readmsg'.
    2.7.2 Configuration of `readmsg'.
  2.8 `sieve'
    2.8.1 A Sieve Interpreter
    2.8.2 A Sieve to Scheme Translator and Filter
  2.9 `guimb' -- A Mailbox Scanning and Processing Language
  2.10 maidag
    2.10.1 Using `maidag' with Sendmail.
    2.10.2 Using `maidag' with Exim.
    2.10.3 Using `maidag' with MeTA1.
    2.10.4 Mailbox Quotas
      2.10.4.1 Keeping Quotas in DBM File
      2.10.4.2 Keeping Quotas in SQL Database
    2.10.5 Maidag Scripting
      2.10.5.1 Sieve Maidag Filters
      2.10.5.2 Scheme Maidag Filters
    2.10.6 Forwarding
    2.10.7 Delivering Messages to a URL.
    2.10.8 Remote Mailbox Delivery
    2.10.9 Maidag Configuration File Summary
  2.11 `mail.local' -- Deliver Mail to the Local UNIX Mailbox
    2.11.1 Invoking `mail.local'
    2.11.2 Mail.local Configuration
  2.12 `mail.remote' -- Pseudo-Sendmail Interface for Mail Delivery
  2.13 mimeview
    2.13.1 Mimeview Invocation
    2.13.2 Mimeview Config
  2.14 POP3 Daemon
    2.14.1 Login delay
    2.14.2 Auto-expire
    2.14.3 Bulletins
    2.14.4 Pop3d Configuration
    2.14.5 Command line options
  2.15 IMAP4 Daemon
    2.15.1 Namespace
    2.15.2 Configuration of `imap4d'.
    2.15.3 Starting `imap4d'
  2.16 Comsat Daemon
    2.16.1 Starting `comsatd'
    2.16.2 Configuring `comsatd'
      2.16.2.1 General Settings
      2.16.2.2 Security Settings
    2.16.3 A per-user Configuration File
  2.17 MH -- The MH Message Handling System
    2.17.1 Major differences between Mailutils MH and other MH implementations
      2.17.1.1 New and Differing MH Format Specifications
      2.17.1.2 New MH Profile Variables
      2.17.1.3 Differences in MH Program Behavior
  2.18 `mailutils-config' -- Get the Information about the Mailutils Build
3 Mailutils Libraries
  3.1 Framework
    3.1.1 Folder
    3.1.2 Mailbox
    3.1.3 Mailer
    3.1.4 Message
    3.1.5 Envelope
    3.1.6 Headers
    3.1.7 Body
    3.1.8 Attribute
    3.1.9 Stream
    3.1.10 Iterator
    3.1.11 Authenticator
    3.1.12 Address
    3.1.13 Locker
    3.1.14 URL
    3.1.15 Parse822
    3.1.16 Mailcap
  3.2 Authentication Library
    3.2.1 Data Types
    3.2.2 Initializing `libmuauth'
    3.2.3 Module Creation and Destruction
    3.2.4 Obtaining Authorization Information
    3.2.5 Existing Modules
    3.2.6 Using `libmuauth' in Your Programs
  3.3 Mailutils to Scheme Interface
    3.3.1 Address Functions
    3.3.2 Mailbox Functions
    3.3.3 Message Functions
    3.3.4 MIME Functions
    3.3.5 Logging Functions
    3.3.6 Other Functions
    3.3.7 Direct Linking
    3.3.8 Dynamic Linking
  3.4 Sieve Library
    3.4.1 Sieve Data Types
    3.4.2 Manipulating the Sieve Machine
    3.4.3 Logging and Diagnostic Functions
    3.4.4 Symbol Space Functions
    3.4.5 Memory Allocation
    3.4.6 Compiling and Executing the Script
    3.4.7 Writing Loadable Commands
4 Sieve Language
  4.1 Lexical Structure
  4.2 Syntax
    4.2.1 Commands
    4.2.2 Actions Described
    4.2.3 Control Flow
    4.2.4 Tests and Conditions
  4.3 Preprocessor
  4.4 Require Statement
  4.5 Comparators
  4.6 Tests
    4.6.1 Built-in Tests
    4.6.2 External Tests
  4.7 Actions
    4.7.1 Built-in Actions
    4.7.2 External Actions
  4.8 GNU Extensions
5 Reporting Bugs
6 Getting News About GNU Mailutils
7 Acknowledgement
Appendix A References
Appendix B Date Input Formats
  B.1 General date syntax
  B.2 Calendar date items
  B.3 Time of day items
  B.4 Time zone items
  B.5 Day of week items
  B.6 Relative items in date strings
  B.7 Pure numbers in date strings
  B.8 Seconds since the Epoch
  B.9 Specifying time zone rules
  B.10 Authors of `get_date'
Appendix C Configuring Help Summary
Appendix D GNU Free Documentation License
  D.1 ADDENDUM: How to use this License for your documents
Function Index
Variable Index
Keyword Index
Program Index
Concept Index


GNU Mailutils
*************

This edition of the `GNU Mailutils Manual', last updated on 26 December
2008, documents GNU Mailutils Version 2.0.

1 Introduction
**************

GNU Mailutils contains a series of useful mail clients, servers, and
libraries. These are the primary mail utilities of the GNU system.
Specifically, this package contains a POP3 server, an IMAP4 server, and
a Sieve mail filter. It also provides a POSIX `mailx' client, and a
collection of other tools. All utilities can manipulate the mailboxes
of various formats, both local, stored on the hard disk, and remote,
accessed via network protocols, such as POP3 or IMAP4.

   The GNU Mailutils libraries supply a rich set of primitives for
handling electronic mail in programs written in C, C++ or Scheme.

   This software is part of the GNU Project and belongs to the Free
Software Foundation. All libraries are licensed using the GNU LGPL.
The documentation is licensed under the GNU FDL, and everything else is
licensed using the GNU GPL.

1.1 What this Book Contains
===========================

This book addresses a wide audience of both system administrators and
users that aim to use Mailutils programs, and programmers who wish to
use Mailutils libraries in their programs. Given this audience, the
book is divided in three major parts.

   The first part provides a detailed description of each Mailutils
utility, and advices on how to use them in various situations. This
part is intended for users and system administrators who are using
Mailutils programs. If you are not interested in programming using
Mailutils, this is the only part you need to read.

   Subsequent parts address programmers.

   The second part is a tutorial which provides an introduction to
programming techniques for writing mail applications using GNU
Mailutils.

   Finally, the third part contains a complete Mailutils library
reference.

   This version of the book is not finished. The places that may
contain inaccurate information carry prominent notices stating so.  For
updated versions of the documentation, visit
`http://www.gnu.org/software/mailutils/manual'. If you have any
questions, feel free to ask them at the mailing list
<bug-mailutils@gnu.org>.

1.2 A bit of History, and why use this package?
===============================================

     (_The information in this node may be obsolete or otherwise
     inaccurate._ This message will disappear, once this node revised.)

This package started off to try and handle large mailbox files more
gracefully then current POP3 servers did. While it handles this task,
it also allows you to support a variety of different mailbox formats
without any real effort on your part. Also, if a new format is added at
a later date, your program will support that new format automatically
as soon as it is compiled against the new library.

2 Mailutils Programs
********************

GNU Mailutils provides a broad set of utilities for handling electronic
mail. These utilities address the needs of both system administrators
and users.

   All utilities are built around a single core subsystem and share many
common aspects. All of them are able to work with almost any existing
mailbox formats. They use a common configuration file syntax, and their
configuration files are located in a single subdirectory.

   In this chapter we will discuss each utility, and give some advices
on how to use them in various real life situations.

   First of all we will describe command line and configuration file
syntax.

2.1 Command Line
================

2.1.1 Basic Notions About Command Line Options
----------------------------------------------

Many command line options have two forms, called short and long forms.
Both forms are absolutely identical in function; they are
interchangeable.

   The "short" form is a traditional form for UNIX utilities.  In this
form, the option consists of a single dash, followed by a single
letter, e.g. `-c'.

   Short options which require arguments take their arguments
immediately following the option letter, optionally separated by white
space. For example, you might write `-f name', or `-fname'.  Here, `-f'
is the option, and `name' is its argument.

   Short options which allow optional arguments take their arguments
immediately following the option letter, _without any intervening white
space characters_. This is important, so that the command line parser
might discern that the text following option is its argument, not the
next command line parameter. For example, if option `-d' took an
optional argument, then `-dname' would mean the option with its
argument (`name' in this case), and `-d name' would mean the `-d'
option without any argument, followed by command line argument `name'.

   Short options' letters may be clumped together, but you are not
required to do this. When short options are clumped as a set, use one
(single) dash for them all, e.g. `-cvl' is equivalent to `-c -v -l'.
However, only options that do not take arguments may be clustered this
way. If an option takes an argument, it can only be the last option in
such a cluster, otherwise it would be impossible to specify the
argument for it. Anyway, it is much more readable to specify such
options separated.

   The "long" option names are probably easier to memorize than their
short counterparts. They consist of two dashes, followed by a
multi-letter option name, which is usually selected to be a mnemonics
for the operation it requests. For example, `--verbose' is a long
option that increases the verbosity of a utility. In addition, long
option names can abbreviated, provided that such an abbreviation is
unique among the options understood by a given utility. For example, if
a utility takes options `--foreground' and `--forward', then the
shortest possible abbreviations for these options are `--fore' and
`--forw', correspondingly. If you try to use `--for', the utility will
abort and inform you that the abbreviation you use is ambiguous, so it
is not clear which of the options you intended to use.

   Long options which require arguments take those arguments following
the option name. There are two ways of specifying a mandatory argument.
It can be separated from the option name either by an equal sign, or by
any amount of white space characters. For example, if the `--file'
option requires an argument, and you wish to supply `name' as its
argument, then you can do so using any of the following notations:
`--file=name' or `--file name'.

   In contrast, optional arguments must always be introduced using an
equal sign.

2.1.2 Options That are Common for All Utilities.
------------------------------------------------

All GNU Mailutils programs understand a common subset of options.

`--help'
`-?'
     Display a short summary of the command line options understood by
     this utilities, along with a terse description of each.

     The output of this option consists of three major parts. First, a
     usage synopsis is displayed. For example:

          Usage: sieve [OPTION...] SCRIPT
          GNU sieve -- a mail filtering tool

     The first line tells that the `sieve' utility takes any number of
     options (brackets indicate optional part) and a single mandatory
     argument (`SCRIPT'). The second lines summarizes the purpose of
     the utility.

     Following this header is an option summary. It consists of two
     columns:

       -c, --compile-only         Compile script and exit
       -d, --debug[=FLAGS]        Debug flags
       -e, --email=ADDRESS        Override user email address

     The leftmost column contains a comma-separated list of option
     names. Short options are listed first. The options are ordered
     alphabetically. Arguments, if any, are specified after the last
     option name in the list, so that, e.g. the option `-e' in the
     example above requires an argument: `-e ADDRESS'. Optional
     arguments are enclosed in square brackets, as in `--debug' option
     in the example above.

     The rightmost column contains a short description of the option
     purpose.

     The last part of `--help' output contains some additional notices
     and lists the email address for reporting bugs.

`--usage'
     Display a short summary of options. In the contrast to the
     `--help' option, only option names and arguments are printed,
     without any textual description. For example:

          Usage: sieve [-cv?V] [--compile-only] [--debug[=FLAGS]]
                       [--email=ADDRESS] SCRIPT

   The exact formatting of the output produced by these two options is
configurable. *Note Usage Vars::, for a detailed descriptions of it.

`--version'
`-V'
     Print program version and exit.

`--show-config-options'
     Show configuration options used when compiling the package. You can
     use this option to verify if support for a particular mailbox
     format or other functionality is compiled in the binary. The
     output of this option is intended to be both machine-readable and
     understandable by humans.

   The following command line options affect parsing of configuration
files. Here we provide a short summary, the next section will describe
them in detail.

`--config-file=FILE'
     Load this configuration file, instead of the default.

`--config-help'
     Show configuration file summary.

`--config-lint'
     Check configuration file syntax and exit

`--config-verbose'
     Verbosely log parsing of the configuration files.

`--no-site-config'
     Do not load site-wide configuration file.

`--no-user-config'
     Do not load user configuration file.

2.2 Mailutils Configuration File
================================

Configuration files are the principal means of configuring any GNU
Mailutils component. When started, each utility tries to load its
configuration from the following locations, in that order:

  1. Main site-wide configuration file.

     It is named `SYSCONFDIR/mailutils.rc', where SYSCONFDIR stands for
     the system configuration directory set when compiling the package.
     You can obtain the value of SYSCONFDIR by running

          $ mailutils-config --info sysconfdir

     or

          $ PROG --show-config-options | grep SYSCONFDIR

     where PROG stands for any GNU Mailutils utility.

     The site-wide configuration file is not read if the
     `--no-site-config' command line option was given.

  2. Per-user configuration file.

     A per user configuration file is located in the user home directory
     and is named `.PROG', where PROG is the name of the utility. For
     example, the per-user configuration file for `sieve' utility is
     named `.sieve'.

     This configuration file is not read if the `--no-user-config'
     command line option was given.

  3. Additional configuration file, if specified using the
     `--config-file' command line option.

   The order in which configuration files are loaded defines the
precedence of their settings. Thus, the settings from additional
configuration file override those set in per-user configuration file.
The latter, in their turn, take precedence over the settings from the
site-wide configuration file.

   Neither site-wide nor user configuration files are required to
exist. If any or both of them are absent, GNU Mailutils does not
complain, and the utility falls back to its default settings. To make
configuration processing more verbose, use the `--config-verbose'
command line option. Here is an example of what you might get using
this option:

     imap4d: Info: parsing file `/etc/mailutils.rc'
     imap4d: Info: finished parsing file `/etc/mailutils.rc'

   Specifying this option more than once adds more verbosity to this
output. If this option is given two times, GNU Mailutils will print any
configuration file statement it parsed, along with the exact location
where it occurred (the exact meaning of each statement will be
described later in this chapter):

     imap4d: Info: parsing file `/etc/mailutils.rc'
     # 1 "/etc/mailutils.rc"
     mailbox {
     # 2 "/etc/mailutils.rc"
       mailbox-pattern maildir:/var/spool/mail;type=index;param=2;user=${user};
     # 3 "/etc/mailutils.rc"
       mailbox-type maildir;
     };
     # 6 "/etc/mailutils.rc"
     include /etc/mailutils.d;
     imap4d: Info: parsing file `/etc/mailutils.d/imap4d'
     ...

   To test configuration file without actually starting the utility,
use the `--config-lint' command line option. With this option, any
Mailutils utility exits after finishing parsing of the configuration
files. Any errors occurred during parsing are displayed on the standard
error output. This option can be combined with `--config-verbose' to
obtain more detailed output.

   The `--config-help' command line option produces on the standard
output the summary of all configuration statements understood by the
utility, with detailed comments and in the form suitable for
configuration file. For example, the simplest way to write a
configuration file for, say, `imap4d' is to run

     $ imap4d --config-help > imap4d.rc

and to edit the `imap4d.rc' file with your editor of choice.

2.2.1 Configuration File Syntax
-------------------------------

Configuration files consist of a series of statements. Blanks, tabs,
newlines and comments, collectively called "white space" are ignored
except as they serve to separate tokens. Some white space is required
to separate otherwise adjacent keywords and values.

2.2.1.1 Comments
................

"Comments" may appear anywhere where white space may appear in the
configuration file. There are two kinds of comments: single-line and
multi-line comments. "Single-line" comments start with `#' or `//' and
continue to the end of the line:

     # This is a comment
     // This too is a comment

   "Multi-line" or "C-style" comments start with the two characters
`/*' (slash, star) and continue until the first occurrence of `*/'
(star, slash).

   Multi-line comments cannot be nested. However, single-line comments
are allowed to appear within a multi-line one.

2.2.1.2 Statements
..................

A "simple statement", consists of a keyword and value separated by any
amount of whitespace. Simple statement is terminated with a semicolon
(`;'), unless it contains a "here-document" (see below), in which case
semicolon is optional.

   Examples of simple statements:

     pidfile /var/run/imap4d.pid;
     transcript yes;

   A "keyword" begins with a letter and may contain letters, decimal
digits, underscores (`_') and dashes (`-').  Examples of keywords are:
`group', `identity-check'.

   A "value" can be one of the following:

number
     A number is a sequence of decimal digits.

boolean
     A boolean value is one of the following: `yes', `true', `t' or
     `1', meaning "true", and `no', `false', `nil', `0' meaning "false".

unquoted string
     An unquoted string may contain letters, digits, and any of the
     following characters: `_', `-', `.', `/', `:'.

quoted string
     A quoted string is any sequence of characters enclosed in
     double-quotes (`"'). A backslash appearing within a quoted string
     introduces an "escape sequence", which is replaced with a single
     character according to the following rules:

     Sequence             Replaced with
     \a                   Audible bell character (ASCII 7)
     \b                   Backspace character (ASCII 8)
     \f                   Form-feed character (ASCII 12)
     \n                   Newline character (ASCII 10)
     \r                   Carriage return character (ASCII
                          13)
     \t                   Horizontal tabulation character
                          (ASCII 9)
     \\                   A single backslash (`\')
     \"                   A double-quote.

     Table 2.1: Backslash escapes

        In addition, the sequence `\NEWLINE' is removed from the
     string. This allows to split long strings over several physical
     lines, e.g.:

          "a long string may be\
           split over several lines"

        If the character following a backslash is not one of those
     specified above, the backslash is ignored and a warning is issued.

        Two or more adjacent quoted strings are concatenated, which
     gives another way to split long strings over several lines to
     improve readability. The following fragment produces the same
     result as the example above:

          "a long string may be"
          " split over several lines"

  Here-document
        "Here-document" is a special construct that allows to introduce
     strings of text containing embedded newlines.

        The `<<WORD' construct instructs the parser to read all the
     lines that follow up to the line containing only WORD, with
     possible trailing blanks. Any lines thus read are concatenated
     together into a single string. For example:

          <<EOT
          A multiline
          string
          EOT

        Body of a here-document is interpreted the same way as
     double-quoted string, unless WORD is preceded by a backslash (e.g.
     `<<\EOT') or enclosed in double-quotes, in which case the text is
     read as is, without interpretation of escape sequences.

        If WORD is prefixed with `-' (a dash), then all leading tab
     characters are stripped from input lines and the line containing
     WORD. Furthermore, if `-' is followed by a single space, all
     leading whitespace is stripped from them. This allows to indent
     here-documents in a natural fashion. For example:

          <<- TEXT
              All leading whitespace will be
              ignored when reading these lines.
          TEXT

        It is important that the terminating delimiter be the only
     token on its line. The only exception to this rule is allowed if a
     here-document appears as the last element of a statement. In this
     case a semicolon can be placed on the same line with its
     terminating delimiter, as in:

          help-text <<-EOT
                  A sample help text.
          EOT;

        However, terminated semicolon after a here-document is optional.

  list
        A "list" is a comma-separated list of values. Lists are
     enclosed in parentheses. The following example shows a statement
     whose value is a list of strings:

          shared-namespace ("/home", "/var/spool/common");

        In any case where a list is appropriate, a single value is
     allowed without being a member of a list: it is equivalent to a
     list with a single member. This means that, e.g. `shared-namespace
     /home;' is equivalent to `shared-namespace (/home);'.

2.2.1.3 Block Statements
........................

A "block statement" introduces a logical group of another statements.
It consists of a keyword, followed by an optional value, and a sequence
of statements enclosed in curly braces, as shown in example below:

     tcp-wrappers {
       enable yes;
       allow-syslog-priority info;
       deny-syslog-priority notice;
     }

   The closing curly brace may be followed by a semicolon, although
this is not required.

2.2.2 Include Statement
-----------------------

An "include statement" is a special statement that causes inclusion of
a named file. This statement has the following syntax:

     include FILE;

   If FILE names a regular file, the contents of this file is included
in this point. Otherwise, if FILE names a directory, Mailutils searches
in that directory for a file whose name coincides with the name of
utility being executed, and includes this file, if it exists.

   It is a common approach to end the site-wide configuration file with
an include statement, e.g.:

     include /etc/mailutils.d;

   This allows each particular utility to have its own configuration
file. Thus. `imap4d' will read `/etc/mailutils.d/imap4d', etc.

2.2.3 Logging Statement
-----------------------

Syntax
------

     logging {
       # Set syslog facility.
       facility NAME;
       # Tag syslog messages with this string.
       tag TEXT;
     }

Description
-----------

The `logging' block statement provides configuration for programs that
use `syslog' for diagnostics. The default syslog facility is determined
at compile time, it can be inspected using the following command:

     $ mailutils-config --info log_facility

 -- Configuration: facility name
     Use syslog facility NAME. Valid argument values are: `user',
     `daemon', `auth', `authpriv', `mail', `cron', `local0' through
     `local7' (all names case-insensitive), or a facility number.

 -- Configuration: tag text
     Tag syslog messages with TEXT. By default, program name is used as
     syslog tag.

2.2.4 Debug Statement
---------------------

Syntax
------

     debug {
       # Set Mailutils debugging level.
       level SPEC;
       # Prefix debug messages with Mailutils source locations.
       line-info BOOL;
     }

Description
-----------

The `debug' statement configures debugging output. Although it is
mostly useful for Mailutils developers, it may be of interest for
casual users as well. In particular, you may use it to obtain more
information about Mailutils actions, which may help in configuring it,
or in filling a bug report.

   Debugging output is controlled by a set of levels, each of which can
be enabled or disabled independently of others. A "debugging level"
consists of a module name, which defines a Mailutils module affected by
this level, and a level number, which defines the verbosity of the
debugging output. Valid debugging levels are:

error
     Display only error messages.

trace0 through trace7
     Eight levels of verbosity, `trace0' producing less output,
     `trace7' producing maximum possible output.

prot
     Display network protocol interactions, where appropriate.

Table 2.2: Debugging levels

   The most important debugging modules are:

acl
     Debug access control lists. .

config
     Debug configuration parser and/or lexical analyzer. The following
     levels are supported:

    trace0
          Minimal information about configuration statements.

    trace2
          Trace lexical structure of the configuration files.

    trace7
          Trace execution of the configuration parser.

     Due to its specific nature, this debugging module cannot be enabled
     using `level' statement below. The `--debug-level' command line
     option should be used instead (). Alternatively, you may use the
     following hook, provided to facilitate debugging of the
     configuration parser: a "pragmatic comment" in form:

          #debug=LEVEL

     is understood as a request to set debugging level of module
     `config' to LEVEL.

ip_server
     IP based servers, such as `imap4d' and `pop3d'. This module
     supports `trace0' and `error' levels. *Note Server Settings::, for
     more information about servers.

udp_server
     UDP based servers, such as `comsatd'. This module supports
     `trace0' and `error' levels. *Note Server Settings::, for more
     information about servers.

mailbox
     Operations over mailboxes. This module supports the following
     levels: `error', `trace0', `trace1', and `proto'. The latter is
     used by remote mailbox support libraries.

sieve
     Debug Sieve parser and run-time evaluator. Currently supported
     levels are `error', `trace1' and `trace7'.

 -- Configuration: level spec
     This statement enables debugging levels given by SPEC. The
     argument is an list of debugging specifications or a string with
     specifications delimited by semicolons. The syntax of a
     specification is:

            MODULE[[:]=LEVEL]

     where MODULE is the name of a module, and LEVEL is the level to be
     set. The level may be optionally prefixed with the following
     symbols:

    `!'
          All levels except this one. E.g. `config=!trace7' means set
          all debugging levels, except `trace7' for the `config' module.

    `<'
          All levels up to and including this. The words `up to' refer
          to the position of levels in *note Table 2.2: debugging
          levels. table, so that, e.g.  `<trace2' means levels `error',
          `trace0', `trace1' and `trace2'.

     Both prefixes can be used together, in this order: `!<'. This
     means all levels except this one and ones listed before it in the
     table.

     A comma before equal sign, as in `mailbox:=<trace7' means set this
     debugging levels in all modules, invoked by this one.

     The LEVEL in the level specification can also be a comma-separated
     list of valid levels, e.g.:

             mailbox=<trace2,!<trace4

     which means "levels trace3 and trace4".

     The following example illustrates two equivalent ways of setting
     debugging level in a configuration file:

            level ("mailbox=!proto", "acl=<trace7");
            level "mailbox=!proto;acl=<trace7";

     The `--debug-level' command line option overrides the settings of
     the `level' configuration statement.

 -- Configuration: line-info BOOL
     If BOOL is `true' (*note boolean value::), each debugging message
     will be preceded by a corresponding source file location, i.e. the
     file name and line number where this message was generated.

2.2.5 Mailbox Statement
-----------------------

Syntax
------

     mailbox {
       # Use specified URL as a mailspool.
       mail-spool URL;
       # Create mailbox URL using PATTERN.
       mailbox-pattern PATTERN;
       # Default mailbox type.
       mailbox-type TYPE;
       # Default user mail folder.
       folder DIR;
     }

Description
-----------

The `mailbox' statement configures the location, name and type of user
mailboxes.

   The mailbox location can be specified using `mail-spool' or
`mail-pattern' statements.

 -- Configuration: mail-spool PATH
     The `mail-spool' statement specifies directory that holds user
     mailboxes. Once this statement is given, the `libmailutils'
     library will assume that the mailbox of user LOGIN is kept in file
     `PATH/LOGIN'.

     Historically, PATH can contain mailbox type prefix, e.g.:
     `maildir:///var/spool/mail', but such usage is discouraged in
     favor of `mailbox-pattern' statement.

 -- Configuration: mailbox-pattern PATTERN
     The `mailbox-pattern' statement is a modern way of configuring
     mailbox locations. It supersedes `mail-spool' statement.

     The PATTERN is valid "mailbox URL", which may contain references
     to `user' macro-variable (). This macro-variable will be expanded
     to the actual user name. The full syntax for PATTERN is:

            [TYPE://]PATH[;ARGS]

     where:

    TYPE
          Specifies the mailbox type. It must be one of mailbox types,
          supported by Mailutils. . By default, `local' is assumed. .

    PATH
          The path pattern.

    ARGS
          A semicolon-separated list of optional arguments, configuring
          indexed directory structure.

          An "indexed directory structure" is a special way of storing
          mailboxes, which allows for faster access in case of very
          large number of users.

          By default, all user mailboxes are stored in a single
          directory and are named after user login names. To find the
          mailbox for a given user, the system scans the directory for
          the corresponding file. This usually implies linear search,
          so the time needed to locate a mailbox is directly
          proportional to the ordinal number of the mailbox in the
          directory.

          GNU Mailutils supports three types of indexed directories:
          `direct', `reverse', and `hashed'.

          In direct indexed directory structure, PATH contains 26
          subdirectories named with lower-case letters of Latin
          alphabet. The location of the user mailbox is determined
          using the following algorithm:

            1. Take the first letter of the user name.

            2. Map it to a lower-case letter using "index mapping"
               table. The result gives sub-directory name.

            3. Descend into this directory.

          For example, using this algorithm, the mailbox of the user
          `smith' is stored in file `PATH/s/smith'.

          If each of single-letter subdirectories contains the indexed
          directory structure, we have second level of indexing. In
          this case the file name of `smith''s mailbox is
          `PATH/s/m/smith'.

          The "reverse" indexed structure uses the same principles, but
          the indexing letters are taken from the _end_ of the user
          name, instead of from the beginning. For example, in the 2nd
          level reverse indexed structure, the `smith''s mailbox is
          located in `PATH/h/t/smith'.

          Finally, the "hashed" structure consists of 256 subdirectories
          under PATH, named by 2-letter hex codes from `00' to `FF'.
          Mailboxes are stored in these subdirectories. The name of the
          subdirectory is computed by hashing first LEVEL letters of
          the user name. The hashing algorithm is:

            1. Take next letter from the user name

            2. Add its ASCII value to the hash sum.

            3. Continue (1-2) until LEVEL letters are processed, or all
               letters from the file name are used, whichever occurs
               first.

            4. Convert the computed sum modulo 256 to a hex code.

          Indexed directory structures are configured using the
          following arguments:

         type=VALUE
               Specifies type of indexing. Valid values are `index',
               for direct indexed structure, `rev-index' for reverse
               indexing, and `hash' for hashed structure.

         param=NUMBER
               Specifies indexing level.

         user=STRING
               Specifies indexing key. The only meaningful value, as of
               Mailutils version 2.0 is `user=${user}'.

          Let's assume the traditional mail layout, in which user
          incoming mails are stored in UNIX mailbox format in
          `/var/mail' directory.  The `mailbox-pattern' for this case
          is:

                 mailbox-pattern "/var/mail/${user}";

          It is entirely equivalent to specifying `mail-spool
          "/var/mail"'.

          Now, if the layout is the same, but mailboxes are kept in
          `maildir' format, then the corresponding statement is:

                 mailbox-pattern "maildir:///var/mail/${user}";

          Finally, if the mailboxes are stored in a directly-indexed
          directory with two levels of indexing, than:

                 mailbox-pattern "maildir:///var/mail;type=index;param=2;user=${user}";

   If neither `mailbox-pattern' nor `mail-spool' are given, the mailbox
names are determined using the following algorithm:

  1. If environment variable `FOLDER' its value is used.

  2. Otherwise, if environment variable `MAIL' is set, its value is
     used.

  3. If neither of these is set, the mailbox name is constructed by
     concatenating the built-in mail spool directory name, a directory
     separator, and the user name.

     The built-in mail spool directory name is determined at compile
     time, using `_PATH_MAILDIR' define from the include file
     `paths.h'. If this value is not defined, `/var/mail' or
     `/usr/spool/mail' is used.

 -- Configuration: mailbox-type TYPE
     Specifies type of mailboxes. By default, `mbox' (UNIX mailbox) is
     assumed. This can be changed while configuring the package by
     setting `MU_DEFAULT_SCHEME' configuration variable. The default
     value can be verified by running `mailutils-config --info scheme'.

 -- Configuration: folder DIR
     Sets user mail folder directory. Its value is using when expanding
     `plus-notation', i.e. such mailbox names as `+inbox'. The `+' sign
     is replaced by DIR, followed by a directory separator (`/').

     The DIR argument can contain mailbox type prefix, e.g `mh://Mail'.

     The default folder name is `Mail/'.

2.2.6 Locking Statement
-----------------------

Syntax
------

     locking {
       # Default locker flags.
       flags ARG;
       # Set timeout for acquiring the lock.
       retry-timeout ARG;
       # Set the maximum number of times to retry acquiring the lock.
       retry-count NUMBER;
       # Expire locks older than this amount of time.
       expire-timeout NUMBER;
       # Use PROG as external locker program.
       external-locker PROG;
     }

Description
-----------

This block statement configures various parameters used when locking
UNIX mailboxes in order to prevent simultaneous writes.

   It is important to note, that locking applies only to maildrops in
UNIX mailbox format. All other mailbox types do not require locking.

 -- Configuration: flags STRING
     Set locking flags. Argument is a string consisting of one or more
     of the following letters:

    E
          Use an external program to manage locks. The program is given
          by `external-locker' statement (see below).

    R
          If the locking attempt failed, retry it. This is the default.
          The number of retries, and time interval between the two
          successive attempts is given by `retry-count' and
          `retry-timeout' statements, correspondingly.

    T
          If a lock file exists, check its modification time and, if it
          is older than a predefined amount of time, remove the lock.
          The amount of time is specified by `expire-timeout' statement.

    P
          Store the PID of the locking process in a lock file.

 -- Configuration: retry-count NUMBER
     Number of locking attempts. The `P' flag must be set for this to
     take effect.

 -- Configuration: retry-timeout SECONDS
     Time interval, in seconds, between the two successive locking
     attempts. The `P' flag must be set for this to take effect.

 -- Configuration: expire-timeout SECONDS
     Remove existing lock file, if it is created more than this number
     of seconds ago. The `T' flag must be set for this to take effect.

 -- Configuration: external-locker STRING
     Set command line of an external locker program. The `E' flag must
     be set for this to take effect.

2.2.7 Mailer Statement
----------------------

Syntax
------

     mailer {
       url URL;
     }

Description
-----------

A "mailer" is a special logical entity GNU Mailutils uses for sending
messages. Its internal representation is discussed in *note Mailer::.
The `mailer' statement configures it.

   The mailer statement contains a single sub-statement:

 -- Configuration: url STR
     Set the mailer URL.

   GNU Mailutils supports two types of mailer URLs, described in the
table below. As usual, square brackets indicate optional parts:

smtp://HOST[:PORT]
     Use an SMTP server HOST to send messages. Optional PORT specifies
     port number or symbolic name (as defined in `/etc/services'). It
     defaults to 25. The HOST can be specified as either an IP address
     in dotted-quad notation or as a symbolic host name. In the latter
     case, DNS system will be used to resolve it.

sendmail://PROGNAME
     Use sendmail-compatible program PROGNAME. "Sendmail-compatible"
     means that the program must support following command line options:

    `-oi'
          Do not treat `.' as message terminator.

    `-f ADDR'
          Use ADDR as the sender address.

    `-t'
          Get recipient addresses from the message.

sendmail:
     This is a special form of the `sendmail' mailer. It uses the
     `sendmail' binary from the `_PATH_SENDMAIL' macro in your
     `/usr/include/paths.h'. It is the default mailer.

prog://PROGNAME?QUERY
     A "prog" mailer. This is a generalization of `sendmail' mailer
     that allows to use arbitrary external programs as mailers.

     The PROGNAME must be a full pathname of the binary file. When
     sending message, Mailutils will invoke this file with the arguments
     specified by QUERY and will pipe the message to be sent to its
     standard input.

     The QUERY part is a list of arguments, separated by `&' signs.
     Arguments may contain the following macro-substitutions:

    `${sender}'
          Expands to the sender email address.

    `${rcpt}'
          Expands to the recipient email addresses.

2.2.8 ACL Statement
-------------------

Syntax
------

     acl {
       # Allow connections from this IP address.
       allow [from] IP;
       # Deny connections from this IP address.
       deny [from] IP;
       # Log connections from this IP address.
       log [from] IP [STRING];
       /* Execute supplied program if a connection from this
          IP address is requested. */
       exec [from] IP PROGRAM;
       /* Use PROGRAM to decide whether to allow connection
          from IP. */
       ifexec [from] IP PROGRAM;
     }

Description
-----------

The ACL statement defines an "Access Control List", a special structure
that controls who can access the given Mailutils resource.

   The `acl' block contains a list of access controls. Each control can
be regarded as a function that returns a tree-state value: `True',
`False' and `Don't know'. When a remote party connects to the server,
each of controls is tried in turn. If a control returns `False', access
is denied. If it returns `True', access is allowed. If it returns `Don't
know', then the next control is tried. It is unclear whether to allow
access if the last control in list returned `Don't know'. GNU Mailutils
2.0 issues a warning message and allows access.  This default may
change in future versions. Users are advised to write their ACLs so
that the last control returns a definitive answer (either `True' or
`False').

   In the discussion below, wherever IP appears as an argument, it can
be replaced by any of:

   * An IPv4 address in dotted-quad notation.

   * A CIDR in the form `IP/MASK', where IP is an IPv4 address, and
     MASK is a decimal number in the range `0--32'.

   * A symbolic host name.  

   * A word `any', that stands for `0.0.0.0/0'.

   The following controls are understood:

 -- Configuration: allow [from] CIDR
     Allow connections from IP addresses matching this CIDR block.

 -- Configuration: deny [from] CIDR
     Deny connections from IP addresses matching this CIDR block.

 -- Configuration: ifexec [from] CIDR PROGRAM
     When a connection from the CIDR block is requested, execute the
     program PROGRAM. If its exit code is `0', then allow connection.
     Otherwise, deny it.

   The following two controls are provided for logging purposes and as a
means of extensions. They always return a `Don't know' answer, and
therefore should not be used at the end of an ACL:

 -- Configuration: log [from] CIDR [STRING]
     Log connections from addresses in this CIDR. The `MU_DIAG_INFO'
     channel is used. If the logging goes to syslog, it is translated
     to the `LOG_INFO' priority.

     If STRING is not given, the format of the log entry depends on the
     connection family, as described in the table below:

    {AF_INET IP:PORT}
          For inet IPv4 connections. The variables IP and PORT are
          replaced by the remote IP address and port number,
          correspondingly.

    {AF_UNIX}
          For connections over UNIX sockets. The socket name, if
          available, may be printed before the closing curly brace.

     If the STRING is specified, it undergoes macro expansion and the
     result of it is used as the log entry. The following macro
     variables are expanded:

    `aclno'
          Ordinal number of the control in the ACL. Numbers begin from
          `0'.

    `family'
          Connection family. Mailutils version 2.0 supports two
          families: `AF_INET' and `AF_UNIX'.

    `address'
          Remote IP address (for `AF_INET') or socket name (for
          `AF_UNIX'). Notice that most Unixes return empty string
          instead of the `AF_UNIX' socket name, so do not rely on it.

    `port'
          Remote port number (for `AF_INET').

     For example, the following ACL makes a Mailutils server log every
     incoming connection:

            acl {
               log from any "Connect from ${address}";
               ...
            }

     This was the default behavior for the versions of Mailutils up to
     `1.2', so if you got used to its logs you might wish to add the
     above in your configuration files.

 -- Configuration: exec [from] CIDR PROGRAM
     If a connection from the CIDR block is requested, execute the
     given PROGRAM. Do not wait for it to terminate, and ignore its
     exit code.

2.2.9 Tcp-wrappers Statement
----------------------------

Syntax
------

     tcp-wrappers {
       # Enable TCP wrapper access control.
       enable BOOL;
       # Set daemon name for TCP wrapper lookups.
       daemon NAME;
       # Use FILE for positive client address access control.
       allow-table FILE;
       # Use file for negative client address access control.
       deny-table FILE;
       # Log allowed accesses at this syslog priority.
       allow-syslog-priority PRIO;
       # Log denied accesses at this syslog priority.
       deny-syslog-priority PRIO;
     }

2.2.10 Description
------------------

The `tcp-wrappers' statements provides an alternative way to control
accesses to the resources served by GNU Mailutils. This statement is
enabled if Mailutils is compiled with TCP wrappers library `libwrap'.

   Access control using TCP wrappers is based on two files, called
"tables", containing access rules. There are two tables: the "allow
table", usually stored in file `/etc/hosts.allow', and the "deny
table", kept in file `/etc/hosts.deny'. The rules in each table begin
with an identifier called "daemon name". Each utility wishing to verify
a connection, select the entries having its daemon name from the allow
table. A connection is allowed if it matches any of these entries.
Otherwise, the utility retrieves all entries with its daemon name from
the deny table. If any of these matches the connection, then it is
refused. Otherwise, if neither table contains matching entries, the
connection is allowed.

   Description of a TCP wrapper table format lies outside the scope of
this document. Please, see *note ACCESS CONTROL FILES:
(hosts_access(5))ACCESS CONTROL FILES, for details.

 -- Configuration: enable BOOL
     Enable access control using TCP wrappers. It is on by default.

 -- Configuration: daemon NAME
     Set daemon name for TCP wrapper lookups. By default, the name of
     the utility is used. E.g. `imap4d' uses `imap4d' as the daemon
     name.

 -- Configuration: allow-table FILE
     Use FILE as allow table. By default, `/etc/hosts.allow' is used.

 -- Configuration: deny-table FILE
     Use FILE as negative table. By default, `/etc/hosts.deny' is used.

 -- Configuration: allow-syslog-priority PRIO;
     Log allowed accesses using syslog priority PRIO.

 -- Configuration: deny-syslog-priority PRIO;
     Log denied accesses using syslog priority PRIO.

2.2.11 Server Settings
----------------------

GNU Mailutils offers several server applications: `pop3d', `imap4d',
`comsatd', to name a few. Being quite different in their purpose, they
are very similar in some aspects of their architecture. First of all,
they all support two operating mode: a "daemon" mode, where a program
disconnects from the controlling terminal and works in background, and
an "inetd" mode, where it remains in foreground and communicates with
the remote party via standard input and output streams. Secondly, when
operating as daemons, they listen to a preconfigured set of IP
addresses and ports, reacting to requests that arrive.

   To configure these aspects of functionality, GNU Mailutils provides
"Server Configuration Settings", which we will describe in this
subsection.

2.2.11.1 General Server Configuration
.....................................

Syntax
......

     # Set daemon mode.
     mode `inetd|daemon';
     # Run in foreground.
     foreground BOOL;
     # Maximum number of children processes to run simultaneously.
     max-children NUMBER;
     # Store PID of the master process in FILE.
     pidfile FILE;
     # Default port number.
     port PORTSPEC;
     # Set idle timeout.
     timeout TIME;

Description
...........

These statements configure general server-related issues.

 -- Configuration: mode STRING;
     Set operation mode of the server. Two operation modes are
     supported:

    daemon
          Run as a standalone daemon, disconnecting from the controlling
          terminal and continuing to run in the background. In this
          case, it is the server that controls what IP addresses and
          ports to listen on, who is allowed to connect and from where,
          how many clients are allowed to connect simultaneously, etc.
          Most remaining configuration statements are valid only in the
          daemon mode.

          This is the preferred mode of operation for GNU Mailutils
          servers.

    inetd
          Operate as a subprocess of UNIX internet super-server program,
          `inetd'. *Note Internet super-server: (inetd(8))Internet
          super-server, for a detailed description of the operation of
          `inetd' and its configuration. In this case it is `inetd' that
          controls all major connectivity aspects, the Mailutils server
          itself communicates with it via standard input and output
          streams.

          For historical reasons, this mode is the default, if no `mode'
          statement is specified. This will change in the future.

 -- Configuration: foreground BOOL;
     [daemon mode only]
     Do not disconnect from the controlling terminal and remain in the
     foreground.

 -- Configuration: max-children NUMBER;
     [daemon mode only]
     Set maximum number of child processes allowed to run
     simultaneously.  This equals the number of clients that can use
     the server simultaneously.

     The default is 20 clients.

 -- Configuration: pidfile FILE;
     After startup, store the PID of the main server process in FILE.
     When the process terminates, the file is removed. As of version
     2.0, GNU Mailutils servers make no further use of this file. It is
     intended for use by automated startup scripts and controlling
     programs ().

 -- Configuration: port PORTSPEC;
     [daemon mode only]
     Set default port to listen to. The PORTSPEC argument is either a
     port number in decimal, or a symbolic service name, as listed in
     `/etc/services' (*note Internet network services list:
     (services(5))Internet network services list.).

 -- Configuration: timeout TIME;
     Set maximum idle time out in seconds. If a client does not send any
     requests during TIME seconds, the child process terminates.

2.2.11.2 Server Statement
.........................

Syntax
......

     server IPADDR[:PORT] {
       # Run this server as a single process.
       single-process BOOL;
       # Log the session transcript.
       transcript BOOL;
       # Set idle timeout.
       timeout TIME;
       # Set server specific ACLs.
       acl { /* *Note ACL Statement::. */ };
     }

Description
...........

The `server' block statement configures a single TCP or UDP server. It
takes effect only in daemon mode (*note server mode::).  The argument
to this statement specifies the IP address, and, optionally, the port,
to listen on for requests. The IPADDR part is either an IPv4 address in
dotted-quad form, or a symbolic host name which can be resolved to such
an address via DNS. Specifying `0.0.0.0' as the IPADDR means listen on
all available network interfaces. The PORT argument is either a port
number in decimal, or a symbolic service name, as listed in
`/etc/services' (*note Internet network services list:
(services(5))Internet network services list.). If PORT is omitted,
Mailutils uses the port set by `port' statement (*note port: General
Server Configuration.), or, in its absence, the default port number,
which depends on a server being used (e.g. 110, for `pop3d', 143, for
`imap4d', etc.).

   Any number of `server' statements may be specified in a single
configuration file, allowing to set up the same service on several IP
addresses and/or port numbers, and with different configurations.

   Statements within the `server' block statement configure this
particular server.

 -- Configuration: single-process BOOL;
     If set to true, this server will operate in single-process mode.
     This mode is intended for debugging only, do not use it on
     production servers.

 -- Configuration: transcript BOOL;
     Enable transcript of the client-server interaction. This may
     generate excessive amounts of logging, which in turn may slow down
     the operation considerably.

     Session transcripts are useful in fine-tuning your configurations
     and in debugging. They should be turned off on most production
     servers.

 -- Configuration: timeout TIME;
     Set idle timeout for this server. This overrides global timeout
     settings (*note timeout: General Server Configuration.).

 -- Configuration: acl
     This statement defines a per-server Access Control List. Its syntax
     is as described in *note ACL Statement::. Per-server ACLs
     complement, but not override, global ACLs, i.e. if both global ACL
     and per-server ACL are used, the connection is allowed only if
     both of them allow it, and is denied if any one of them denies it.

2.2.12 Auth Statement
---------------------

Syntax
------

     auth {
       # Set a list of modules for authentication.
       authentication MODULE-LIST;
       # Set a list of modules for authorization.
       authorization MODULE-LIST;
     }

Description
-----------

Some mail utilities provide access to their services only after
verifying that the user is actually the person he is claiming to be.
Such programs are, for example, `pop3d' and `imap4d'. The process of
the verification is broken down into two stages: "authorization" and
"authentication".  In "authorization" stage the program retrieves the
information about a particular user. In "authentication" stage, this
information is compared against the user-supplied credentials. Only if
both stages succeed is the user allowed to use the service.

   A set of "modules" is involved in performing each stage. For
example, the authorization stage can retrieve the user description from
various sources: system database, SQL database, virtual domain table,
etc. Each module is responsible for retrieving the description from a
particular source of information. The modules are arranged in a "module
list". The modules from the list are invoked in turn, until one of them
succeeds or the list is exhausted. In the latter case the authorization
fails. Otherwise, the data returned by the succeeded module are used in
authentication.

   Similarly, authentication may be performed in several ways. The
authentication modules are also grouped in a list. Each module is tried
in turn until either a module succeeds, in which case the
authentication succeeds, or the end of the list is reached.

   For example, the authorization list

       (system, sql, virtdomains)

means that first the system user database (`/etc/password') is searched
for a description of a user in question. If the search fails, the SQL
database is searched. Finally, if it also fails, the search is
performed in the virtual domain database.

   _Note_, that some authentication and/or authorization modules may be
disabled when configuring the package before compilation. The names of
the disabled modules are nevertheless available for use in runtime
configuration options, but they represent a "fail-only" functionality,
e.g. if the package was compiled without SQL support then the module
`sql' in the above example will always fail, thus passing the execution
on to the next module.

   The `auth' statement configures authentication and authorization.

 -- Configuration: authorization MODULE-LIST
     Define a sequence of modules to use for authorization. Modules will
     be tried in the same order as listed in MODULE-LIST.

     The modules available for use in authorization list are:

    system
          User credentials are retrieved from the system user database
          (`/etc/password').

    sql
          User credentials are retrieved from a SQL database.  A
          separate configuration statement, `sql', is used to configure
          it (*note SQL Statement::).

    virtdomain
          User credentials are retrieved from a "virtual domain" user
          database. Virtual domains are configured using `virtdomain'
          statement (*note Virtdomain Statement::).

    radius
          User credentials are retrieved using RADIUS. *Note Radius
          Statement::, for a detailed description on how to configure
          it.

    ldap
          User credentials are retrieved from an LDAP database. *Note
          LDAP Statement::, for an information on how to configure it.

     Unless overridden by `authorization' statement, the default list
     of authorization modules is:

            (system, sql, virtdomains)

 -- Configuration: authentication MODULE-LIST
     Define a sequence of modules to use for authentication. Modules
     will be tried in the same order as listed in MODULE-LIST.

     The following table lists modules available for use in MODULE-LIST:

    generic
          The generic authentication type. User password is hashed and
          compared against the hash value returned in authorization
          stage.

    system
          The hashed value of the user password is retrieved from
          `/etc/shadow' file on systems that support it.

    sql
          The hashed value of the user password is retrieved from a SQL
          database using query supplied by `getpass' statement (*note
          getpass: SQL Statement.).

    pam
          The user is authenticated via pluggable authentication module
          (PAM). The PAM service name to be used is configured in `pam'
          statement (*note PAM Statement::).

    radius
          The user is authenticated on a remote RADIUS server. *Note
          Radius Statement::.

    ldap
          The user is authenticated using LDAP. *Note LDAP Statement::.

     Unless overridden by `authentication' statement, the list of
     authentication modules is:

            (generic, system, pam, sql)

2.2.13 PAM Statement
--------------------

Syntax
------

     pam {
       # Set PAM service name.
       service TEXT;
     }

Description
-----------

The `pam' statement configures PAM authentication. It contains a single
sub-statement:

 -- Configuration: service TEXT
     Define service name to look for in PAM configuration. By default,
     the base name of the Mailutils binary is used.

   This statement takes effect only if `pam' is listed in
`authentication' statement (*note Auth Statement::).

2.2.14 Virtdomain Statement
---------------------------

Syntax
------

     virtdomain {
       # Name of the virtdomain password directory.
       passwd-dir DIR;
     }

Description
-----------

"Virtual mail domains" make it possible to handle several mail domains
each having a separate set of users, on a single server.  The domains
are completely independent of each other, i.e. the same user name can
be present in several domains and represent different users.

   When authenticating to a server with virtual domain support enabled,
users must supply their user names with domain parts. The server strips
off the domain part and uses it as a name of UNIX-format password
database file, located in the "domain password directory". The latter
is set using `passwd-dir' statement.

 -- Configuration: passwd-dir DIR
     Set virtual domain password directory.

   For example, when authenticating user `smith@domain.tld', the server
will use password file named `DIR/domain.tld'.  This file must be in
UNIX passwd format (*note password file: (passwd(5))password file.),
with encrypted passwords stored in it (as of GNU Mailutils version
2.0, there is no support for shadow files in virtual password
directories, although this is planned for future versions). Here is an
example record from this file:

     smith:Wbld/G2Q2Le2w:1000:1000:Email Account:/var/mail/domain/smith:/dev/null

   Notice, that it must contain user names without domain parts.

   The `pw_dir' field (the 6th field) is used to determine the location
of the maildrop for this user. It is defined as `PW_DIR/INBOX'. In our
example, the maildrop for user `smith' will be located in file
`/var/mail/domain/smith'.

   If user did not supply his domain name, or if no matching record was
found in the password file, or if the file matching the domain name
does not exist, then GNU Mailutils falls back to alternative method.
First, it tries to determine the IP address of the remote party. Then
the domain name corresponding to that address is looked up in the DNS
system. Finally, this domain name is used as a name of the password
file.

2.2.15 Radius Statement
-----------------------

Syntax
------

     radius {
       # Set radius configuration directory.
       directory DIR;
       # Radius request for authorization.
       auth REQUEST;
       # Radius request for getpwnam.
       getpwnam REQUEST;
       # Radius request for getpwuid.
       getpwuid REQUEST;
     }

Description
-----------

The `radius' block statement configures RADIUS authentication and
authorization.

   Mailutils uses GNU Radius library, which is configured via
`raddb/client.conf' file (*note Client Configuration:
(radius)client.conf.). Its exact location depends on configuration
settings that were used while compiling GNU Radius. Usually it is
`/usr/local/etc', or `/etc'. This default can also be changed at run
time using `directory' statement:

 -- Configuration: directory DIR
     Set full path name to the GNU Radius configuration directory.

   It authorization is used, the Radius dictionary file must declare the
the following attributes:

Attribute                     Type           Description
--------------------------------------------------------------------------- 
GNU-MU-User-Name              string         User login name
GNU-MU-UID                    integer        UID
GNU-MU-GID                    integer        GID
GNU-MU-GECOS                  string         GECOS
GNU-MU-Dir                    string         Home directory
GNU-MU-Shell                  string         User shell
GNU-MU-Mailbox                string         User mailbox
GNU-MU-Quota                  integer        Mail quota (in bytes)

   A dictionary file with appropriate definitions is included in the
Mailutils distribution: `examples/config/mailutils.dict'. This file is
not installed by default, you will have to manually copy it to the GNU
Radius `raddb/dict' directory and include it in the main dictionary
file `raddb/dictionary' by adding the following statement:

     $INCLUDE dict/mailutils.dict

   Requests to use for authentication and authorization are configured
using three statements: `auth', `getpwnam' and `getpwuid'. Each
statement takes a single argument: a string, containing a
comma-separated list of assignments. An assignment specifies a
particular "attribute-value pair" (*note RADIUS Attributes:
(radius)Overview.) to send to the server. The left-hand side of the
assignment is a symbolic attribute name, as defined in one of Radius
dictionaries (*note Dictionary of Attributes: (radius)dictionary
file.). The value is specified by the right-hand side of assignment.
For example:

     "Service-Type = Authenticate-Only, NAS-Identifier = \"mail\""

   An assignment may contain references to the following macro-variables
():

user
     The actual user name (for `auth' and `getpwnam'), or user ID (for
     `getpwuid'). For example:

          User-Name = ${user}

passwd
     User password. For examples:
          User-Password = ${passwd}

 -- Configuration: auth PAIRLIST
     Specifies the request to be sent to authenticate the user. For
     example:

          auth "User-Name = ${user}, User-Password = ${passwd}";

     The user is authenticated only if this request returns
     `Access-Accept' (*note Access-Accept: (radius)Authentication
     Requests.). Any returned attribute-value pairs are ignored.

 -- Configuration: getpwnam PAIRLIST
     Specifies the request that returns user information for the given
     user name. For example:

          getpwnam "User-Name = ${user}, State = getpwnam, "
                   "Service-Type = Authenticate-Only";

     If the requested user account exists, the Radius server must return
     `Access-Accept' packet with the following attributes:
     `GNU-MU-User-Name', `GNU-MU-UID', `GNU-MU-GID', `GNU-MU-GECOS',
     `GNU-MU-Dir', `GNU-MU-Shell'.

     The attributes `GNU-MU-Mailbox' and `GNU-MU-Quota' are optional.

     If `GNU-MU-Mailbox' is present, it must contain a valid mailbox
     URL (). If `GNU-MU-Mailbox' is not present, Mailutils constructs
     the mailbox name using the settings from the `mailbox'
     configuration statement (*note Mailbox Statement::), or built-in
     defaults, if it is not present.

     If `GNU-MU-Quota' is present, it specifies the maximum mailbox
     size for this user, in bytes. In the absence of this attribute,
     mailbox size is unlimited.

 -- Configuration: getpwuid PAIRLIST
     Specifies the request that returns user information for the given
     user ID. In PAIRLIST, the `user' macro-variable is expanded to the
     numeric value of ID. For example:

          getpwuid "User-Name = ${user}, State = getpwuid, "
                   "Service-Type = Authenticate-Only";

     The reply to `getpwuid' request is the same as to `getpwnam'
     request (see above).

2.2.16 SQL Statement
--------------------

     (_The information in this node may be obsolete or otherwise
     inaccurate._ This message will disappear, once this node revised.)

Syntax
------

     sql {
       # Set SQL interface to use.
       interface `mysql|odbc|postgres';
       # SQL server host name.
       host ARG;
       # SQL user name.
       user ARG;
       # Password for the SQL user.
       passwd ARG;
       # SQL server port.
       port ARG;
       # Database name.
       db ARG;
       # Type of password returned by getpass query.
       password-type `plain | hash | scrambled';
       # Set a field-map for parsing SQL replies.
       field-map MAP;
       # SQL query returning the user's password.
       getpass QUERY;
       # SQL query to use for getpwnam requests.
       getpwnam QUERY;
       # SQL query to use for getpwuid requests.
       getpwuid QUERY;
     }

2.2.17 Description
------------------

The `sql' statement configures access credentials to SQL database and
the queries for authentication and authorization.

   GNU Mailutils supports three types of SQL interfaces: MySQL,
PostgreSQL and ODBC. The latter is a standard API for using database
management systems, which can be used to communicate with a wide
variety of DBMS.

 -- Configuration: interface TYPE
     Configures type of DBMS interface. Allowed values for TYPE are:

    mysql
          Interface with a MySQL server (`http://www.mysql.org').

    odbc
          Use ODBC interface. See `http://www.unixodbc.org', for a
          detailed description of ODBC configuration.

    postgres
          Interface with a PostgreSQL server
          (`http://www.postgres.org').

   The database and database access credentials are configured using the
following statements:

 -- Configuration: host ARG
     The host running the SQL server. The value can be either a host
     name or an IP address in dotted-quad notation, in which case an
     INET connection is used, or a full pathname to a file, in which
     case a connection to UNIX socket is used.

 -- Configuration: port ARG
     TCP port the server is listening on (for INET connections). This
     parameter is optional. Its default value depends on the type of
     database being used.

 -- Configuration: db ARG;
     Name of the database.

 -- Configuration: user ARG
     SQL user name.

 -- Configuration: passwd ARG;
     Password to access the database.

2.2.18 LDAP Statement
---------------------

     _This node is to be written._

Syntax
------

     ldap {
       # Enable LDAP lookups.
       enable BOOL;
       # Set URL of the LDAP server.
       url URL;
       # Base DN for LDAP lookups.
       base STRING;
       # DN for accessing LDAP database.
       binddn STRING;
       # Password for use with binddn.
       passwd STRING;
       # Use TLS encryption.
       tls BOOL;
       # Set LDAP debugging level.
       debug NUMBER;
       # Set a field-map for parsing LDAP replies.
       field-map MAP;
       # LDAP filter to use for getpwnam requests.
       getpwnam STRING;
       # LDAP filter to use for getpwuid requests.
       getpwuid FILTER;
     }

2.2.19 TLS Statement
--------------------

     _This node is to be written._

Syntax
------

     tls {
       # Enable TLS support.
       enable BOOL;
       # Specify SSL certificate file.
       ssl-cert BOOL;
       # Specify SSL certificate key file.
       ssl-key FILE;
       # Specify trusted CAs file.
       ssl-cafile FILE;
     }

2.2.20 GSASL Statement
----------------------

     _This node is to be written._

Syntax
------

     gsasl {
       # Name of GSASL password file.
       cram-passwd FILE;
       # SASL service name.
       service STRING;
       # SASL realm name.
       realm STRING;
       # SASL host name.
       hostname STRING;
       # Anonymous user name.
       anonymous-user STRING;
     }

2.3 `frm' and `from' -- List Headers from a Mailbox
===================================================

GNU mailutils provides two commands for listing messages in a mailbox.
These are `from' and `frm'.

   The behavior of both programs is affected by the following
configuration file statements:

Statement              Reference
------------------------------------------------------------------- 
debug                  *Note Debug Statement::.
tls                    *Note TLS Statement::.
mailbox                *Note Mailbox Statement::.
locking                *Note Locking Statement::.

`frm'
-----

The `frm' utility outputs a header information of the selected messages
in a mailbox. By default, `frm' reads user's system mailbox and outputs
the contents of `From' and `Subject' headers for each message. If a
folder is specified in the command line, the program reads that folder
rather than the default mailbox.

   The following command line options alter the behavior of the program:

`-d'
`--debug'
     Enable debugging output.

`-f STRING'
`--field STRING'
     Display the header named by STRING instead of `From' `Subject'
     pair.

`-l'
`--to'
     Include the contents of `To' header to the output. The output field
     order is then: `To' `From' `Subject'.

`-n'
`--number'
     Prefix each line with corresponding message number.

`-Q'
`--Quiet'
     Be very quiet. Nothing is output except error messages. This is
     useful in shell scripts where only the return status of the
     program is important.

`-q'
`--query'
     Print a message only if there are unread messages in the mailbox.

`-S'
`--summary'
     Print a summary line.

`-s ATTR'
`--status ATTR'
     Only display headers from messages with the given status.  ATTR
     may be one of the following: `new', `read', `unread'. It is
     sufficient to specify only first letter of an ATTR. Multiple `-s'
     options are allowed.

`-t'
`--align'
     Tidy mode. In this mode `frm' tries to preserve the alignment of
     the output fields. It also enables the use of BIDI algorithm for
     displaying subject lines that contain text in right-to-left
     orientation (such as Arabic or Hebrew).

`from'
------

The `from' utility displays sender and subject of each message in a
mailbox. By default, it reads the user's system mailbox. If the program
is given a single argument, it is interpreted as a name of the user
whose mailbox is to be read. Obviously, permissions are required to
access that user's mailbox, so such invocations may be used only by
superuser.

   The option `-f' (`--file') instructs `from' to read the given
mailbox.

   The full list of options, supported by `from' follows:

`-c'
`--count'
     Prints only a count of messages in the mailbox and exit.

`-d'
`--debug'
     Prints additional debugging output.

`-s STRING'
`--sender=STRING'
     Prints only mail whose `From:' headers contain the supplied string.

`-f URL'
`--file=URL'
     Examine mailbox from the given URL.

2.4 `mail' -- Send and Receive Mail
===================================

`Mail' is an enhanced version of standard `/bin/mail' program.  As well
as its predecessor, it can be used either in sending mode or in reading
mode. `Mail' enters sending mode when one or more email addresses were
specified in this command line. In this mode the program waits until
user finishes composing the message, then attempts to send it to the
specified addresses and exits.  See *note Composing Mail::, for a
detailed description of this behavior.

   If the command line contained no email addresses, `mail' switches to
reading mode. In this mode it allows to read and manipulate the
contents of a mailbox. The URL of the mailbox to operate upon is taken
from the argument of `--file' command line option. If it is not
specified, the user's system mailbox is assumed. For more detail, see
*note Reading Mail::.

   In contrast to other GNU Mailutils programs, `mail' does not use the
Mailutils configuration file. Instead, it uses the traditional
`mailrc'-style configuration. *Note Mail Configuration Files::, for a
detailed description of its format.

2.4.1 Invoking `mail'
---------------------

General usage of `mail' program is:

           mail [OPTION...] [ADDRESS...]
   If [ADDRESS...] part is present, `mail' switches to mail sending
mode, otherwise it operates in mail reading mode.

   The program uses following option groups: .

   `Mail' understands following command line options:

`-e'
`--exist'
     Return true if the mailbox contains some messages. Return false
     otherwise.  This is useful for writing shell scripts.

`-E COMMAND'
`--exec=COMMAND'
     Execute COMMAND before opening the mailbox. Any number of `--exec'
     options can be given. The commands will be executed after sourcing
     configuration files (*note Mail Configuration Files::), but before
     opening the mailbox.

`--exec'

`-f[FILE]'
`--file[=FILE]'
     Operate on mailbox FILE. If this option is not specified, the
     default is user's system mailbox. If it is specified without
     argument, the default is `$HOME/mbox'.  _Please note_, that there
     should be no whitespace between the short variant of the option
     (`-f'), and its parameter. Similarly, when using long option
     (`--file'), its argument must be preceded by equal sign.

`-F'
`--byname'
     Save messages according to sender. Currently this option is not
     implemented.

`-H'
`--headers'
     Print header summary to stdout and exit.

`-i'
`--ignore'
     Ignore interrupts.

`-m PATH'
`--mail-spool=PATH'
     Set path to the mailspool directory

`-n'
`--norc'
     Do not read the system-wide mailrc file. *Note Mail Configuration
     Files::.

`-N'
`--nosum'
     Do not display initial header summary.

`-p'
`--print'
`-r'
`--read'
     Print all mail to standard output. It is equivalent to issuing
     following commands after starting `mail -N':
          print *
          quit

`-q'
`--quit'
     Cause interrupts to terminate program.

`-s SUBJ'
`--subject=SUBJ'
     Send a message with a Subject of SUBJ. Valid only in sending mode.

`-t'
`--to'
     Switch to sending mode.

`-u USER'
`--user=USER'
     Operate on USER's mailbox. This is equivalent to:

          mail -f/SPOOL_PATH/USER

     with SPOOL_PATH being the full path to your mailspool directory
     (`/var/spool/mail' or `/var/mail' on most systems).

`-?'
`--help'
     Display a help message.

`--usage'
     Display a short usage summary.

`-V'
`--version'
     Print program version and exit.

2.4.2 How to Specify Message Sets
---------------------------------

Many mail commands such as print and delete can be given a "message
list" to operate upon. Wherever the message list is omitted, the command
operates on the current message.

   The "message list" in its simplest form is one of:

.
     Selects current message. It is equivalent to empty message list.

*
     Selects all messages in the mailbox.

^
     Selects first non-deleted message.

$
     Selects last non-deleted message.

   In its complex form, the "message list" is a comma or
whitespace-separated list of "message specifiers". A "message
specifier" is one of

Message Number
     This specifier addresses the message with the given ordinal number
     in the mailbox.

Message range
     "Message range" is specified as two message numbers separated by a
     dash. It selects all messages with the number lying within that
     range.

Attribute specifier
     An "Attribute specifier" is a colon followed by a single letter.
     The "Attribute specifier" addresses all messages in the mailbox
     that have the given attribute. These are the valid attribute
     specifiers:

    `:d'
          Selects all deleted messages.

    `:n'
          Selects all recent messages, i.e. the messages that have not
          been neither read not seen so far.

    `:o'
          Selects all messages that have been seen.

    `:r'
          Selects all messages that have been read.

    `:u'
          Selects all messages that have _not_ been read.

    `:t'
          Selects all tagged messages.

    `:T'
          Selects all untagged messages.

Header match
     The "header match" is a string in the form:

          [HEADER:]/STRING/
     It selects all messages that contain header field HEADER matching
     given REGEXP. If the variable `regexp' is set, the STRING is
     assumed to be a POSIX regexp. Otherwise, a header is considered to
     match STRING if the latter constitutes a substring of the former
     (comparison is case-insensitive).

     If HEADER: part is omitted, it is assumed to be `Subject:'.

Message body match
     The "message body match" is a string in the form:

          :/STRING/
     It selects all messages whose body matches the string. The matching
     rules are the same as described under "Header match".

   A "message specifier" can be followed by "message part specifier",
enclosed in a pair of brackets. A "message part specifier" controls
which part of a message should be operated upon.  It is meaningful only
for multipart messages. A "message part specifier" is a comma or
whitespace - separated list of part numbers or ranges. Each part number
can in turn be "message part specifier", thus allowing for operating
upon multiply-encoded messages.

   The following are the examples of valid message lists:

2.4.3 Composing Mail
--------------------

You can compose the message by simply typing the contents of it, line
by line. But usually this is not enough, you would need to edit your
text, to quote some messages, etc. `Mail' provides these capabilities
through "compose escapes". The "compose escapes" are single-character
commands, preceded by special "escape character", which defaults to
`~'. The combination `escape character + command' is recognized as a
compose escape only if it occurs at the beginning of a line. If the
escape character must appear at the beginning of a line, enter it twice.
The actual escape character may be changed by setting the value of
`escape' mail variable (*note Mail Variables::).

Quitting Compose Mode
.....................

There are several commands allowing you to quit the compose mode.

   Typing the end-of-file character (`C-D') on a line alone finishes
compose mode and sends the message to its destination. The `C-D'
character looses its special meaning if `ignoreeof' mail variable is
set.

   If mail variable `dot' is set, typing dot (`.') on a line alone
achieves the same effect as `C-D' above.

   Finally, using `~.' escape always quits compose mode and sends out
the composed message.

   To abort composing of a message without sending it, type interrupt
character (by default, `C-C') twice. This behavior is disabled when
mail variable `ignore' is set. In this case, you can use `~x' escape to
achieve the same effect.

Getting Help on Compose Escapes: ~?
...................................

The `~?' escape prints on screen a brief summary of the available
compose escapes. _Please note_, that `~h' escape prompts for changing
the header values, and does _not_ give help.

Editing the Message: ~e and ~v
..............................

If you are not satisfied with the message as it is, you can edit it
using a text editor specified either by `EDITOR' or by `VISUAL'
environment variables. The `~e' uses the former, and `~v' uses the
latter.

   By default both escapes allow you to edit only the body of the
message. However, if the `editheaders' variable is set, `mail' will
load into the editor the complete text of the message with headers
included, thus allowing you to change the headers as well.

Modifying the Headers: ~h, ~t, ~c, ~b, ~s
.........................................

To add new addresses to the list of message recipients, use `~t'
command, e.g.:

     ~t name1@domain.net name2

   To add addresses to `Cc' or `Bcc', use `~c' or `~b' escapes
respectively.

   To change the `Subject' header, use `~s' escape, e.g.:

     ~s "Re: your message"

   Finally, to edit all headers, type `~h' escape. This will present
you with the values of `To', `Cc', `Bcc', and `Subject' headers
allowing to edit them with normal text editing commands.

Enclosing Another Message: ~m and ~M
....................................

If you are sending mail from within mail command mode, you can enclose
the contents of any message sent to you by using `~m' or `~M' commands.
Typing `~m' alone will enclose the contents of the current message,
typing `~m 12' will enclose the contents of message #12 and so on.

   The `~m' uses retained and ignored lists when enclosing headers, the
`~M' encloses all header fields.

   In both cases, the contents of `indentprefix' mail variable is
prepended to each line enclosed.

Adding a File to the Message: ~r and ~d
.......................................

To append the contents of file FILENAME to the message, type

     ~r FILENAME
   or

     ~< FILENAME
   The `~d' escape is a shorthand for

     ~r dead.letter

Printing And Saving the Message
...............................

The `~p' escape types the contents of the message entered so far,
including headers, on your terminal. You can save the message to an
arbitrary file using `~w' escape. It takes the filename as its argument.

Signing the Message: ~a and ~A
..............................

To save you the effort of typing your signature at the end of each
message, you can use `~a' or `~A' escapes. If your signature occupies
one line only, save it to the variable `sign' and use `~a' escape to
insert it. Otherwise, if it is longer than one line, save it to a file,
store the name of this file in the variable `Sign', and use `~A' escape
to insert it into the message.

Printing Another Message: ~f and ~F
...................................

Sometimes it is necessary to view the contents of another message,
while composing. These two escapes allow it. Both take the message list
as their argument. If they are used without argument, the contents of
the current message is printed. The difference between `~f' and `~F' is
that the former uses ignored and retained lists to select headers to be
displayed, whereas the latter prints all headers.

Inserting Value of a Mail Variable: ~i
......................................

The `~i' escape enters the value of the named mail variable into the
body of the message being composed.

Executing Other Mail Commands: ~: and ~-
........................................

You can execute a mail command from within compose mode using `~:' or
`~-' escapes. For example, typing

     ~: from :t
   will display the from lines of all tagged messages. Note, that
executing mail-sending commands from within the compose mode is not
allowed.  An attempt to execute such a command will result in
diagnostic message "Command not allowed in an escape sequence" being
displayed.  Also, when starting compose mode immediately from the shell
(e.g. running `mail address@domain'), most mail commands are
meaningless, since there is no mailbox to operate upon. In this case,
the only commands that can reasonably be used are: `alias', `unalias',
`alternate', `set', and `unset'.

Executing Shell Commands: ~! and ~|
...................................

The `~!' escape executes specified command and returns you to `mail'
compose mode without altering your message. When used without
arguments, it starts your login shell. The `~|' escape pipes the
message composed so far through the given shell command and replaces the
message with the output the command produced. If the command produced
no output, `mail' assumes that something went wrong and retains the old
contents of your message.

2.4.4 Reading Mail
------------------

To read messages from a given mailbox, use one of the following ways of
invoking `mail':

`mail'
     To read messages from your system mailbox.

`mail --file'
     To read messages from your mailbox (`$HOME/mbox').

`mail --file=PATH_TO_MAILBOX'
     To read messages from the specified mailbox.

`mail --user=USER'
     To read messages from the system mailbox belonging to USER.

   _Please note_, that usual mailbox permissions won't allow you to use
the last variant of invocation, unless you are a super-user.
Similarly, the last but one variant is also greatly affected by the
permissions the target mailbox has.

   Unless you have started mail with `--norc' command line option, it
will read the contents of the system-wide configuration file.  Then it
reads the contents of user configuration file, if any.  For detailed
description of these files, see *note Mail Configuration Files::.
After this initial setup, `mail' displays the first page of header
lines and enters interactive mode. In interactive mode, `mail' displays
its prompt (`?', if not set otherwise) and executes the commands the
user enters.

Quitting the Program
....................

Following commands quit the program:

`quit'
     Terminates the session. If `mail' was operating upon user's system
     mailbox, then all undeleted and unsaved messages that have been
     read and are not marked with hold flag are saved to the user's
     mbox file (`$HOME/mbox'). The messages, marked with `delete' are
     removed.  The program exits to the Shell, unless saving the
     mailbox fails, in which case user can escape with the exit command.

`exit'
`ex'
`xit'
     Program exits to the Shell without modifying the mailbox it
     operates upon.

   Typing EOF (`C-D') alone is equivalent to `quit'.

Obtaining Online Help
.....................

Following commands can be used during the session to request online
help:

`help [COMMAND]'
`hel [COMMAND]'
`? [COMMAND]'
     Display detailed command synopsis. If no COMMAND is given, help for
     all available commands is displayed.

`list'
`*'
     Print a list of available commands.

`version'
`ve'
     Display program version.

`warranty'
`wa'
     Display program warranty statement.

Moving Within a Mailbox
.......................

`^'
     Move to the first undeleted message.

`$'
     Move to the last undeleted message.

`next'
`n'
     Move to the next message.

`previous'
`prev'
     Move to the previous message.

Changing Mailbox/Directory
..........................

`cd [DIR]'
`chdir [DIR]'
`ch [DIR]'
     Change to the specified directory. If DIR is omitted, `$HOME' is
     assumed.

`file [MAILBOX]'
`fi [MAILBOX]'
`folder [MAILBOX]'
`fold [MAILBOX]'
     Read in the contents of the specified MAILBOX. The current mailbox
     is updated as if `quit' command has been issued.  If MAILBOX is
     omitted, the command prints the current mailbox name followed by
     the summary information regarding it, e.g.:

          & fold
          "/var/spool/mail/gray": 23 messages 22 unread

Controlling Header Display
..........................

To control which headers in the message should be displayed, `mail'
keeps two lists: a "retained" header list and an "ignored" header list.
If "retained" header list is not empty, only the header fields listed
in it are displayed when printing the message.  Otherwise, if "ignored"
header list is not empty, only the headers _not listed_ in this list
are displayed. The uppercase variants of message-displaying commands
can be used to print all the headers.

   The following commands modify and display the contents of both lists.

`discard [HEADER-FIELD-LIST]'
`di [HEADER-FIELD-LIST]'
`ignore [HEADER-FIELD-LIST]'
`ig [HEADER-FIELD-LIST]'
     Add HEADER-FIELD-LIST to the ignored list. When used without
     arguments, this command prints the contents of ignored list.

`retain [HEADER-FIELD-LIST]'
`ret [HEADER-FIELD-LIST]'
     Add HEADER-FIELD-LIST to the retained list. When used without
     arguments, this command prints the contents of retained list.

Displaying Information
......................

`='
     Displays the current message number.

`headers [MSGLIST]'
`h [MSGLIST]'
     Lists the current pageful of headers.

`from [MSGLIST]'
`f [MSGLIST]'
     Lists the contents of `From' headers for a given set of messages.

`z [ARG]'
     Presents message headers in pagefuls as described for `headers'
     command. When ARG is `.', it is generally equivalent to `headers'.
     When ARG is omitted or is `+', the next pageful of headers is
     displayed. If ARG is `-', the previous pageful of headers is
     displayed. The latter two forms of `z' command may also take a
     numerical argument meaning the number of pages to skip before
     displaying the headers. For example:

          & z +2
     will skip two pages of messages before displaying the header
     summary.

`size [MSGLIST]'
`si [MSGLIST]'
     Lists the message number and message size in bytes for each
     message in MSGLIST.

`folders'
     Displays the value of `folder' variable.

`summary'
`su'
     Displays current mailbox summary. E.g.:

          & summary
          "/var/spool/mail/gray": 23 messages 22 unread

Displaying Messages
...................

`print [MSGLIST]'
`p [MSGLIST]'

`type [MSGLIST]'
`t [MSGLIST]'
     Prints out the messages from MSGLIST. The variable `crt'
     determines the minimum number of lines the body of the message must
     contain in order to be piped through pager command specified by
     environment variable `PAGER'. If `crt' is set to a numeric value,
     this value is taken as the minimum number of lines. Otherwise, if
     `crt' is set without a value then the height of the terminal
     screen is used to compute the threshold. The number of lines on
     screen is controlled by `screen' variable.

`Print [MSGLIST]'
`P [MSGLIST]'
`Type [MSGLIST]'
`T [MSGLIST]'
     Like print but also prints out ignored header fields.

`decode [MSGLIST]'
`dec [MSGLIST]'
     Print a multipart message. The `decode' command decodes and prints
     out specified message parts. E.g.
          & decode 15[2]
          +---------------------------------------
          | Message=15[2]
          | Type=message/delivery-status
          | encoding=7bit
          +---------------------------------------
          Content-Type: message/delivery-status
          ...

`top [MSGLIST]'
`to [MSGLIST]'
     Prints the top few lines of each message in MSGLIST. The number of
     lines printed is controlled by the variable `toplines' and
     defaults to five.

`pipe [MSGLIST] [SHELL-COMMAND]'
`| [MSGLIST] [SHELL-COMMAND]'
     Pipe the contents of specified messages through SHELL-COMMAND. If
     SHELL-COMMAND is empty but the string variable `cmd' is set, the
     value of this variable is used as a command name.

Marking Messages
................

`tag [MSGLIST]'
`ta [MSGLIST]'
     Tag messages. The tagged messages can be referred to in message
     list using `:t' notation.

`untag [MSGLIST]'
`unt [MSGLIST]'
     Clear tags from specified messages. To untag all messages tagged
     so far type
          & untag :t

`hold [MSGLIST]'
`ho [MSGLIST]'
`preserve [MSGLIST]'
`pre [MSGLIST]'
     Marks each message to be held in user's system mailbox. This
     command does not override the effect of `delete' command.

Disposing of Messages
.....................

`delete [MSGLIST]'
`d [MSGLIST]'
     Mark messages as deleted. Upon exiting with `quit' command these
     messages will be deleted from the mailbox. Until the end of current
     session the deleted messages can be referred to in message lists
     using :d notation.

`undelete [MSGLIST]'
`u [MSGLIST]'
     Clear delete mark from the specified messages.

`dp [MSGLIST]'
`dt [MSGLIST]'
     Deletes the current message and prints the next message. If
     MSGLIST is specified, deletes all messages from the list and
     prints the message, immediately following last deleted one.

Saving Messages
...............

`save [[MSGLIST] FILE]'
`s [[MSGLIST] FILE]'
     Takes a message list and a file name and appends each message in
     turn to the end of the file. The name of file and number of
     characters appended to it is echoed on the terminal. Each saved
     message is marked for deletion as if with `delete' command, unless
     the variable `keepsave' is set.

`Save [MSGLIST]'
`S [MSGLIST]'
     Like `save', but the file to append messages to is named after the
     sender of the first message in MSGLIST. For example:

          & from 14 15
           U  14 smith@noldor.org Fri Jun 30 18:11  14/358   The Save c
           U  15 gray@noldor.org  Fri Jun 30 18:30  8/245    Re: The Sa
          & Save 14 15
          "smith" 22/603
     i.e., 22 lines (603 characters) have been appended to the file
     "smith".  If the file does not exist, it is created.

`write [[MSGLIST] FILE]'
`w [[MSGLIST] FILE]'
     Similar to `save', except that only message body (without the
     header) is saved.

`Write [MSGLIST]'
`W [MSGLIST]'
     Similar to `Save', except that only message body (without the
     header) is saved.

`mbox [MSGLIST]'
`mb [MSGLIST]'
`touch [MSGLIST]'
`tou [MSGLIST]'
     Mark list of messages to be saved in the user's mailbox
     (`$HOME/mbox') upon exiting via `quit' command. This is the
     default action for all read messages, unless you have variable
     `hold' set.

`copy [[MSGLIST] FILE]'
`c [[MSGLIST] FILE]'
     Similar to `save', except that saved messages are not marked for
     deletion.

`Copy [MSGLIST]'
`C [MSGLIST]'
     Similar to `Save', except that saved messages are not marked for
     deletion.

Editing Messages
................

These command allow to edit messages in a mailbox. _Please note_, that
modified messages currently do not replace original ones. i.e.  you
have to save them explicitly using your editor's `save' command if you
do not want the effects of your editing to be lost.

`edit [MSGLIST]'
`e [MSGLIST]'
     Edits each message in MSGLIST with the editor, specified in
     `EDITOR' environment variable.

`visual [MSGLIST]'
`v [MSGLIST]'
     Edits each message in MSGLIST with the editor, specified in
     `VISUAL' environment variable.

Aliasing
........

`alias [alias [ADDRESS...]]'
`a [alias [ADDRESS...]]'
`group [alias [ADDRESS...]]'
`g [alias [ADDRESS...]]'
     With no arguments, prints out all currently-defined aliases.  With
     one argument, prints out that alias.  With more than one argument,
     creates a new alias or changes an old one.

`unalias [ALIAS...]'
`una [ALIAS...]'
     Takes a list of names defined by alias commands and discards the
     remembered groups of users. The alias names no longer have any
     significance.

`alternates NAME...'
`alt NAME...'
     The alternates command is useful if you have accounts on several
     machines. It can be used to inform mail that the listed addresses
     are really you. When you reply to messages, mail will not send a
     copy of the message to any of the addresses listed on the
     alternates list.  If the alternates command is given with no
     argument, the current set of alternate names is displayed.

Replying
........

`mail [ADDRESS...]'
`m [ADDRESS...]'
     Switches to compose mode. After composing the message, sends
     messages to the specified addresses.

`reply [MSGLIST]'
`respond [MSGLIST]'
`r [MSGLIST]'
     For each message in MSGLIST, switches to compose mode and sends
     the composed message to the sender and all recipients of the
     message.

`Reply [MSGLIST]'
`Respond [MSGLIST]'
`R [MSGLIST]'
     Like `reply', except that the composed message is sent only to
     originators of the specified messages.

     Notice, that setting mail variable `flipr' (*note Mail
     Variables::) swaps the meanings of the two above commands, so that
     `reply' sends the message to the sender and all recipients of the
     message, whereas `Reply' sends it to originators only.

`followup [MSGLIST]'
`fo [MSGLIST]'
     Switches to compose mode. After composing, sends the message to the
     originators and recipients of all messages in MSGLIST.

`Followup [MSGLIST]'
`F [MSGLIST]'
     Similar to `followup', but reply message is sent only to
     originators of messages in MSGLIST.

   To determine the sender of the message `mail' uses the list of
sender fields (*note Controlling Sender Fields::). The first field from
this list is looked up in message headers. If it is found and contains
a valid email address, this address is used as the sender address. If
not, the second field is searched and so on. This process continues
until a field is found in the headers, or the sender field list is
exhausted, whichever happens first.

   If the previous step did not determine the sender address, the
address from SMTP envelope is used.

   Let's illustrate this. Suppose your mailbox contains the following:

      U  1 block@helsingor.org  Fri Jun 30 18:30  8/245    Re: The Sa
     & Print 1
     From: Antonius Block <block@helsingor.org>
     To: Smeden Plog <plog@helsingor.org>
     Date: Tue, 27 Apr 2004 13:23:41 +0300
     Reply-To: <root@helsingor.org>
     Subject: News

     Hi

Now, you issue the following commands:

     & sender mail-followup-to reply-to from
     & reply
     To: <root@helsingor.org>
     Subject: Re: News

As you see, the value of `Reply-To' field was taken as the sender
address.

   Now, let's try the following command sequence:

     # Clear the sender list
     & nosender
     # Set new sender list
     & sender From

Now, the `From' address will be taken:

     & reply
     To: Antonius Block <block@helsingor.org>
     Subject: Re: News

Controlling Sender Fields
.........................

Commands `sender' and `nosender' are used to manipulate the contents of
the sender field list.

   If the command `sender' is used without arguments, it displays the
contents of the sender field list. If arguments are given, each
argument is appended to the sender field list. For example:

     & sender
     Sender address is obtained from the envelope
     & sender mail-followup-to reply-to
     & sender
     mail-followup-to
     reply-to
     & sender from
     & sender
     mail-followup-to
     reply-to
     from

   Command `nosender' is used to remove items from the sender field
list:

     & sender
     mail-followup-to
     reply-to
     from
     & nosender reply-to
     & sender
     mail-followup-to
     from

   When used without arguments, this command clears the list:

     & nosender
     Sender address is obtained from the envelope

Incorporating New Mail
......................

The `incorporate' (`inc') command incorporates newly arrived messages
to the displayed list of messages. This is done automatically before
returning to `mail' command prompt if the variable `autoinc' is set.

Shell Escapes
.............

To run arbitrary shell command from `mail' command prompt, use `shell'
(`sh') command. If no arguments are specified, the command starts the
user login shell. Otherwise, it uses its first argument as a file name
to execute and all subsequent arguments are passed as positional
parameters to this command. The `shell' command can also be spelled as
`!'.

2.4.5 Scripting
---------------

Comments
........

The `#' character introduces an end-of-line comment. All characters
until and including the end of line are ignored.

Displaying Arbitrary Text
.........................

The `echo' (`ec') command prints its arguments to stdout.

Sourcing External Command Files
...............................

The command `source FILENAME' reads commands from the named file. Its
minimal abbreviation is `so'.

Setting and Unsetting the Variables
...................................

The mail variables may be set using `set' (`se') command. The command
takes a list of assignments. The syntax of an assignment is

`NAME=STRING'
     Assign a string value to the variable. If STRING contains
     whitespace characters it must be enclosed in a pair of
     double-quote characters (`"')

`NAME=NUMBER'
     Assign a numeric value to the variable.

`NAME'
     Assign boolean `True' value.

`noNAME'
     Assign boolean `False' value.

   Example:

     & set askcc nocrt indentprefix="> "
   This statement sets `askcc' to `True', `crt' to `False', and
`indentprefix' to "> ".

   To unset mail variables use `unset'(`uns') command. The command
takes a list of variable names to unset.

   Example: To undo the effect of the previous example, do:

     & unset askcc crt indentprefix

Setting and Unsetting Shell Environment Variables
.................................................

Shell environment may be modified using `setenv' (`sete') command. The
command takes a list of assignments. The syntax of an assignment is:

`NAME=VALUE'
     If variable NAME does not already exist in the environment, then
     it is added to the environment with the value VALUE.  If NAME does
     exist, then its value in the environment is changed to VALUE.

`NAME'
     Delete the variable NAME from the environment ("unset" it).

Conditional Statements
......................

The conditional statement allows to execute a set of mail commands
depending on the mode the `mail' program is in. The conditional
statement is:

     if COND
     ...
     else
     ...
     endif
   where `...' represents the set of commands to be executed in each
branch of the statement. COND can be one of the following:

`s'
     True if `mail' is operating in mail sending mode.

`r'
     True if `mail' is operating in mail reading mode.

`t'
     True if stdout is a terminal device (as opposed to a regular file).

   The conditional statements can be nested to arbitrary depth. The
minimal abbreviations for `if', `else' and `endif' commands are `i',
`el' and `en'.

   Example:

     if t
     set crt prompt="& "
     else
     unset prompt
     endif
     if s
     alt gray@farlep.net gray@mirddin.farlep.net
     set

2.4.6 How to Alter the Behavior of `mail'
-----------------------------------------

Following variables control the behavior of GNU `mail':

`appenddeadletter'
     Type: Boolean.
     Default: False.  

     If this variable is `True', the contents of canceled letter is
     appended to the user's `dead.letter' file. Otherwise it overwrites
     its contents.

`askbcc'
     Type: Boolean.
     Default: False.  

     When set to `True' the user will be prompted to enter `Bcc' field
     before composing the message.

`askcc'
     Type: Boolean.
     Default: True.  

     When set to `True' the user will be prompted to enter `Cc' field
     before composing the message.

`asksub'
     Type: Boolean.
     Default: True in interactive mode, False otherwise.  

     When set to `True' the user will be prompted to enter `Subject'
     field before composing the message.

`autoinc'
     Type: Boolean.
     Default: True.  

     Automatically incorporate newly arrived messages.

`autoprint'
     Type: Boolean.
     Default: False.  

     Causes the delete command to behave like dp - thus, after deleting
     a message, the next one will be typed automatically.

`bang'
     Type: Boolean.
     Default: False.  

     When set, every occurrence of `!' in arguments to `!' command is
     replaced with the last executed command.

`datefield'
     Type: Boolean.
     Default: False.  

     By default the date in a header summary is taken from the SMTP
     envelope of the message. Setting this variable tells `mail' to use
     the date from `Date:' header field, converted to local time.
     Notice, that for messages lacking this field `mail' will fall back
     to using SMTP envelope.

`charset'
     Type: string
     Default: `auto' 

     The value of this variable controls the output character set for
     the header fields encoding using RFC 2047. If the variable is
     unset, no decoding is performed and the fields are printed as they
     are. If the variable is set to `auto', `mail' tries to deduce the
     name of the character set from the value of `LC_ALL' environment
     variable. Otherwise, its value is taken as the name of the charset.

`cmd'
     Type: String.
     Default: Unset.  

     Contains default shell command for `pipe'.

`columns'
     Type: Numeric.
     Default: Detected at startup by querying the terminal device. If
     this fails, the value of environment variable `COLUMNS' is used.  

     This variable contains the number of columns on terminal screen.

`crt'
     Type: Boolean or Numeric
     Default: True in interactive mode, False otherwise.  

     The variable `crt' determines the minimum number of lines the body
     of the message must contain in order to be piped through pager
     command specified by environment variable `PAGER'. If `crt' is set
     to a numeric value, this value is taken as the threshold.
     Otherwise, if `crt' is set without a value, then the height of the
     terminal screen is used to compute the threshold. The number of
     lines on screen is controlled by `screen' variable.

`decode-fallback'
     Type: String.
     Default: `none'.  

     This variable controls the way to represent characters that cannot
     be rendered using current character set. It can have three values:

    `none'
          Such characters are not printed at all. The conversion
          process stops at the first character that cannot be rendered.

    `copy-pass'
          The characters are displayed `as is'. Notice, that depending
          on your setup, this may screw-up your terminal settings.

    `copy-octal'
          Unprintable characters are represented by their octal codes.
          Printable ones are printed `as is'.

`dot'
     Type: Boolean.
     Default: False.  

     If `True', causes `mail' to interpret a period alone on a line as
     the terminator of a message you are sending.

`emptystart'
     Type: Boolean.
     Default: False.  

     If the mailbox is empty, `mail' normally prints `No mail for user'
     and exits immediately. If this option is set, `mail' will start no
     matter is the mailbox empty or not.

`editheaders'
     Type: Boolean.
     Default: False.  

     When set, `mail' will include message headers in the text to be
     the `~e' and `~v' escapes, thus allowing you to customize the
     headers.

`escape'
     Type: String.
     Default: ~ 

     If defined, the first character of this option gives the character
     to denoting escapes.

`flipr'
     Type: Boolean
     Default: Unset 

     The variable `flipr' if set swaps the meanings of `reply' and
     `Reply' commands (*note Replying::).

`folder'
     Type: String.
     Default: Unset.  

     The name of the directory to use for storing folders of messages.
     If unset, `$HOME' is assumed.

`header'
     Type: Boolean.
     Default: True, unless started with `--nosum' (`-N') option.  

     Whether to run `headers' command automatically after entering
     interactive mode.

`hold'
     Type: Boolean.
     Default: False.  

     When set to `True', the read or saved messages will be stored in
     user's mailbox (`$HOME/mbox'). Otherwise, they will be held in
     system mailbox also. This option is in effect only when operating
     upon user's system mailbox.

`ignore'
     Type: Boolean.
     Default: False.  

     When set to `True', `mail' will ignore keyboard interrupts when
     composing messages. Otherwise an interrupt will be taken as a
     signal to abort composing.

`ignoreeof'
     Type: Boolean.
     Default: False.  

     Controls whether typing EOF character terminates the letter being
     composed.

`indentprefix'
     Type: String.
     Default: "\t" (a tab character).  

     String used by the `~m' tilde escape for indenting quoted messages.

`inplacealiases'
     Type: Boolean
     Default: False

     If set, `mail' will expand aliases in the address header field
     before entering send mode (*note Composing Mail::). By default, the
     address header fields are left intact while composing, the alias
     expansion takes place immediately before sending message.

`keepsave'
     Type: Boolean.
     Default: False.  

     Controls whether saved messages should be kept in system mailbox
     too.  This variable is in effect only when operating upon a user's
     system mailbox.

`mailx'
     Type: Boolean.
     Default: False.  

     When set, enables "mailx compatibility mode". This mode has the
     following effects:

        * When composing a message `mail' will ask for `Cc' and `Bcc'
          addresses after composing the body.  The default behavior is
          to ask for these values before composing the body.

        * In send mode, if the composition was interrupted, `mail' will
          exit with zero status. By default it exits with zero status
          only if the message was sent successfully.

`metamail'
     Type: Boolean or String.
     Default: True.  

     This variable controls operation of `decode' command. If it is
     unset, `decode' will not attempt any interpretation of the content
     of message parts. Otherwise, if `metamail' is set to `true',
     `decode' will use internal metamail support to interpret message
     parts. Finally, if `metamail' is assigned a string, this string is
     treated as command line of the external `metamail' command which
     will be used to display parts of a multipart message. For example:

          # Disable MIME interpretation:
          set nometamail
          # Enable built-in MIME support:
          set metamail
          # Use external program to display MIME parts:
          set metamail="metamail -m mail -p"

`mimenoask'
     Type: String
     Default: Empty 

     By default `mail' asks for confirmation before running interpreter
     to view a part of the multi-part message. If this variable is set,
     its value is treated as a comma-separated list of MIME types for
     which no confirmation is needed. Elements of this list may include
     shell-style globbing patterns, e.g. setting

          set mimenoask=text/*,image/jpeg

     will disable prompting before displaying any textual files, no
     matter what their subtype is, and before displaying files with
     type `image/jpeg'.

`metoo'
     Type: Boolean.
     Default: False.  

     Usually, when an alias is expanded that contains the sender, the
     sender is removed from the expansion. Setting this option causes
     the sender to be included in the group.

`mode'
     Type: String.
     Default: The name of current operation mode.  

     Setting this variable does not affect the operation mode of the
     program.

`nullbody'
     Type: Boolean
     Default: True 

     Controls whether `mail' accepts messages with an empty body. The
     default value, `true', means such messages are sent, and a warning
     (traditionally saying `Null message body; hope that's ok') is
     displayed. The text of the warning can be set using `nullbodymsg'
     variable (see below).

     If `nullbody' is unset, `mail' will silently ignore such messages.
     This can be useful in `crontab' files, to avoid sending mails when
     nothing important happens. For example, the `crontab' entry below
     will send mail only if the utility `some-prog' outputs something
     on its standard output or error:

          */5 * * * * some-prog 2>&1 | \
             /bin/mail -E'set nonullbody' -s 'Periodic synchronization'

`nullbodymsg'
     Type: String
     Default: Null message body; hope that's ok 

     Keeps the text of the warning, displayed by `mail' before sending
     an empty message. When available, the translation of this text, in
     accordance with the current locale, is displayed.

     Unsetting this variable disables the warning.

`outfolder'
     Type: String.
     Default: Unset.  

     Contains the directory in which files created by `save', `write',
     etc. commands will be stored. When unset, current directory is
     assumed.

`page'
     Type: Boolean.
     Default: False.  

     If set to `True', the `pipe' command will emit a linefeed
     character after printing each message.

`prompt'
     Type: String.
     Default: "? " 

     Contains the command prompt sequence.

`quit'
     Type: Boolean.
     Default: False, unless started with `--quit' (`-q') option.  

     When set, causes keyboard interrupts to terminate the program.

`rc'
     Type: Boolean.
     Default: True, unless started with `--norc' (`-N') option.  

     When this variable is set, `mail' will read the system-wide
     configuration file upon startup. See *note Mail Configuration
     Files::.

`record'
     Type: String.
     Default: Unset.  

     When set, any outgoing message will be saved to the named file.

`recursivealiases'
     Type: Boolean
     Default: True

     When set, `mail' will expand aliases recursively.

`regex'
     Type: Boolean.
     Default: True.  

     Setting this to `True' enables use of regular expressions in
     `/.../' message specifications.

`replyprefix'
     Type: String
     Default: `Re: ' 

     Sets the prefix that will be used when constructing the subject
     line of a reply message.

`replyregex'
     Type: String
     Default: `^re: *' 

     Sets the regular expression used to recognize subjects of reply
     messages. If the `Subject' header of the message matches this
     expression, the value of `replyprefix' will not be prepended to it
     before replying. The expression should be a POSIX extended regular
     expression. The comparison is case-insensitive.

     For example, to recognize usual English, Polish, Norwegian and
     German reply subject styles, use:

          set replyregex="^(re|odp|aw|ang)(\\[[0-9]+\\])?:[[:blank:]]"

     (Notice the quoting of backslash characters).

`save'
     Type: Boolean.
     Default: True.  

     When set, the aborted messages will be stored in the user's
     `dead.file'. See also `appenddeadletter'.

`screen'
     Type: Numeric.
     Default: Detected at startup by querying the terminal device. If
     this fails, the value of environment variable `LINES' is used.  

     This variable contains the number of lines on terminal screen.

`sendmail'
     Type: String.
     Default: sendmail:/usr/lib/sendmail 

     Contains the URL of mail transport agent.

`Sign'
     Type: String.
     Default: Unset.  

     Contains the filename holding users signature. The contents of this
     file is appended to the end of a message being composed by `~A'
     escape.

`sign'
     Type: String.
     Default: Unset.  

     Contains the user's signature. The contents of this variable is
     appended to the end of a message being composed by `~a' escape. Use
     `Sign' variable, if your signature occupies more than one line.

`showto'
     Type: Boolean
     Default: unset 

     If this variable is set, `mail' will show `To:' addresses instead
     of `From:' for all messages that come from the user that invoked
     the program.

`subject'
     Type: String.
     Default: Unset.  

     Contains default subject line. This will be used when `asksub' is
     off.

`toplines'
     Type: Numeric.
     Default: 5 

     Number of lines to be displayed by `top' and `Top' commands.

`verbose'
     Type: Boolean.
     Default: False.  

     When set, the actual delivery of messages is displayed on the
     user's terminal.

`xmailer'
     Type: Boolean.
     Default: Set.  

     Controls whether the header `X-Mailer' should be added to outgoing
     messages. The default value of this header is

          X-Mailer: mail (GNU Mailutils 2.0)


2.4.7 Personal and System-wide Configuration Files
--------------------------------------------------

Upon startup, `mail' reads the contents of the two command files: the
system-wide configuration file, and the user's configuration file. Each
line read from these files is processed like a usual `mail' command.

   When run with `--norc' (`-N') option, `mail' does not read the
contents of system-wide configuration file. The user's file, if it
exists, is always processed.

   The user's configuration file is located in the user's home
directory and is named `.mailrc'. The location and name of the
system-wide configuration file is determined when configuring the
package via `--with-mail-rc' option. It defaults to
`SYSCONFDIR/mail.rc'.

2.5 `messages' -- Count the Number of Messages in a Mailbox
===========================================================

`Messages' prints on standard output the number of messages contained
in each folder specified in command line. If no folders are specified,
it operates upon user's system mailbox. For each folder, the following
output line is produced:

     Number of messages in FOLDER: NUMBER

where FOLDER represents the folder name, NUMBER represents the number
of messages.

   Following configuration file statements affect the behaviour of
`messages':

Statement              Reference
------------------------------------------------------------------- 
debug                  *Note Debug Statement::.
tls                    *Note TLS Statement::.
mailbox                *Note Mailbox Statement::.
locking                *Note Locking Statement::.

   The program accepts following command line options:

`-q'
`--quiet'
`-s'
`--silent'
     Be quiet. Display only number of messages per mailbox, without
     leading text.

`-?'
`--help'
     Output help message and exit.

`--usage'
     Output short usage summary and exit.

`-V'
`--version'
     Output program version and exit.

2.6 `movemail' -- Moves Mail from the User Maildrop to the Local File
=====================================================================

The purpose of `movemail', as its name implies, is to move mail from
one location to another. For example, the following invocation:

     movemail /var/mail/smith INBOX

moves messages from file `/var/mail/smith' to file `INBOX'.

   You will probably never have to run this program manually. It is
intended as a replacement for `movemail' from GNU Emacs. The `movemail'
program is run by Emacs `Rmail' module. *Note Rmail: (emacs)Rmail, for
detailed description of `Rmail' interface.

   Mailutils version of `movemail' is completely backward-compatible
with its Emacs predecessor, so it should run flawlessly with older
versions of Emacs. Emacs version 21.4, which is being developed at the
time of this writing, will contain improved `Rmail' interface for work
with mailutils `movemail'.

2.6.1 Movemail Configuration
----------------------------

Following configuration file statements affect the behavior of
`movemail':

 -- Movemail Config: preserve BOOL
     If BOOL is `true', do not remove messages from the source mailbox.

 -- Movemail Config: reverse BOOL
     If BOOL is `true', reverse message sorting order.

 -- Movemail Config: emacs BOOL
     If BOOL is `true', output information used by Emacs rmail
     interface.

Statement              Reference
------------------------------------------------------------------- 
debug                  *Note Debug Statement::.
tls                    *Note TLS Statement::.
mailbox                *Note Mailbox Statement::.
locking                *Note Locking Statement::.
pam                    *Note PAM Statement::.
sql                    *Note SQL Statement::.
virtdomain             *Note Virtdomain Statement::.
radius                 *Note Radius Statement::.
ldap                   *Note LDAP Statement::.
auth                   *Note Auth Statement::.

2.6.2 Movemail Options
----------------------

This subsection discusses `movemail' options from the point of view of
an Emacs `Rmail' user.

   To set various options to `movemail' from `Rmail', use
`rmail-movemail-flags' variable, or `Rmail Movemail Flags' section from
the menu.

   Some POP servers return messages in reversed order. To fix the
order, use `-p' option or its synonym `--reverse'.

   If the remote server supports TLS encryption, use `--tls' to
instruct `movemail' to initiate encrypted connection.

   Quite a few options control how `movemail' handles mail locking (a
way of preventing simultaneous access to the source mailbox). By
default, before accessing mailbox FILE, `movemail' will first see if
the file named `FILE.lock' (so called "lock file") exists. If so, it
will assume that the mailbox is being used by another program and will
sleep one second. If `FILE.lock' file disappears after this wait
period, the program will proceed. Otherwise, it will repeat this action
ten times. If after ten wait periods the lock file does not disappear,
`movemail' gives up and exits.

   If the lock file does not exist, `movemail' will create it, thereby
indicating to other programs that the mailbox is being used, and will
proceed to copying messages to the destination file. When finished,
`movemail' closes the mailbox and removes the lock file.

   Several options control this behavior. To change the default sleep
period use `--lock-retry-timeout'. Its argument is the timeout value in
seconds.

   To change number of retries, use `--lock-retry-count'. For example,
setting `rmail-movemail-flags' to

     --lock-retry-timeout=2 --lock-retry-count=5

instructs `movemail' to make five attempts to acquire the lock file,
with two-second intervals between the attempts.

   You may also force `movemail' to remove the lock file if it is older
than a given amount of time (a so called "stale lock file"). To do so,
use the following option:

     --lock-expire-timeout=SECONDS

   The `--lock-expire-timeout' sets the number of seconds after which a
lock file is considered stale.

   There are special programs that can be used to lock and unlock
mailboxes. A common example of such programs is `dotlock'. If you wish
to use such "external locking program" instead of the default mailutils
locking mechanism, use option `--external-locker'. Argument to this
option specifies the full name of the external program to use.

2.6.3 Summary of Movemail Usage
-------------------------------

     movemail [OPTION...] INBOX DESTFILE [REMOTE-PASSWORD]

   The first argument, INBOX, is the url (*note URL::) of the source
mailbox. The second argument, DESTFILE, traditionally means destination
file, i.e. the UNIX mailbox to copy messages to. However, mailutils
`movemail' extends the meaning of this parameter. You may actually
specify any valid url as DESTFILE parameter.(1). Finally, optional
third argument is a traditional way of specifying user passwords for
remote (POP or IMAP) mailboxes.

   Following is the summary of available command line options:

`--emacs'
     Output information used by Emacs rmail interface

`-p'
`--preserve'
`--keep-messages'
     Preserve the source mailbox

`-r'
`--reverse'
     Reverse the sorting order

`--license'
     Print GPL license and exit

`--external-locker=PROGRAM'
     Use given PROGRAM as the external locker program.

`--lock-expire-timeout=SECONDS'
     Set number of seconds after which the lock expires

`--lock-flags=FLAGS'
     Set locker flags. FLAGS is composed of the following letters: `E'
     - use external locker program `dotlock', `R' - retry 10 times if
     acquiring of the lock failed (see also `--lock-retry-count'
     below), `T' - remove stale locks after 10 minutes (see also
     `--lock-expire-timeout', and `P' - write process PID to the lock
     file.

`--lock-retry-count=NUMBER'
     Set the maximum number of times to retry acquiring the lockfile

`--lock-retry-timeout=SECONDS'
     Set timeout for acquiring the lockfile

`-m URL'
`--mail-spool URL'
     Use specified URL as a mailspool directory

`--tls[=BOOL]'
     Enable (default) or disable TLS support


   ---------- Footnotes ----------

   (1) Rmail does not use this feature

2.7 `readmsg' -- Extract Messages from a Folder
===============================================

The `readmsg' utility extracts messages from a mailbox according to the
criteria specified in the command line. These criteria are:

  1. A lone `*' means "select all messages in the mailbox".

  2. A list of message numbers may be specified. Values of  `0'  and
     `$' in the list both mean the last message in the mailbox. For
     example:
          readmsg 1 3 0
     extracts three messages from the folder: the first, the third, and
     the last.

  3. Finally, the selection may be some text to match. This will select
     a mail message which exactly matches the specified text. For
     example,
          readmsg staff meeting
     extracts the message which contains the words `staff meeting'.
     Note that it will not match a message containing `Staff Meeting' -
     the matching is case sensitive. Normally only the first message
     which matches the pattern is printed.

2.7.1 Invocation of `readmsg'.
------------------------------

`-a'
`--show-all'
     If a pattern is use for selection show all messages that match
     pattern by default only the first one is presented.

`-d'
`--debug'
     Display mailbox debugging information.

`-f MAILBOX'
`--folder=MAILBOX'
     Specified the default mailbox.

`-h'
`--header'
     Show the entire header and ignore the weedlist.

`-n'
`--no-header'
     Do not print the message header.

`-p'
`--form-feed'
     Put form-feed (Control-L) between messages instead of newline.

`-w WEEDLIST'
`--weedlist=WEEDLIST'
     A whitespace or coma separated list of header names to show per
     message.  Default is `--weedlist="From Subject Date To CC
     Apparently-"'.

2.7.2 Configuration of `readmsg'.
---------------------------------

Following configuration statements affect the behavior of `readmsg':

 -- Readmsg Conf: header BOOL
     If BOOL is `true', display entire headers.

 -- Readmsg Conf: weedlist STR
     Set the weedlist. The STR argument is a string, containing a list
     of header names, separated by whitespace, commands or colons. This
     corresponds to the `--weedlist' command line option (*note
     -weedlist: Opt-readmsg.).

 -- Readmsg Conf: no-header BOOL
     If BOOL is `true', exclude all headers.

 -- Readmsg Conf: form-feeds BOOL
     If BOOL is `true', output formfeed character between messages.

 -- Readmsg Conf: folder URL
     Set the URL of the mailbox folder to read.

 -- Readmsg Conf: show-all-match BOOL
     If BOOL is `true', print all messages matching pattern, not only
     the first.

Statement              Reference
------------------------------------------------------------------- 
debug                  *Note Debug Statement::.
tls                    *Note TLS Statement::.
mailbox                *Note Mailbox Statement::.
locking                *Note Locking Statement::.

2.8 `sieve'
===========

Sieve is a language for filtering e-mail messages at time of final
delivery, described in RFC 3028. GNU Mailutils provides two
implementations of this language: a stand-alone "sieve interpreter" and
a "sieve translator and filter". The following sections describe these
utilities in detail.

2.8.1 A Sieve Interpreter
-------------------------

Sieve interpreter `sieve' allows to apply Sieve scripts to an arbitrary
number of mailboxes. GNU `sieve' implements a superset of the Sieve
language as described in RFC 3028. *Note Sieve Language::, for a
description of the Sieve language. *Note GNU Extensions::, for a
discussion of differences between the GNU implementation of Sieve and
its standard.

Invoking `sieve'
................

The `sieve' invocation syntax is:

     sieve [OPTIONS] SCRIPT

where SCRIPT denotes the filename of the sieve program to parse, and
OPTIONS is one or more of the following:

`-c'
`--compile-only'
     Compile script and exit.

`--clear-library-path'
`--clearpath'
     Clear Sieve library path. See also *note clear-library-path: Sieve
     Configuration.

`--clear-include-path'
     Clear Sieve include path. See also *note clear-include-path: Sieve
     Configuration.

`-d[FLAGS]'
`--debug[=FLAGS]'
     Specify debug flags. The FLAGS argument is a sequence of one or
     more of the following letters:

     `g'                         Enable main parser traces
     `T'                         Enable mailutils traces
     `P'                         Trace network protocols
     `t'                         Enable sieve trace
     `i'                         Trace the program instructions

`-D'
`--dump'
     Compile the script, dump disassembled code on standard output and
     exit.

`-e ADDRESS'
`--email ADDRESS'
     Override the user email address. This is useful for `reject' and
     `redirect' actions. By default, the user email address is deduced
     from the user name and the full name of the machine where `sieve'
     is executed. See also *note email: Sieve Configuration.

`-I DIR'
`--includedir=DIR'
     Append directory DIR to the list of directories searched for
     include files. See also *note include-path: Sieve Configuration.

`-f'
`--mbox-url=MBOX'
     Mailbox to sieve (defaults to user's system mailbox). See also
     *note mbox-url: Sieve Configuration.

`-k'
`--keep-going'
     Keep on going if execution fails on a message. See also *note
     keep-going: Sieve Configuration.

`-L DIR'

`--libdir=DIR'
     Append directory DIR to the list of directories searched for
     library files. See also *note library-path: Sieve Configuration.

`-n'
`--no-actions'
     Dry run: do not execute any actions, just print what would be done.

`-t TICKET'
`--ticket=TICKET'
     Ticket file for mailbox authentication. See also *note ticket:
     Sieve Configuration.

`-v'
`--verbose'
     Log all actions executed. See also *note verbose: Sieve
     Configuration.

Sieve Configuration
...................

The behavior of `sieve' is affected by the following configuration
statements:

Statement              Reference
------------------------------------------------------------------- 
debug                  *Note Debug Statement::.
tls                    *Note TLS Statement::.
mailbox                *Note Mailbox Statement::.
locking                *Note Locking Statement::.
logging                *Note Logging Statement::.
mailer                 *Note Mailer Statement::.

   The following statements configure sieve-specific features:

 -- Sieve Conf: sieve { ... }
     This block statement configures search paths `sieve' uses to
     locate its loadable modules. *Note Require Statement::, for a
     detailed information of this feature.

     This statement may contain the following sub-statements:
     `clear-library-path', `clear-include-path', `library-path',
     `include-path', which are described below.

 -- Sieve Conf: clear-library-path BOOL
     Used within the `sieve' block statement.

     If BOOL is `true', clear library search path.

 -- Sieve Conf: clear-include-path BOOL
     Used within the `sieve' block statement.

     If BOOL is `true', clear include search path.

 -- Sieve Conf: library-path PATH
     Used within the `sieve' block statement.

     Add directories to `sieve' library search path. Argument is a
     string containing a colon-separated list of directories.

 -- Sieve Conf: include-path PATH
     Used within the `sieve' block statement.

     Add directories to the include search path. Argument is a string
     containing a colon-separated list of directories.

 -- Sieve Conf: keep-going BOOL
     If BOOL is `true', do not abort if execution of a Sieve script
     fails on a particular message.

 -- Sieve Conf: mbox-url URL
     Sets URL of the mailbox to be processed.

 -- Sieve Conf: ticket FILE
     Sets the name of the ticket file for user authentication.

 -- Sieve Conf: debug FLAGS
     Sets Sieve debug flags. *Note Logging and Debugging::, for a
     detailed description.

 -- Sieve Conf: verbose BOOL
     If BOOL is `true', log all executed actions.

 -- Sieve Conf: line-info BOOL
     If BOOL is `true', print source locations along with action logs.
     This statement takes effect only if `verbose true' is also set.

 -- Sieve Conf: email ADDR
     Set user e-mail address. This is useful for `reject' and
     `redirect' actions. By default, the user email address is deduced
     from the user name and the full name of the machine where `sieve'
     is executed.

Logging and debugging
.....................

The default behavior of `sieve' is to remain silent about anything
except errors. However, it is sometimes necessary to see which actions
are executed and on which messages. This is particularly useful when
debugging the sieve scripts. The `--verbose' (`-v') option outputs log
of every action executed.

   Option `--debug' allows to produce even more detailed debugging
information. This option takes an argument specifying the debugging
level to be enabled. The argument can consist of the following letters:

``t''
     This flag enables sieve tracing. It means that every test will be
     logged when executed.

``T''
     This flag enables debugging of underlying `mailutils' library.

``P''
     Trace network protocols: produces log of network transactions
     executed while running the script.

``g''
     Enable main parser traces. This is useful for debugging the sieve
     grammar.

``i''
     Trace the program instructions. It is the most extensive debugging
     level. It produces the full execution log of a sieve program,
     showing each instruction and states of the sieve machine. It is
     only useful for debugging the code generator.

   _Note_, that there should be no whitespace between the short variant
of the option (`-d'), and its argument. Similarly, when using long
option (`--debug'), its argument must be preceded by equal sign.

   If the argument to `--debug' is omitted, it defaults to `TPt'.

   Option `--dump' produces the disassembled dump of the compiled sieve
program.

   By default `sieve' output all diagnostics on standard error and
verbose logs on standard output. This behaviour is changed when
`--log-facility' is given in the command line ().  This option causes
`sieve' to output its diagnostics to the given syslog facility.

Extending `sieve'
.................

The basic set of sieve actions, tests and comparators may be extended
using loadable extensions. Usual `require' mechanism is used for that.

   When processing arguments for `require' statement, `sieve' uses the
following algorithm:

  1. Look up the name in a symbol table. If the name begins with
     `comparator-' it is looked up in the comparator table. If it
     begins with `test-', the test table is used instead. Otherwise the
     name is looked up in the action table.

  2. If the name is found, the search is terminated.

  3. Otherwise, transform the name. First, any `comparator-' or `test-'
     prefix is stripped. Then, any character other than alphanumeric
     characters, `.' and `,' is replaced with dash (`-'). The name thus
     obtained is used as a file name of an external loadable module.

  4. Try to load the module. The module is searched in the following
     search paths (in the order given):

       1. Mailutils module directory. By default it is
          `$prefix/lib/mailutils'.

       2. The value of the environment variable `LTDL_LIBRARY_PATH'.

       3. Additional search directories specified with the
          `library-path' statement (*note library-path: Sieve
          Configuration.) in Sieve configuration file.

       4. Additional search directories specified with the.  `--libdir'
          command line option ().

       5. Additional search directories specified with the
          `#searchpath' Sieve directive (*note #searchpath::).

       6. System library search path: The system dependent library
          search path (e.g. on Linux it is set by the contents of the
          file `/etc/ld.so.conf' and the value of the environment
          variable `LD_LIBRARY_PATH').

     The value of `LTDL_LIBRARY_PATH' and `LD_LIBRARY_PATH' must be a
     colon-separated list of absolute directories, for example,
     `"/usr/lib/mypkg:/lib/foo"'.

     In any of these directories, `sieve' first attempts to find and
     load the given filename. If this fails, it tries to append the
     following suffixes to the file name:

       1. the libtool archive extension `.la'

       2. the extension used for native dynamic libraries on the host
          platform, e.g., `.so', `.sl', etc.

  5. If the module is found, `sieve' executes its initialization
     function (see below) and again looks up the name in the symbol
     table. If found, search terminates successfully.

  6. If either the module is not found, or the symbol wasn't found
     after execution of the module initialization function, search is
     terminated with an error status. `sieve' then displays the
     following diagnostic message:

          source for the required action NAME is not available

2.8.2 A Sieve to Scheme Translator and Filter
---------------------------------------------

A Sieve to Scheme Translator `sieve.scm' translates a given Sieve
script into an equivalent Scheme program and optionally executes it.
The program itself is written in Scheme and requires presence of Guile
version 1.8 or newer on the system. For more information on Guile refer
to *note Overview: (guile)Top.

`-f FILENAME'
`--file FILENAME'
     Set input file name.

`-o FILENAME'
`--output FILENAME'
     Set output file name

`-L DIRNAME'
`--lib-dir DIRNAME'
     Set sieve library directory name

`-d LEVEL'
`--debug LEVEL'
     Set debugging level

   The Scheme programs produced by `sieve.scm' can be used with `guimb'
or `mail.local'.

2.9 `guimb' -- A Mailbox Scanning and Processing Language
=========================================================

`Guimb' is for mailboxes what `awk' is for text files.  It processes
mailboxes, applying the user-supplied scheme procedures to each of them
in turn and saves the resulting output in mailbox format.

   The following configuration statements affect the behavior of
`guimb':

Statement              Reference
------------------------------------------------------------------- 
debug                  *Note Debug Statement::.
mailbox                *Note Mailbox Statement::.
locking                *Note Locking Statement::.

Specifying Scheme Program to Execute
------------------------------------

The Scheme program or expression to be executed is passed to `guimb'
via the following options:

`-s FILE'
`--source FILE'
     Load Scheme source code from FILE.

`-c EXPR'
`--code EXPR'
     Execute given scheme expression.

   The above switches stop further argument processing, and pass all
remaining arguments as the value of `(command-line)'.

   If the remaining arguments must be processed by `guimb' itself, use
following options:

`-e EXPR'
`--expression EXPR'
     Execute scheme expression.

`-f FILE'
`--file FILE'
     Load Scheme source code from FILE.

   You can specify both of them. In this case, the FILE is read first,
then EXPR is executed. You may still pass any additional arguments to
the script using `--guile-arg' option.

Specifying Mailboxes to Operate Upon
------------------------------------

There are four basic ways of passing mailboxes to `guimb'.

`guimb [OPTIONS] [MAILBOX...]'
     The resulting mailbox is not saved, unless the user-supplied
     scheme program saves it.

`guimb [OPTIONS] --mailbox DEFMBOX'
     The contents of DEFMBOX is processed and is replaced with the
     resulting mailbox contents. Useful for applying filters to user's
     mailbox.

`guimb [OPTIONS] --mailbox DEFMBOX MAILBOX [MAILBOX...]'
     The contents of specified mailboxes is processed, and the resulting
     mailbox contents is appended to DEFMBOX.

`guimb [OPTIONS] --user USERNAME [MAILBOX...]'
     The contents of specified mailboxes is processed, and the resulting
     mailbox contents is appended to the user's system mailbox. This
     allows to use `guimb' as a mail delivery agent.

   If no mailboxes are specified in the command line, `guimb' reads and
processes the system mailbox of the current user.

Passing Options to Scheme
-------------------------

Sometimes it is necessary to pass some command line options to the
scheme procedure. There are three ways of doing so.

   When using `--source' (`-s') or `--code' (`-c') options, all the
rest of the command line following the option's argument is passed to
Scheme program verbatim. This allows for making guimb scripts
executable by the shell. If your system supports `#!' magic at the
start of scripts, add the following two lines to the beginning of your
script to allow for its immediate execution:

     #! /usr/local/bin/guimb -s
     !#

(replace `/usr/local/bin/' with the actual path to the `guimb').

   Otherwise, if you use `--file' or `--expression' options, the
additional arguments may be passed to the Scheme program `-g'
(`--guile-arg') command line option. For example:

     guimb --guile-arg -opt --guile-arg 24 --file PROGFILE

   In this example, the scheme procedure will see the following command
line:

     PROGFILE -opt 24

   Finally, if there are many arguments to be passed to Scheme, it is
more convenient to enclose them in `-{' and `-}' escapes:

     guimb -{ -opt 24 -} --file PROGFILE

Command Line Option Summary
---------------------------

This is a short summary of the command line options available to
`guimb'.

`-d'
`--debug'
     Start with debugging evaluator and backtraces.

`-e EXPR'
`--expression EXPR'
     Execute given Scheme expression.

`-m PATH'
`--mail-spool=PATH'
     Set path to the mailspool directory

`-f PROGFILE'
`--file PROGFILE'
     Read Scheme program from PROGFILE.

`-g ARG'
`--guile-command ARG'
     Append ARG to the command line passed to Scheme program.

`-{ ... -}'
     Pass all command line options enclosed between `-{' and `-}' to
     Scheme program.

`-m'
`--mailbox MBOX'
     Set default mailbox name.

`-u'
`--user NAME'
     Act as local MDA for user NAME.

`-h'
`--help'
     Display help message.

`-v'
`--version'
     Display program version.

2.10 maidag
===========

The name `maidag' stands for Mail delivery agent. It is a
general-purpose MDA offering a rich set of features. It can operate
both in traditional mode, reading the message from its standard input,
and in LMTP mode. `Maidag' is able to deliver mail to any mailbox
format, supported by GNU Mailutils. These formats, among others,
include `remote+smtp', `remote+prog' and `remote+sendmail' which are
equivalent to forwarding a message over SMTP to a remote node. Thus,
`maidag' supersedes both `mail.local' and `mail.remote' utilities from
GNU Mailutils versions prior to 2.0.

   `Maidag' is also able to process incoming messages using Sieve or
Scheme scripts and, based on results of this processing, to take a
decision on whether to actually deliver and where to deliver them. Due
to its extensive scripting facilities, `maidag' offers much more
flexibility than other popular MDAs, such as `procmail'.

2.10.1 Using `maidag' with Sendmail.
------------------------------------

When used as a MDA with Sendmail, `maidag' must be invoked from the
local mailer definition in the `sendmail.cf' file. It must have the
following flags set: `lswS'. These mean: the mailer is local, quote
characters should be stripped off the address before invoking the
mailer, the user must have a valid account on this machine and the
userid should not be reset before calling the mailer. Additionally, the
flags `fn' may be specified to allow `maidag' to generate the usual
`From ' envelope instead of the one supplied by `sendmail'.

   If you wish to use `maidag' with non-local authentication, such as
SQL or LDAP, you also need to remove the `w' flag, since in that case
the user is not required to have a valid account on the machine that
runs `sendmail'.

   Here is an example of mailer definition in `sendmail.cf'

     Mlocal, P=/usr/local/sbin/maidag,
             F=lsDFMAw5:/|@qSPfhn9,
             S=EnvFromL/HdrFromL, R=EnvToL/HdrToL,
             T=DNS/RFC822/X-Unix,
             A=mail $u

   To define local mailer in `mc' source file, it will suffice to set:

     define(`LOCAL_MAILER_PATH', `/usr/local/sbin/maidag')
     define(`LOCAL_MAILER_ARGS', `mail $u')

2.10.2 Using `maidag' with Exim.
--------------------------------

Using `maidag' with Exim is quite straightforward. The following
example illustrates the definition of the appropriate transport and
director in `exim.conf':

     # transport
     maidag_pipe:
       driver = pipe
       command = /usr/local/sbin/maidag $local_part
       return_path_add
       delivery_date_add
       envelope_to_add

     # director
     maidag:
       driver = localuser
       transport = maidag_pipe

2.10.3 Using `maidag' with MeTA1.
---------------------------------

MeTA1 (`http://meta1.org') communicates with the delivery agent using
LMTP.

   LMTP mode is enabled in `maidag' by the `lmpt yes' statement. The
socket to listen on must be specified using `server' statement (*note
Server Settings::). For the purposes of this section, let's suppose
`maidag' will listen on a UNIX socket `/var/spool/meta1/lmtpsock'.
Then, the following (minimal) `maidag' configuration will do the job:

     # Start in LMTP mode.
     lmtp yes;
     # Run as daemon.
     mode daemon;
     # Switch to this group after startup.
     group meta1c;
     # Configure server:
     server unix:///var/spool/meta1/lmtpsock {
       transcript no;
     };

   To configure MeTA1 to use this socket, add the following statement to
the `smtpc' section in `/etc/meta1/meta1.conf':

       LMTP_socket="lmtpsock";

2.10.4 Mailbox Quotas
---------------------

"Mailbox quota" is a limit on the size of the mailbox. When a mailbox
size reaches this limit, `maidag' stops accepting messages for this
recipient and returns an error condition to the sender. The error code
is accompanied by the following error message:

     USER: mailbox quota exceeded for this recipient

   Furthermore, if accepting the incoming message would make the
mailbox size exceed the quota, such a message will be rejected as well.
In this case, the error message is:

     USER: message would exceed maximum mailbox size for this recipient

   In both cases, the default return code will be `service unavailable'
(corresponding to the SMTP return code `550'), unless the following
statement is present in the `maidag' configuration file:

     exit-quota-tempfail yes;

in which case a temporary error will be returned.

   The mailbox quota can be retrieved from the following sources:

  1. Authentication method.

  2. DBM file.

  3. SQL database.

2.10.4.1 Keeping Quotas in DBM File
...................................

To use DBM quota database, GNU Mailutils must be compiled with one of
the following command line options: `--with-gdbm',
`--with-berkeley-db', or `--with-ndbm'. Examine the output of `maidag
--show-config-options', if not sure.

   The quota database should have the following structure:

Key
     Key represents the user name. Special key `DEFAULT' means default
     quota value, i.e. the one to be used if the user is not explicitly
     listed in the database.

Value
     Mailbox quota for this user. If it is a number, it represents the
     maximum mailbox size in bytes. A number may optionally be followed
     by `kb' or `mb', meaning kilobytes and megabytes, respectively.

     A special value `NONE' means no mailbox size limit for this user.

   Here is an example of a valid quota database

     # Default quota value:
     DEFAULT         5mb

     # Following users have unlimited mailbox size
     root            NONE
     smith           NONE

     # Rest of users
     plog            26214400
     karin           10mB

   To use the DBM quota database, specify its absolute name using
`quota-db' configuration statement, e.g.:

     quota-db /etc/mail/quota.db;

2.10.4.2 Keeping Quotas in SQL Database
.......................................

Configuration statement `quota-query' allows to specify a special query
to retrieve the quota from the database. Currently (as of mailutils
version 2.0) it is assumed that this table can be accessed using the
credentials set in `sql' configuration statement (*note SQL
Statement::).

   For example, suppose you have the following quota table:

     create table mailbox_quota (
       user_name varchar(32) binary not null,
       quota int,
       unique (user_name)
     );

To retrieve user quota the following query can be used:

     SELECT quota FROM mailbox_quota WHERE user_name='${user}'

   There are no special provisions for specifying group quotas, similar
to `DEFAULT' in DBM databases. This is because group quotas can easily
be implemented using SQL language. `Maidag' always uses the first tuple
from the set returned by mailbox quota query. So, you may add a special
entry to the `mailbox_quota' table that would keep the group quota. In
the discussion below we assume that the `user_name' column for this
entry is lexicographically less than any other user name in the table.
Let's suppose the group quota name is `00DEFAULT'. Then the following
query:

     SELECT quota
     FROM mailbox_quota
     WHERE user_name IN ('${user}','00DEFAULT')
     ORDER BY user_name DESC

will return two tuples if the user is found in `mailbox_quota'. Due to
`ORDER' statement, the first tuple will contain the quota for the user,
which will be used by `maidag'. On the other hand, if the requested
user name is not present in the table, the above query will return a
single tuple containing the group quota.

   The following configuration statement instructs `maidag' to use this
query for retrieving the user quota:

     quota-query "SELECT quota "
                 "FROM mailbox_quota "
                 "WHERE user_name IN ('${user}','00DEFAULT') "
                 "ORDER BY user_name DESC";

2.10.5 Maidag Scripting
-----------------------

`Maidag' can use global or per-user "mail filters" to decide whether to
deliver the message, and where to deliver it. As of Mailutils version
2.0, such mail filters may be written in the following languages:

   * Sieve *Note Sieve Language::.

   * Scheme

2.10.5.1 Sieve Maidag Filters
.............................

The file name of the Sieve filter to use is specified using
`sieve-filter' configuration statement. The following meta-symbols can
be used in its argument:

~
%h
     Expands to the recipient home directory.

%u
     Expands to the recipient user name.

   For example, the following configuration statement:

     sieve-filter "~/.maidag.sv"

instructs `maidag' to use file `.maidag.sv' in the recipient home
directory as a Sieve filter.

   Normal message delivery is attempted if execution of the Sieve code
ended with `keep' action (either implicit or explicit).

   Other Sieve actions are executed as described in *note Actions::. For
example, to deliver message to another mailbox, use the `fileinto'
action.

   Any modifications to headers or body of the message performed by the
Sieve code will be visible in the delivered message.

2.10.5.2 Scheme Maidag Filters
..............................

The file name of the Scheme mail filter is specified using
`guile-filter' configuration statement. This statement is processed as
described in *note Sieve Maidag Filters::.

   Only one of `guile-filter' or `sieve-filter' may be used. The
behavior of `maidag' if both statements are used is undefined.

2.10.6 Forwarding
-----------------

"Forward file" is a special file in the user's home directory that
contains the email address of the mailbox where the user wants to
forward his mail. Normally, forward files are processed by MTA.
However, there are some MTA that lack this feature. One of them is
MeTA1.

   `Maidag' provides a forwarding feature that is useful to compensate
the lack of it.

   Name of the forward file is given using `forward-file' configuration
statement. A common usage is:

     forward-file .forward;

   The forward file is always searched in the recipient home directory.

   Before actually using the file, a number of safety checks are
performed on it. If the file fails to pass one of these checks, no
forwarding is performed and the message is delivered as usual. These
checks can be configured using `forward-file-checks' statement.  Its
argument is a list of the following keywords:

groupwritablefile
file_iwgrp
     The file must not be group writable.

worldwritablefile
file_iwoth
     The file must not be world writable.

linkedfileinwritabledir
link
     The file cannot be a symlink in a writable directory.

fileingroupwritabledir
dir_iwgrp
     The file cannot reside in a group writable directory.

fileinworldwritabledir
dir_iwoth
     The file cannot reside in a world writable directory.

all
     All of the above checks.

   The default is `forward-file-checks all'.

   Each of these keywords may be prefixed by `no' to disable this
particular check. For example:

     forward-file-checks (nodir_iwoth, nodir_iwgrp);

2.10.7 Delivering Messages to a URL.
------------------------------------

When invoked with the `--url' command line option, `maidag' treats its
arguments as a list of mailbox URLs and attempts to deliver the message
to each of them.

   For example:

     $ maidag --url maildir:///home/smith/Mail

2.10.8 Remote Mailbox Delivery
------------------------------

`Maidag' can be used to deliver mail to remote mailboxes, such as
`imap' or `remote+smtp'. If the mailbox URL is `remote+smtp' or
`remote+sendmail', the message is actually forwarded over SMTP to the
remote node, so `maidag' acts as a message transfer agent. For example:

     $ maidag --url remote+smtp://10.10.1.100:24

   This command line will send the message to the machine `10.10.1.100'
using port `24' (private mail system).

   The `remote+prog' mailbox may be of special use. Delivering to this
mailbox results in invoking the specified command with the given
arguments and passing the message to its standard input. There are two
ways to specify a `remote+prog' mailbox:

remote+prog://PROGRAM?ARGS
     Here, PROGRAM is the absolute pathname of the program binary, and
     ARGS are its arguments, separated by `&' signs.

|PROGRAM ARGS
     In this notation, ARGS are command line arguments separated by
     white space.

   In both cases, ARGS do not include `argv[0]'.

   The `remote+prog' mailbox may be used, in particular, to implement
mailing lists with MeTA1.

   For example, suppose that the `maidag' configuration contains:

     auth {
       authorization sql:system;
       authentication generic:system;
     }

     sql {
       interface mysql;
       db mail;
       getpwnam "SELECT user as name, mailbox, "
                "'x' as passwd, 500 as uid, 2 as gid, "
                "'/nonexistent' as dir, '/sbin/nologin' as shell "
                "FROM userdb "
                "WHERE user='${user}'";
     }

   Then, the following entries in the `userdb' table implement
<mailman@yourdomain> mailing list:

     mysql> select * from userdb;
     +---------------------+---------------------------------------+
     | user                | mailbox                               |
     +---------------------+---------------------------------------+
     | mailman             | |/usr/bin/mailman post mailman        |
     | mailman-admin       | |/usr/bin/mailman admin mailman       |
     | mailman-bounces     | |/usr/bin/mailman bounces mailman     |
     | mailman-confirm     | |/usr/bin/mailman confirm mailman     |
     | mailman-join        | |/usr/bin/mailman join mailman        |
     | mailman-leave       | |/usr/bin/mailman leave mailman       |
     | mailman-owner       | |/usr/bin/mailman owner mailman       |
     | mailman-request     | |/usr/bin/mailman request mailman     |
     | mailman-subscribe   | |/usr/bin/mailman subscribe mailman   |
     | mailman-unsubscribe | |/usr/bin/mailman unsubscribe mailman |
     +---------------------+---------------------------------------+

2.10.9 Maidag Configuration File Summary
----------------------------------------

The behavior of `maidag' is affected by the following configuration
statements:

Statement              Reference
------------------------------------------------------------------- 
debug                  *Note Debug Statement::.
mailbox                *Note Mailbox Statement::.
locking                *Note Locking Statement::.
pam                    *Note PAM Statement::.
sql                    *Note SQL Statement::.
virtdomain             *Note Virtdomain Statement::.
radius                 *Note Radius Statement::.
ldap                   *Note LDAP Statement::.
auth                   *Note Auth Statement::.
mailer                 *Note Mailer Statement::.
server                 *Note Server Settings::. Used only in LMTP
                       mode.
acl                    *Note ACL Statement::.
tcp-wrappers           *Note Tcp-wrappers Statement::.

 -- Maidag Config: ex-multiple-delivery-success BOOL
     In case of multiple delivery, exit with code 0 if at least one
     delivery has succeeded.

 -- Maidag Config: ex-quota-tempfail BOOL
     Indicate temporary failure if the recipient is over his mail quota.
     By default, permanent failure is returned. *Note Mailbox Quotas::.

 -- Maidag Config: quota-db FILE
     Set the name of DBM quota database file. *Note DBM Quotas::.

 -- Maidag Config: sieve-filter PATTERN
     Set file name or name pattern of the Sieve filter file.  *Note
     Sieve Maidag Filters::.

 -- Maidag Config: message-id-header NAME
     When logging Sieve actions, identify messages by the value of this
     header.

 -- Maidag Config: guile-filter PATTERN
     File name or name pattern for Guile filter file.  *Note Scheme
     Maidag Filters::.

 -- Maidag Config: debug FLAGS
     Set additional debugging flags. Valid flags are:

    g
          Print `guimb' stack traces.

    t
          Enable `sieve' trace (`MU_SIEVE_DEBUG_TRACE').

    i
          Enable `sieve' instructions trace (`MU_SIEVE_DEBUG_INSTR').

    l
          Log executed Sieve actions.

 -- Maidag Config: stderr BOOL
     Log to stderr instead of syslog.

 -- Maidag Config: forward-file FILE
     Process forward file FILE. *Note Forwarding::.

 -- Maidag Config: forward-file-checks LIST
     Configure safety checks for the forward file.  *Note
     forward-file-checks: Forwarding.

 -- Maidag Config: lmtp BOOL
     Run in LMTP mode.

 -- Maidag Config: group LIST
     In LMTP mode, retain supplementary groups from LIST.

 -- Maidag Config: listen URL
     In LMTP mode, listen on URL. Valid URLs are: `tcp://HOST:PORT'
     (note that port is mandatory), `file://SOCKET-FILE-NAME' or
     `socket://SOCKET-FILE-NAME'.

 -- Maidag Config: reuse-address BOOL
     Reuse existing address (LMTP mode). Default is `yes'.

2.11 `mail.local' -- Deliver Mail to the Local UNIX Mailbox
===========================================================

`Mail.local' reads the standard input up to an end-of-file and appends
the received data to the local mailboxes in UNIX mailbox format. This
program is superseded by `maidag' (*note maidag::) and will be
decommissioned in future releases.

2.11.1 Invoking `mail.local'
----------------------------

General usage of `mail.local' program is:

           mail.local [OPTION...] RECIPIENT [RECIPIENT ...]

If recipient part is a FQDN, `mail.local' will attempt to deliver to a
virtual host.

`-f ADDR'
`--from ADDR'
     Specify the sender's name. This option forces `mail.local' to add
     `From ' envelope to the beginning of the message. If it is not
     specified, `mail.local' first looks into the first line from the
     standard input. If it starts with `From ', it is assumed to
     contain a valid envelope. If it does not, `mail.local' creates the
     envelope by using current user name and date.

`-q'
`--quota-db FILE'
     Specify path to DBM mailbox quota database (*note Mailbox
     Quotas::).

`--quota-query'
     Specify SQL query that should be used to obtain user mailbox
     quotas from the SQL database (*note Mailbox Quotas::).

`-s PATTERN'
`--source PATTERN'
     Set name pattern for user-defined mail filters written in Scheme.
     The metacharacters `%u' and `%h' in the pattern are expanded to
     the current recipient user name and home directory correspondingly.

     This option is available only if the package has been configured to
     use Guile extension language.

`-S PATTERN'
`--sieve PATTERN'
     Set name pattern for user-defined mail filters written is Sieve.
     The metacharacters `%u' and `%h' in the pattern are expanded to
     the current recipient user name and home directory correspondingly.

`-t NUMBER'
`--timeout NUMBER'
     Wait NUMBER seconds for acquiring the lockfile. If it doesn't
     become available after that amount of time, return failure. The
     timeout defaults to 5 minutes.

`-x FLAGS'
`--debug FLAGS'
     Enable debugging. The debugging information will be output using
     syslog.  The FLAGS is a string consisting of the following flags:
     Debug flags are:

    `g'
          Start with guile debugging evaluator and backtraces. This is
          convenient for debugging user-defined filters.

    `T'
          Enable libmailutil traces (`MU_DEBUG_TRACE').

    `P'
          Enable network protocol traces (`MU_DEBUG_PROT')

    `t'
          Enable sieve trace (`MU_SIEVE_DEBUG_TRACE')

    `l'
          Enable sieve action logs

     The digits in the range `0' - `9' used in FLAGS set `mail.local'
     debugging level.

`-v'
`--version'
     Display program version and exit.

`--ex-multiple-delivery-success'
     Don't return errors when delivering to multiple recipients.

`--ex-quota-tempfail'
     Return temporary failure if disk or mailbox quota is exceeded. By
     default, 'service unavailable' is returned if the message exceeds
     the mailbox quota.

2.11.2 Mail.local Configuration
-------------------------------

The behavior of mail.local is affected by the following configuration
statements:

Statement              Reference
------------------------------------------------------------------- 
debug                  *Note Debug Statement::.
mailbox                *Note Mailbox Statement::.
locking                *Note Locking Statement::.
pam                    *Note PAM Statement::.
sql                    *Note SQL Statement::.
virtdomain             *Note Virtdomain Statement::.
radius                 *Note Radius Statement::.
ldap                   *Note LDAP Statement::.
auth                   *Note Auth Statement::.
mailer                 *Note Mailer Statement::.

   Additionally, `mail.local' defines the following configuration
statements for its use:

 -- Mail.local Config: ex-multiple-delivery-success BOOL
     In case of multiple delivery, exit with code 0 if at least one
     delivery has succeeded.

 -- Mail.local Config: ex-quota-tempfail BOOL
     Indicate temporary failure if the recipient is over his mail quota.
     By default, permanent failure is returned.

 -- Mail.local Config: quota-db FILE
     Set the name of DBM quota database file.

 -- Mail.local Config: sieve-filter PATTERN
     Set file name or name pattern of the Sieve filter file.

     The following meta-sequences are expanded in PATTERN:

    ~
    %h
          Expands to the recipient home directory.

    %u
          Expands to the recipient user name.

 -- Mail.local Config: message-id-header NAME
     When logging Sieve actions, identify messages by the value of this
     header.

 -- Mail.local Config: guile-filter PATTERN
     File name or name pattern for Guile filter file. See
     `sieve-filter' above, for the description if PATTERN.

 -- Mail.local Config: debug FLAGS
     Set additional debugging flags. Valid flags are:

    g
          Print `guimb' stack traces.

    t
          Enable `sieve' trace (`MU_SIEVE_DEBUG_TRACE').

    i
          Enable `sieve' instructions trace (`MU_SIEVE_DEBUG_INSTR').

    l
          Log executed Sieve actions.

2.12 `mail.remote' -- Pseudo-Sendmail Interface for Mail Delivery
=================================================================

The `mail.remote' utility reads the standard input, which must be
formatted as an RFC-2822 email message, and forwards it to the
specified remote SMTP server. This utility is superseded by `maidag'
and will be decommissioned in future releases. For a description of how
to use `maidag' for remote delivery, *note Remote Mailbox Delivery::.

   This section provides a short overview of the `mail.remote' utility.

     $ mail.remote [OPTION...] RCPT [RCPT...]

   Options are:

`-b ARG'
     Ignored, for compatibility with `sendmail'.

`-d'
`--debug'
     Print envelope commands in SMTP protocol transaction. If specified
     more than once, the data part of the protocol transaction is also
     printed.

`-f ADDR'
`--from=ADDR'
     Override the default from address.

`-i'
`-o ARG'
     Ignored, for for compatibility with `sendmail'.

`-t'
`--read-recipients'
     Read recipient addresses from the message headers.

`--debug-auth'
     Debug authentication functions.

2.13 mimeview
=============

For each file given in its command line, `mimeview' attempts to
autodetect its type and invoke an appropriate file viewer.

   To detect the file type, `mimeview' uses `mime.types' file. This
file is a part of Common UNIX Printing System, *note mime.types:
(mime.types(5))mime.types. By default `mimeview' searches for
`mime.types' in `$prefix/etc/cups/'(1), however its exact location can
be specified at runtime as well (see `--mimetypes' below).

   Once file MIME type is successfully determined, `mimeview' consults
`mailcap' files in order to determine how to display the file. It does
so essentially in the same manner as `metamail' utility, i.e., it scans
all files specified in `METAMAIL' environment variable until it finds
an entry describing the desired file format or until the list of files
is exhausted. If `METAMAIL' variable is not set, `mimeview' uses the
following default path instead:

     $HOME/.mailcap:/usr/local/etc/mailcap:\
      /usr/etc/mailcap:/etc/mailcap:\
      /etc/mail/mailcap:/usr/public/lib/mailcap

   ---------- Footnotes ----------

   (1) The exact location is determined at configuration time by
setting environment variable `DEFAULT_CUPS_CONFDIR'. On most sites
running

     ./configure DEFAULT_CUPS_CONFDIR=/etc/cups

should be recommended.

2.13.1 Mimeview Invocation
--------------------------

The following table summarizes options specific for `mimeview':

`-a[TYPE-LIST]'
`--no-ask[=TYPE-LIST]'
     By default `mimeview' asks for confirmation before running
     interpreter to view a message. If this option is used without
     argument, it disables the default behavior for all message types.
     Otherwise, if argument TYPE-LIST is given, it specifies a
     comma-separated list of MIME types for which no questions should be
     asked. Elements of this list may include shell-style globbing
     patterns, e.g. setting

          --no-ask='text/*,image/jpeg'

     will disable prompting before displaying any textual files, no
     matter what their subtype is, and before displaying files with
     type `image/jpeg'.

     Notice, that when the long form is used, its argument must be
     separated from the option by a single equal sign, as shown in the
     example above. When the short form (`-a') is used, its argument
     must follow the option immediately, without any intervening
     whitespace, e.g. `-a'text/*'').

`-d[FLAGS]'
`--debug[=FLAGS]'
     Enables debugging output. FLAGS is a sequence of characters
     specifying the desired debugging level. Following characters are
     meaningful in FLAGS:

    g
          Enables debugging of `mime.types' parser

    l
          Enables debugging of `mime.types' lexical analyzer (warning:
          produces _very_ copious output)

    1
          Prints basic information about actions to be executed and
          reports about exit status of executed commands.

    2
          Additionally displays each file name along with its MIME type

    3
          Additionally traces the process of looking up the matching
          entry in `mailcap' files.

    digits from 4 to 9
          The same as 3, currently.

     If FLAGS are not given, the default `9' is assumed.

`--metamail[=FILE]'
     Run `metamail' to display files, instead of using the internal
     mechanisms. If FILE is specified, it is taken as `metamail'
     command line.

`-h'
`--no-interactive'
`--print'
     This options tells `mimeview' that it should run in
     non-interactive mode. In this mode prompting is disabled, and the
     normal mailcap `command' field is not executed. Instead `mimeview'
     will execute the command specified in the `print' field. If there
     is nothing in the print field, the mailcap entry is ignored and
     the search continues for a matching mailcap entry that does have a
     `print' field.

     Notice, that unlike in `metamail -h', this option does not force
     `mimeview' to send the output to the printer daemon.

     When used with `--metamail' option, this option passes `-h' flag
     to the invocation of `metamail'.

     By default `mimeview' behaves as if given `--no-interactive'
     option whenever its standard input is not a tty device.

`-n'
`--dry-run'
     Do not do anything, just print what would be done. Implies
     `--debug=1', unless the debugging level is set up explicitly.

`-t FILE'
`--mimetypes FILE'
     Use FILE as `mime.types' file. If FILE is a directory, use
     `FILE/mime.types'

2.13.2 Mimeview Config
----------------------

The following configuration statements affect the behavior of
`mimeview':

Statement              Reference
------------------------------------------------------------------- 
debug                  *Note Debug Statement::.

 -- Mimeview Config: debug NUMBER
     Set `mimeview' debug level. *Note -debug: Mimeview Invocation, for
     a description of debug levels.

 -- Mimeview Config: mimetypes FILE
     Read FILE instead of the default `mime.types'.

 -- Mimeview Config: metamail PROGRAM
     Use PROGRAM to display files.

2.14 POP3 Daemon
================

The `pop3d' daemon implements the Post Office Protocol Version 3 server.

   `pop3d' has two operation modes:

Inetd
     The server is started from `/etc/inetd.conf' file:

          pop3  stream tcp nowait  root  /usr/local/sbin/pop3d pop3d

     This is the default operation mode.

Standalone
     The server runs as daemon, forking a child for each new connection.

   The server operation mode is configured using `mode' statement
(*note mode: Server Settings.).

2.14.1 Login delay
------------------

POP3 clients often login frequently to check for new mail. Each new
connection implies authenticating the user and opening his maildrop and
can be very resource consuming. To reduce server load, it is possible
to impose a minimum delay between any two consecutive logins.  This is
called `LOGIN-DELAY' capability and is described in RFC 2449.

   As of version 2.0, GNU Mailutils `pop3d' allows to set global login
delay, i.e. such enforcement will affect all POP3 users. If a user
attempts to log in before the specified login delay expires, he will
get the following error message:

     -ERR [LOGIN-DELAY] Attempt to log in within the minimum login delay interval

   The message will be issued after a valid password is entered. This
prevents this feature from being used by malicious clients for account
harvesting.

   To enable the login delay capability, specify the minimum delay
using `login-delay' configuration statement, e.g.:

     login-delay 60;

   The `pop3d' utility keeps each user's last login time in a special
DBM file, called "login statistics database", so to be able to use this
feature, Mailutils must be compiled with DBM support.  By default, the
login statistics database is called `/var/run/pop3-login.db'. You can
change its name using `stat-file' configuration statement:

     login-delay 60;
     stat-file /tmp/pop.login;

   Notice, that there is no need to include the `.db' suffix in the
file name.

   The login delay facility will be enabled only if `pop3d' is able to
access the statistics database for both reading and writing. If it is
not, it will report this using `syslog' and start up without login
delay restrictions. A common error message looks like:

     Unable to open statistics db: Operation not permitted

   You can check whether your `pop3d' uses login delays by connecting
to it and issuing the `CAPA' command. If login delays are in use, there
response will contain the string `LOGIN-DELAY N', where N is the actual
login delay value.

2.14.2 Auto-expire
------------------

Automatic expiration of messages allows you to limit the period of time
users are permitted to keep their messages on the server. It is enabled
by `expire' configuration statement:

`expire N;'
     Enable automatic expiration of messages after N days.

   The current implementation works as follows. When a message is
downloaded by `RETR' or `TOP' command, it is marked with
`X-Expire-Timestamp: N' header, where N is current value of UNIX
timestamp. The exact expiration mechanism depends on you. Mailutils
allows you two options:

  1. Expired messages are deleted by `pop3d' upon closing the mailbox.
     You specify this mechanism using `delete-expired' configuration
     statement:

    `delete-expired BOOL;'
          If BOOL is `true', delete expired messages after receiving
          the `QUIT' command.

  2. Expired messages remain in the mailbox after closing it. The system
     administrator is supposed to run a cron job that purges the
     mailboxes.  Such a cron job can be easily implemented using
     `sieve' from GNU Mailutils and the following script:

          require "timestamp";
          # Replace "5" with the desired expiration period
          if timestamp :before "X-Expire-Timestamp" "now - 5 days"
            {
              discard;
            }

     This script will remove expired messages 5 days after the
     retrieval. Replace `5' with the desired expiration period and make
     sure it equals the argument to `expire' configuration keyword.

   The statement `expire 0' means the client is not permitted to leave
mail on the server. It always implies `delete-expired true'.

2.14.3 Bulletins
----------------

The bulletin feature allows you to send important announcements to all
POP3 users without mailing them. It works by creating a "bulletin
source mailbox" and sending the announcements to it.

   After a user successfully authenticates, `pop3d' checks the last
"bulletin number" the user receives. The bulletin number refers to the
number of the bulletin message in the bulletin source mailbox. If the
latter contains more messages, these are appended to the user mailbox.

   The user last bulletin number can be kept in two places. First, it
can be stored in file `.popbull' in his home directory. Secondly, if
Mailutils is compiled with DBM support, the numbers can be kept in a
DBM file, supplied via `bulletin-db' configuration statement. If both
the database and the `.popbull' file are present, the data from the
database take precedence.

   To enable this feature, use the following configuration statements:

`bulletin-source MBOX'
     Set the URL of the bulletin source mailbox.

`bulletin-db FILE'
     Set the name of the database file to keep last bulletin numbers in.
     Be sure not to specify `.db' extension.

   The following example instructs `pop3d' to look for the bulletin
messages in MH folder `/var/spool/bull/mbox' and to keep the database
of last delivered bulletin numbers in `/var/spool/bull/numbers.db':

     bulletin-source mh:/var/spool/bull/mbox;
     bulletin-db /var/spool/bull/numbers;

2.14.4 Pop3d Configuration
--------------------------

The following configuration file statements affect the behavior of
`pop3d'.

Statement              Reference
------------------------------------------------------------------- 
debug                  *Note Debug Statement::.
tls                    *Note TLS Statement::.
mailbox                *Note Mailbox Statement::.
locking                *Note Locking Statement::.
logging                *Note Logging Statement::.
pam                    *Note PAM Statement::.
sql                    *Note SQL Statement::.
virtdomain             *Note Virtdomain Statement::.
radius                 *Note Radius Statement::.
ldap                   *Note LDAP Statement::.
auth                   *Note Auth Statement::.
server                 *Note Server Settings::.
acl                    *Note ACL Statement::.
tcp-wrappers           *Note Tcp-wrappers Statement::.

 -- Pop3d Conf: undelete BOOL
     On startup, clear deletion marks from all the messages.

 -- Pop3d Conf: expire N
     Automatically expire read messages after N days. *Note
     Auto-expire::, for a detailed description.

 -- Pop3d Conf: delete-expired BOOL
     Delete expired messages upon closing the mailbox. *Note
     Auto-expire::, for a detailed description.

 -- Pop3d Conf: tls-required BOOL
     Always require `STLS' command before entering authentication phase.

 -- Pop3d Conf: login-delay DURATION
     Set the minimal allowed delay between two successive logins.
     *Note Login delay::, for more information.

 -- Pop3d Conf: stat-file FILE
     Set the name of login statistics file for the `login-delay'
     facility. *Note Login delay::, for more information.

 -- Pop3d Conf: bulletin-source FILE
     Get bulletins from the specified mailbox. *Note Bulletins::, for a
     detailed description.

 -- Pop3d Conf: bulletin-db FILE
     Set bulletin database file name. *Note Bulletins::, for a detailed
     description.

2.14.5 Command line options
---------------------------

The following table summarizes all `pop3d' command line options.

`-d[NUMBER]'
`--daemon[=NUMBER]'
     Run in standalone mode. An optional NUMBER specifies the maximum
     number of child processes allowed to run simultaneously. When it
     is omitted, it defaults to 10 processes.  _Please note_, that
     there should be no whitespace between the `-d' and its parameter.

`-i'
`--inetd'
     Run in inetd mode.

`-h'
`--help'
     Display short help message and exit.

`--foreground'
     Remain in foreground.

`--tls[=BOOL]'
     Enable TLS. If optional argument is supplied and is `false', then
     disable it.

`--debug-auth'
     Enable debugging of authentication functions.

2.15 IMAP4 Daemon
=================

GNU `imap4d' is a daemon implementing IMAP4 rev1 protocol for accessing
and handling electronic mail messages on a server. It can be run either
as a standalone program or from `inetd.conf' file.

2.15.1 Namespace
----------------

GNU `imap4d' supports a notion of "namespaces" defined in RFC 2342. A
namespace is a set of directories upon which the user has certain
permissions. It should be understood that these permissions apply only
if the underlying filesystem allows them.

   The three namespaces supported by `imap4d' are:

Personal Namespace
     A namespace that is within the personal scope of the authenticated
     user on a particular connection. The user has all permissions on
     this namespace.

Other Users' Namespace
     A namespace that consists of mailboxes from the "Personal
     Namespaces" of other users. The user can read and list mailboxes
     from this namespace. However, he is not allowed to use `%' and `*'
     wildcards with `LIST' command, that is he can access a mailbox
     only if he knows exactly its location.

Shared Namespace
     A namespace that consists of mailboxes that are intended to be
     shared amongst users and do not exist within a user's Personal
     Namespace.  The user has all permissions on this namespace.

By default, `imap4d' starts with the following namespaces:

Personal Namespace
     The home directory of the user, if exists.

Other Users' Namespace
     Empty

Shared Namespace
     Empty

   _Note_, that this means that by default, a user won't be able to see
or otherwise access mailboxes residing in the directories other than
his own home.

   To change these defaults, use `shared-namespace' and
`other-namespace' configuration statements:

`shared-namespace LIST'
     Set shared namespace.

`other-namespace LIST'
     Set other users' namespace.

   For both statements, the argument is a list of directories that
belong to this namespace, e.g.:

     shared-namespace (/var/spool/mail,/var/mail);

   If during the session the user creates a mailbox within either of
these namespaces, the mode of the mailbox is determined by the
following configuration statements:

`shared-mailbox-mode MODE'
     Set file mode for mailboxes created in shared namespace.

`other-mailbox-mode MODE'
     Set file mode for mailboxes created in other users' namespace.

   In both cases, the argument, MODE is a list of symbolic mode
settings, similar to that used by `chmod'. It is a list of
comma-separated mode change commands. Each command begins with a letter
`g', which means set mode bits for file group, or `o', which means set
mode bits for other users (note, that there is no `u' specifier, since
user ownership of his mailbox cannot be changed). This letter is
followed by an `=' (or `+'), and a list of modes to be set. This list
can contain only two letters: `r' to set read permission, and `w' to
set write permission.

   For example, the following statement sets read and write permissions
for the group:

     shared-namespace-mode g=rw;

2.15.2 Configuration of `imap4d'.
---------------------------------

The behavior of `imap4d' is altered by the following configuration
statements:

Statement              Reference
------------------------------------------------------------------- 
debug                  *Note Debug Statement::.
tls                    *Note TLS Statement::.
mailbox                *Note Mailbox Statement::.
locking                *Note Locking Statement::.
logging                *Note Logging Statement::.
pam                    *Note PAM Statement::.
sql                    *Note SQL Statement::.
virtdomain             *Note Virtdomain Statement::.
radius                 *Note Radius Statement::.
ldap                   *Note LDAP Statement::.
auth                   *Note Auth Statement::.
server                 *Note Server Settings::.
acl                    *Note ACL Statement::.
tcp-wrappers           *Note Tcp-wrappers Statement::.

 -- Imap4d Conf: shared-namespace LIST
     Set shared namespace. LIST is a list of strings. *Note
     Namespace::, for a detailed description.

 -- Imap4d Conf: other-namespace LIST
     Set other users' namespace. LIST is a list of strings. *Note
     Namespace::, for a detailed description.

 -- Imap4d Conf: shared-mailbox-mode STR
     Set file mode for mailboxes created within shared namespace.
     *Note Namespace::, for a detailed description.

 -- Imap4d Conf: other-mailbox-mode STR
     Set file mode for mailboxes created within other users' namespace.
     *Note Namespace::, for a detailed description.

 -- Imap4d Conf: login-disabled BOOL
     Disable `LOGIN' command, if BOOL is `true'.

 -- Imap4d Conf: create-home-dir BOOL
     Create nonexistent user home directories. See also home-dir-mode,
     below.

 -- Imap4d Conf: home-dir-mode MODE
     Set file mode for created user home directories. Mode is specified
     in octal.

     The default value for MODE is `700' (`drwx------' in `ls' terms).

 -- Imap4d Conf: tls-required BOOL
     Require successful `STARTTLS' command before entering
     authentication phase.

 -- Imap4d Conf: preauth MODE
     Configure PREAUTH mode. Valid arguments are:

    prog:///PROGRAM-NAME
          `Imap4d' invokes an external program to authenticate the
          connection. The command line is obtained from the supplied
          string, by expanding the following meta-variables:

         `${client_address}'
               Remote IP address in dotted-quad notation;

         `${client_port}'
               Remote port number;

         `${server_address}'
               Local IP address;

         `${server_port}'
               Local port number.

          If the connection is authenticated, the program should print
          the user name, followed by a newline character, on its
          standard output and exit with code `0'.

          Otherwise, it should exit with a non-zero exit code.

    ident[://:PORT]
          The remote machine is asked about the requester identity
          using the identification protocol (RFC 1413). Both plaintext
          and DES encrypted replies are understood. Optional PORT
          specifies the port to use, if it differs from the default
          `113'. It can be either a decimal port number or a symbolic
          name of a service, listed in `/etc/services'.

    stdio
          PREAUTH mode is enabled automatically if imap4d is started
          from command line in interactive mode (`-i' command line
          option). The current login name is used as the user name.

 -- Imap4d Conf: preauth-only BOOL
     If BOOL is `true', use only preauth mode. If unable to setup it,
     disconnect immediately.

 -- Imap4d Conf: ident-keyfile FILE
     Set DES keyfile for decoding encrypted ident responses. Used with
     `ident://' preauth mode.

 -- Imap4d Conf: ident-encrypt-only BOOL
     Use only encrypted IDENT responses.

 -- Imap4d Conf: id-fields LIST
     Set list of fields to return in response to ID command.

     Valid field names are:

    name
          Package name (`GNU Mailutils').

    version
          Package version (`2.0').

    vendor
          Vendor name (`GNU').

    support-url
          The string `http://www.gnu.org/software/mailutils'

    address
          The string `51 Franklin Street, Fifth Floor, Boston, MA
          02110-1301 USA'.

    os
          OS name.

    os-version
          OS version number.

    command
          Name of the `imap4d' binary.

    arguments
          Invocation command line.

    environment
          List of environment variables with their values.


2.15.3 Starting `imap4d'
------------------------

`imap4d' may run either in "standalone" or in "inetd" operation modes.
When run in "standalone" mode, the server disconnects from the terminal
and runs as a daemon, forking a child for each new connection.

   The "inetd" mode allows to start the server from `/etc/inetd.conf'
file. This is the default operation mode.

     imap4  stream tcp nowait  root  /usr/local/sbin/imap4d imap4d

Command Line Options
--------------------

`-d[NUMBER]'
`--daemon[=NUMBER]'
     Run in standalone mode. An optional NUMBER specifies the maximum
     number of child processes the daemon is allowed to fork. When it
     is omitted, it defaults to 20 processes.  _Please note_, that
     there should be no whitespace between the `-d' and its parameter.

`-h'
`--help'
     Display short help message and exit.

`-i'
`--inetd'
     Run in inetd mode.

`--foreground'
     Run in foreground.

`--preauth'
     Start in preauth mode

`--tls[=BOOL]'
     Enable TLS support

`--debug-auth'
     Debug authentication functions.

`-v'
`--version'
     Display program version and exit.

2.16 Comsat Daemon
==================

Comsatd is the server which receives reports of incoming mail and
notifies users, wishing to get this service. It can be started either
from `inetd.conf' or as a standalone daemon.

2.16.1 Starting `comsatd'
-------------------------

`Comsatd' uses following option groups: , , .

`-C FILE'
`--convert-config=FILE'
     Convert the configuration file FILE to the new format. FILE must
     be a `comsatd' configuration file in Mailutils v. 1.x format. The
     converted file is printed on the standard output. For example, the
     following command can be used to convert old `comsatd'
     configuration file to new format:

          $ comsatd --convert-config=/etc/comsatd.conf > /etc/mailutils.d/comsatd

`-d'
`--daemon'
     Run as a standalone daemon.

`-i'
`--inetd'
     The server is started from `/etc/inetd.conf' file:

          comsat dgram  udp wait  root  /usr/sbin/comsatd \
          comsatd -c /etc/comsat.conf

     This is the default operation mode.

`-t'
`--test'
     Test mode. In this mode, `comsatd' takes two arguments: URL of a
     mailbox and QID of the message from that mailbox, e.g.:

          $ comsatd --test /var/mail/root 34589


2.16.2 Configuring `comsatd'
----------------------------

Following configuration statements affect the behavior of `comsatd':

Statement              Reference
------------------------------------------------------------------- 
debug                  *Note Debug Statement::.
logging                *Note Logging Statement::.
mailbox                *Note Mailbox Statement::.
locking                *Note Locking Statement::.
acl                    *Note ACL Statement::.

2.16.2.1 General Settings
.........................

These statements control the general behavior of the comsat daemon:

 -- Comsatd Conf: max-lines NUMBER
     Set maximum number of message body lines to be output.

 -- Comsatd Conf: allow-biffrc BOOL
     Enable or disable processing of user's `.biffrc' file. By default,
     it is enabled.

2.16.2.2 Security Settings
..........................

These statements control the way `comsatd' fights possible flooding
attacks.

 -- Comsatd Conf: max-requests NUMBER
     Set maximum number of incoming requests per
     `request-control-interval'.

 -- Comsatd Conf: request-control-interval DURATION
     Set the request control interval.

 -- Comsatd Conf: overflow-delay-time DURATION
     Set initial amount of time to sleep, after the first overflow
     occurs.

 -- Comsatd Conf: overflow-control-interval DURATION
     Set overflow control interval. If two consecutive overflows happen
     within that interval, the overflow-delay-time is doubled.

2.16.3 A per-user Configuration File
------------------------------------

By default, when a notification arrives, `comsatd' prints subject, from
headers and the first five lines from the new message to the user's
tty. The user is allowed to change this behavior by using his own
configuration file. This file should be located in the user's home
directory and should be named `.biffrc'. It must be owned by the user
and have its permissions bits set to 0600. (_Please note_, that the use
of per-user configuration files may be disabled, by specifying
`allow-biffrc no' in the main configuration file, see *note Configuring
comsatd::).

   The `.biffrc' file consists of a series of statements. Each
statement occupies one line and defines an action to be taken upon
arrival of a new mail. Very long lines may be split using `\' as the
last character on the line. As usual, comments may be introduced with
`#' character.

   The actions specified in `.biffrc' file are executed in turn.  The
following actions are defined:

beep
     Produce an audible signal.

echo [-n] STRING [STRING...]
     Output the arguments to the user's terminal device. If several
     arguments are given they will be output separated by single
     spaces. The newline character will be printed at the end of the
     output, unless the `-n' option is used.

exec PROG ARGLIST
     Execute program PROG with arguments from ARGLIST. PROG must be
     specified with absolute pathname. It may not be a setuid or setgid
     program.

   In the description above, STRING denotes any sequence of characters.
This sequence must be enclosed in a pair of double-quotes, if it
contains whitespace characters. The `\' character inside a string
starts a C escape sequence. Following meta-characters may be used in
strings:

$u
     Expands to username

$h
     Expands to hostname

$H{name}
     Expands to value of message header `name'.

$B(C,L)
     Expands to message body. C and L give maximum number of characters
     and lines in the expansion. When omitted, they default to 400, 5.

Example I
.........

Dump to the user's terminal the contents of `From' and `Subject'
headers followed by at most 5 lines of message body.
     echo "Mail to \a$u@$h\a\n---\n\
     From: $H{from}\n\
     Subject: $H{Subject}\n\
     ---\n\
     $B(,5)\
     ---\n"

The above example can also be written as:
     echo Mail to \a$u@$h\a
     echo ---
     echo From: $H{From}
     echo Subject: $H{Subject}
     echo ---
     echo $B(,5)
     echo ---

Example II
..........

Produce a bell, then pop up the xmessage window on display :0.0 with
the text formatted in the same manner as in the previous example.

     beep
     exec /usr/X11R6/bin/xmessage \
     -display :0.0 -timeout 10 "Mail to $u@$h \n---\n\
     From: $H{from}\n\
     Subject: $H{Subject}\n\
     ---\n\
     $B(,5)\
     ---\n"

2.17 MH -- The MH Message Handling System
=========================================

The primary aim of this implementation is to provide an interface
between Mailutils and Emacs using mh-e module.

   To use Mailutils MH with Emacs, add the following line to your
site-start.el or .emacs file:

   (load "mailutils-mh")

   For the information about the current state of Mailutils MH
implementation please refer to file `mh/TODO' in the Mailutils
distribution directory.

   [FIXME]

2.17.1 Major differences between Mailutils MH and other MH implementations
--------------------------------------------------------------------------

  1. All programs use usual GNU long options. The support for MH
     single-dash options is provided for backward compatibility;

  2. UUCP addresses are not supported;

  3. Mailutils supports a set of new format specifications (*note
     Format String Diffs::);

  4. Mailutils provides a set of new profile variables (*note Profile
     Variable Diffs::);

  5. Several programs behave differently (*note Program Diffs::);


2.17.1.1 New and Differing MH Format Specifications
...................................................

 -- MH Format: string decode (string STR)
     Decodes the input string STR as per RFC 2047. Useful in printing
     `From:', `To:' and `Subject:' headers.

     Notice that, unlike the similar NMH function, `decode' checks the
     value of the global profile variable `Charset' (*note Charset
     variable::) to determine the charset to output the result in. If
     this variable is not set, `decode' returns its argument without
     any change. If this variable is set to `auto', `decode' tries to
     determine the charset name from the setting of `LC_ALL' environment
     variable. Otherwise, the value of `Charset' is taken to be the
     name of the character set.

 -- MH Format: string package ()
     Returns package name (string `mailutils').

 -- MH Format: string package_string ()
     Returns full package string (e.g. `GNU Mailutils 2.1')

 -- MH Format: string version ()
     Returns mailutils version.

 -- MH Format: string unre (string STR)
     The function removes any leading whitespace and eventual `Re:'
     prefix from its argument. Useful for creating subjects in reply
     messages:

            %<{subject}Subject: Re: %(unre{subject})\\n%>

 -- MH Format: void reply_regex (string R)
     Sets the regular expression used to recognize reply messages. The
     argument R should be a POSIX extended regular expression.
     Matching is case insensitive.

     For example, the following invocation

            %(reply_regex ^\(re|aw|ang|odp\)\(\\[[0-9]+\\]\)?:[[:blank:]])

     corresponds to English `Re', Polish `Odp', Norwegian `Aw' or
     German `Ang', optionally followed by a number in brackets, followed
     by colon and any amount of whitespace. Notice proper quoting of the
     regex metacharacters.

     See also `Reply-Regex' (*note Reply-Regex variable::) and
     `isreply' (*note isreply MH function::) below.


 -- MH Format: boolean isreply ([string STR])
     If STR is not given, the value of `Subject:' header is taken.

     The function returns true if its argument matches the "reply
     subject" regular expression. This expression is set via the global
     profile variable `Reply-Regex' (*note Reply-Regex variable::) or
     via the format function `reply_regex'.

     This function is useful for creating `Subject:' headers in reply
     messages. For example, consider the following construction:

          %<{subject}%(lit)%<(isreply)%?\
          (profile reply-prefix)%(concat)%|%(concat Re:)%>\
          %(concat{subject})%(printhdr Subject: )\n%>

     If the `Subject:' header already contained reply prefix, this
     construct leaves it unchanged. Otherwise it prepends to it the
     value of `Reply-Prefix' profile variable, or, if it is unset, the
     string `Re:'.

     This expression is used in default `replcomps' and
     `replgroupcomps' files.

 -- MH Format: boolean rcpt (`to' | `cc' | `me' | `all')
     This function returns true if the given element is present in the
     recipient mask (as modified by `--cc' or `--nocc' options) and
     false otherwise. It is used in default formats for `repl' and
     `comp', e.g.:

          %(lit)%<(rcpt to)%(formataddr{to})%>

     Notice that this means that usual `replcomps' file will be ignoring
     `--cc' and `--nocc' options, unless it has been modified as shown
     above.

 -- MH Format: string concat ()
     Appends whitespace + arg to string register.

 -- MH Format: string printhdr (string STR)
     Prints the value of string register, prefixed by STR.  The output
     is formatted as a RFC 822 header, i.e.  it is split at whitespace
     characters nearest to the width boundary and each subsequent
     segment is prefixed with horizontal tabulation.

 -- MH Format: string in_reply_to ()
     Generates the value for `In-reply-to:' header according to RFC
     2822.

 -- MH Format: string references ()
     Generates the value for `References:' header according to RFC 2822.

2.17.1.2 New MH Profile Variables
.................................

 -- Variable: MH Variable string Charset
     Controls the character set in which the components decoded via the
     `decode' (*note decode function::) format function should be
     output.

 -- Variable: MH Variable string Reply-Regex
     Keeps the regular expression used to recognize reply messages. The
     argument should be a POSIX extended regular expression. Matching
     is case insensitive.

     For more information, please see *Note reply_regex function::.

2.17.1.3 Differences in MH Program Behavior
...........................................

`burst'
     The utility is able to burst both RFC 934 digest messages and MIME
     multipart messages. It provides two additional command line
     options: `--recurse' and `--length'.

     The `--recurse' option instructs the utility to recursively expand
     the digest.

     The `--length' option can be used to set the minimal encapsulation
     boundary length for RFC 934 digests. Default length is 1, i.e.
     encountering one dash immediately following a newline triggers
     digest decoding. It is OK for messages that follow RFC 934
     specification. However, many user agents do not precisely follow
     it, in particular, they often do not escape lines starting with a
     dash by `- ' sequence. `Mailman' is one of such agents. To cope
     with such digests you can set encapsulation boundary length to a
     higher value. For example, `bounce --length=8' has been found to be
     sufficient for most Mailman-generated digests.

`comp'
     Understands `--build' option.

`fmtdump'
     This command is not provided. Use `fmtcheck' instead.

`mhl'
     If the argument to `ignores' contains more than one component name
     it must be enclosed in double-quotes. Dangling equal sign is an
     error, to set a string variable to the empty value assign it an
     empty string, e.g.: `overflowtext=""' (see the supplied
     `mhl.format' file).

     Interactive prompting is not yet implemented.

`mhn'
        * New option New option `--compose' forces `mhn' editing mode.
          This is also the default mode. This differs from the standard
          `mhn', which switches to the editing mode only if no other
          options were given and the input file name coincides with the
          value of `mhdraft' environment variable.

        * Show mode (`--show') If an appropriate
          mhn-show-type[/subtype] was not found, GNU `mhn' prints the
          decoded message content using `moreproc' variable. Standard
          `mhn' in this case used to print `don't know how to display
          content' diagnostic.

          The default behaviour is to pipe the content to the standard
          input of the mhn-show-type[/subtype] command. This is altered
          to using a temporary file if the command contains `%f' or
          `%F' escapes.

        * Store mode (`--store') If the `Content-Disposition' header
          contains `filename=', and `mhn' is invoked with `--auto'
          switch, it transforms the file name into the absolute
          notation and uses it only if it lies below the current
          mhn-storage directory. Standard `mhn' only requires that the
          file name do not begin with `/'.

          Before saving a message part, GNU `mhn' checks if the file
          already exists. If so, it asks whether the user wishes to
          rewrite it. This behaviour is disabled when `--quiet' option
          was given.

`mhparam'
     The `--all' mode does not display commented out entries.

`repl'
     Understands `--use' option. Disposition shell provides `use'
     command.

`rmm'
       1. Different behaviour if one of the messages in the list does
          not exist:

          Mailutils `rmm' does not delete any messages. Standard `rmm'
          in this case deletes all messages preceeding the non-existent
          one.

       2. The `rmmproc' profile component is not used.

`pick'
     The non-standard command line syntax `--FIELD STRING'), where
     FIELD is any string, is deprecated. It is recognized only if
     `pick' is called from within another program, so that existing
     application continue to work. Please use the following syntax
     instead:

          pick --component FIELD --pattern STRING

     New command line option `--cflags' allows to control the type of
     regular expressions used. The option must occur right before
     `--pattern' or `--component' option (or one of its aliases, like
     `--cc', `--from', etc.)

     The argument to this option is a string of type specifications:

     B             Use basic regular expressions
     E             Use extended regular expressions
     I             Ignore case
     C             Case sensitive

     Default is `EI'.

     The flags remain in effect until the next occurrence of `--cflags'
     option.

     Sample usage:

          pick --cflag BC --subject '*a string'

     The date comparison options (`--before' and `--after' accept date
     specifications in a wide variety of formats, e.g.:

          pick --after 20030301
          pick --after 2003-03-01
          pick --after 01-mar-2003
          pick --after 2003-mar-01
          pick --before '1 year ago'
          etc...

`refile'
       1. Linking messages between folders goes against the logic of
          Mailutils, so `refile' never makes links even if called with
          `--link' option. The latter is actually a synonym for
          `--copy', which preserves the original message.

       2. The `--preserve' option is not implemented. It is retained
          for backward compatibility only.

       3. Message specs and folder names may be interspersed.

`sortm'
     New option `--numfield' specifies numeric comparison for the given
     field.

     Any number of `--datefield', `--textfield' and `--numfield'
     options may be given, thus allowing to build sort criteria of
     arbitrary complexity.

     The order of `--.*field' options sets the ordering priority. This
     differs from the behaviour of the standard `sortm', which always
     orders datefield-major, textfield-minor.

     Apart from sorting the mailfolder the following actions may be
     specified:

    `--list'
          List the ordered messages using a format string given by
          `--form' or `--format' option.

    `--dry-run'
          Do not actually sort messages, rather print what would have
          been done. This is useful for debugging purposes.


2.18 `mailutils-config' -- Get the Information about the Mailutils Build
========================================================================

This program is designed for developers wishing to link their programs
against libmailbox. It allows to examine the particulars of the current
build of Mailutils and to get the command line parameters necessary for
compiling and linking an application with Mailutils libraries.

Getting Compiler Flags
----------------------

When invoked with the option `--compile', or its short form `-c',
`mailutils-config' prints the flags that must be given to the compiler
for compiling the program using Mailutils functions. An example usage:

     cc -omyprog.o `mailutils-config --compile` myprog.c

Getting Loader Flags
--------------------

The `--link', or its short form `-l' prints to the standard output the
loader flags necessary to link a program against Mailutils libraries.

   When invoked without arguments, it produces the flags necessary to
link against the basic library of Mailutils: `libmailbox'.  Arguments
may be given that alter this behavior. These are:

`auth'
     Print flags to link against `libmuauth', the library adding new
     authentication methods to `libmailbox'.

`guile'
     Print flags to link against `libmu_scm', the Guile interface
     library.

`mbox'
     Link against `mbox' format library.

`mh'
     Link against `mh' format library.

`maildir'
     Link against `maildir' format library.

`mailer'
     Link against `mailer' library.

`imap'
     Link against `imap' format library.

`pop'
     Link against `pop' format library.

`all'
     Link against all Mailutils format libraries.

   The order of arguments does not matter.

   For example, if you wrote a program `myprog.c' that uses standard
UNIX mailbox format, MH format and the Guile interface, then you would
link it with the following command:

     cc -omyprog myprog.o `mailutils-config --link mbox mh guile`

Obtaining General Build Information
-----------------------------------

The `--info', or `-i' retrieves the options (flags) used when building
Mailutils. It may be used with or without arguments.

   When used without arguments, it prints the list of all build flags,
e.g.:

     $ mailutils-config --info
     VERSION=2.0
     SYSCONFDIR=/usr/local/etc
     MAILSPOOLDIR=/var/mail/
     SCHEME=mbox
     LOG_FACILITY=mail
     USE_LIBPAM
     HAVE_LIBLTDL
     WITH_GDBM
     WITH_GNUTLS
     WITH_GSASL
     WITH_GUILE
     WITH_PTHREAD
     WITH_READLINE
     HAVE_MYSQL
     ENABLE_VIRTUAL_DOMAINS
     ENABLE_IMAP
     ENABLE_POP
     ENABLE_MH
     ENABLE_MAILDIR
     ENABLE_SMTP
     ENABLE_SENDMAIL

   When this option is used in conjunction with the `--verbose' option,
a short description is printed to the right of each keyword, e.g.:

     $ mailutils-config --info --verbose
     VERSION=1.9.93             - Version of this package
     SYSCONFDIR=/usr/local/etc  - System configuration directory
     MAILSPOOLDIR=/var/mail/    - Default mail spool directory
     SCHEME=mbox                - Default mailbox type
     LOG_FACILITY=mail          - Default syslog facility
     USE_LIBPAM                 - PAM support
     HAVE_LIBLTDL               - a portable `dlopen' wrapper library
     WITH_GDBM                  - GNU DBM
     ...

   This option also accepts any number of arguments. When these are
given, each argument is treated as a name of a build flag.
`Mailutils-config' checks if such a flag was defined and prints its
full name if so. It exits with zero code if all the flags given on the
command line are defined. Otherwise, it exits with code of 1.

   The comparison of the flag names is case-insensitive. The arguments
given need not include the leading prefix (i.e. the characters up to
and including the first underscore character).

   Given the previous example, the invocation

     $ mailutils --info readline use_libpam pop

will produce the following output:

     WITH_READLINE
     USE_LIBPAM
     ENABLE_POP

and will exit with a zero status.

   The following command:

     $ mailutils --info readline gssapi pop

will exit with status 1, and will print:

     WITH_READLINE
     ENABLE_POP

since `WITH_GSSAPI' flag is not defined.

   The flags and their meanings are:

USE_LIBPAM
     The Mailutils uses PAM libraries.

HAVE_LIBLTDL
     The GNU wrapper library `libltdl' is present and is used by
     Mailutils. *Note Using libltdl: (libtool)Using libltdl, for more
     information on `libltdl' library.

WITH_BDB2
     Support for Berkeley DB is compiled in (the package was configured
     with `--with-db2' option).

WITH_NDBM
     Support for NDBM is compiled in (the package was configured with
     `--with-ndbm' option).

WITH_OLD_DBM
     Support for old style DBM is compiled in (the package was
     configured with `--with-dbm' option).

WITH_GDBM
     Support for GNU DBM is compiled in (the package was configured with
     `--with-gdbm' option). *Note Introduction: (gdbm)Top, for more
     information about this library.

WITH_GNUTLS
     Support for GnuTLS (a Transport Layer Security Library) is
     compiled in (the package was configured with `--with-gnutls'
     option).

WITH_GSASL
     Support for GNU SASL is compiled in (the package was configured
     with `--with-gsasl' option). *Note Introduction: (gsasl)Top, for
     more information about this library.

WITH_GSSAPI
     Support for GSSAPI is compiled in (the package was configured with
     `--with-gssapi' option).

WITH_GUILE
     Support for Guile extension language is built (the package was
     configured with `--with-guile' option).  *Note Overview:
     (guile)Top, for more information about Guile.

WITH_PTHREAD
     The POSIX thread support is compiled in.

WITH_READLINE
     The readline support is enabled (the package was configured with
     `--with-readline' option).  *Note Top: (readline)Top, for more
     information.

HAVE_MYSQL
     Authentication via MySQL is supported (the package was configured
     with `--enable-mysql' option).

ENABLE_VIRTUAL_DOMAINS
     Support for mail virtual domains is enabled (the package was
     configured with `--enable-virtual-domains' option).

ENABLE_IMAP
     Support for IMAP4 protocol is enabled.

ENABLE_POP
     Support for POP3 protocol is enabled.

ENABLE_MH
     Support for mailboxes in MH format is enabled.

ENABLE_MAILDIR
     Support for mailboxes in MAILDIR format is enabled.

ENABLE_SMTP
     Support for SMTP mailer is enabled.

ENABLE_SENDMAIL
     Support for Sendmail mailer is enabled.

3 Mailutils Libraries
*********************

3.1 Framework
=============

Wherever the mail is and whatever format it is stored in, it is operated
upon using the same set of functions. To unified the C API, GNU
Mailutils offers a heteroclite set of objects that work in aggregation
to do operations on emails.  Each object does a specific task and
delegates non-related tasks to others.  The object comes alive by
specifying a _URL_ parameter when created, it will indicate the storage
format or protocol (POP3, IMAP4, MH, MAILDIR, etc ..).

                               mu_folder_t                  mu_url_t
       -/var/mail-    +- .. ->+-------------------+   +-->+------------+
      (  alain *-)-+  |       |   mu_url_t      *-|---+   |   port     |
       ----------  |  |       |-------------------|       |   hostname |
      (  jakob *-)-+--+       |   mu_auth_t     *-|---+   |   file     |
       ----------  |          |-------------------|   |   |   ...      |
      (  jeff  *-)-+          |   mu_stream_t     |   |   +------------+
       ----------  |          |-------------------|   |
      (  shaleh*-)-+          |   .....           |   |    mu_auth_t
       ----------             |-------------------|   +-->+-------------+
                          +---|-* mu_mailbox_t[]  |       | mu_ticket_t |
       mu_mailbox_t       |   +-------------------+       +-------------+
      +-------------------+
      |   mu_locker_t  *--|-------------+
      |-------------------|             |
      |   mu_url_t        |             |          mu_locker_t
      |-------------------|             +-------->+---------+
      |   mu_stream_t     |                       | lock    |
      |-------------------|                       | unlock  |
      |  mu_message_t[] *-|-------+               +---------+
      +-------------------+       |                     mu_envelope_t
                                  |          +-------->+-----------+
       mu_message_t               |          |         | date      |
      +-------------------+<------+          |         | from      |
      |   mu_envelope_t *-|------------------+         | to        |
      |-------------------|              mu_header_t   +-----------+
      |   mu_header_t   *-|------------>+-----------------+
      |-------------------|             |   mu_stream_t   |
      |   mu_body_t     *-|----+        +-----------------+
      +-------------------+    |    mu_body_t
                               +-->+-----------------+
                                   |   mu_stream_t   |
                                   +-----------------+

   As an example, here is a simplified version of `from' command. It
lists the `From' and `Subject' headers of every mail in a mailbox.


     #ifdef HAVE_CONFIG_H
     # include <config.h>
     #endif
     #include <stdio.h>
     #include <stdlib.h>
     #include <string.h>
     #include <unistd.h>

     #include <mailutils/mailutils.h>

     int
     main (int argc, const char **argv)
     {
       char *from;
       char *subject;
       mu_mailbox_t mbox;
       size_t msgno, total = 0;
       int status;

       /* Register the formats. */
       mu_register_all_mbox_formats ();

       status = mu_mailbox_create_default (&mbox, argv[1]);
       if (status != 0)
         {
           mu_error ("mu_mailbox_create: %s", mu_strerror (status));
           exit (EXIT_FAILURE);
         }

       status = mu_mailbox_open (mbox, MU_STREAM_READ);
       if (status != 0)
         {
           mu_error ("mu_mailbox_open: %s", mu_strerror (status));
           exit (EXIT_FAILURE);
         }

       mu_mailbox_messages_count (mbox, &total);

       for (msgno = 1; msgno <= total; msgno++)
         {
           mu_message_t msg;
           mu_header_t hdr;

           if ((status = mu_mailbox_get_message (mbox, msgno, &msg)) != 0
               || (status = mu_message_get_header (msg, &hdr)) != 0)
             {
               mu_error ("Error message: %s", mu_strerror (status));
               exit (EXIT_FAILURE);
             }

           if (mu_header_aget_value (hdr, MU_HEADER_FROM, &from))
             from = strdup ("(NO FROM)");

           if (mu_header_aget_value (hdr, MU_HEADER_SUBJECT, &subject))
             subject = strdup ("(NO SUBJECT)");

           printf ("%s\t%s\n", from, subject);
           free (from);
           free (subject);
         }

       status = mu_mailbox_close (mbox);
       if (status != 0)
         {
           mu_error ("mu_mailbox_close: %s", mu_strerror (status));
           exit (EXIT_FAILURE);
         }

       mu_mailbox_destroy (&mbox);
       return 0;
     }

   Here is a sample output produced by this program:

     % ./sfrom pop://alain@localhost
     Passwd: xxxx
     Jim Meyering <meyering@foo.org>      fetish(shellutils) beta
     Franc,ois Pinard <pinard@bar.org> recode new alpha
     ...

3.1.1 Folder
------------

     `/* Prefix _mu_folder__ is reserved. */'
     `#include <mailutils/folder.h>'

                                  mu_folder_t                mu_url_t
       -/var/mail-    +---//--->/-------------------\   +-->/-----------\
      (  alain *-)-+  |         |  mu_url_t       *-|---+   |  port     |
       ----------  |  |         |-------------------+       |  hostname |
      (  jakob *-)-+--+         |  mu_observer_t  *-|       |  file     |
       ----------  |            |-------------------+       |  ...      |
      (  jeff  *-)-+            |  mu_stream_t      |       \-----------/
       ----------  |            |-------------------|
      (  sean  *-)-+            |  mu_auth_t        |
       ----------               |-------------------|
                                |  mu_mailbox_t(1)  |
                                |-------------------|
                                |  mu_mailbox_t(2)  |
                                |  ......           |
                                |  mu_mailbox_t(n)  |
                                \-----------------/

   Data structures:

     struct mu_list_response
     {
       int type;
       int separator;
       char *name;
     };

 -- Function: int mu_folder_create (mu_folder_t *, const char *URL)

 -- Function: void mu_folder_destroy (mu_folder_t *)

 -- Function: int mu_folder_open (mu_folder_t, int FLAG)

 -- Function: int mu_folder_close (mu_folder_t)

 -- Function: int mu_folder_delete (mu_folder_t, const char *MAILBOX)

 -- Function: int mu_folder_rename (mu_folder_t, const char *, const
          char *MAILBOX)

 -- Function: int mu_folder_subscribe (mu_folder_t, const char *MAILBOX)

 -- Function: int mu_folder_unsubscribe (mu_folder_t, const char
          *MAILBOX)

 -- Function: int mu_folder_list (mu_folder_t, const char *REF, const
          char *WCARD, size_t SIZE, mu_list_t *LIST)

 -- Function: int mu_folder_lsub (mu_folder_t, const char *REF, const
          char *WCARD, mu_list_t *LIST)

 -- Function: int mu_folder_get_stream (mu_folder_t, mu_stream_t *)

 -- Function: int mu_folder_set_stream (mu_folder_t, mu_stream_t)

 -- Function: int mu_folder_get_observable (mu_folder_t,
          mu_observable_t *)

 -- Function: int mu_folder_has_debug (mu_folder_t)

 -- Function: int mu_folder_get_debug (mu_folder_t, mu_debug_t *)

 -- Function: int mu_folder_set_debug (mu_folder_t, mu_debug_t)

 -- Function: int mu_folder_get_authority (mu_folder_t, mu_authority_t
          *)

 -- Function: int mu_folder_set_authority (mu_folder_t, mu_authority_t)

 -- Function: int mu_folder_get_url (mu_folder_t, mu_url_t *)

 -- Function: int mu_folder_set_url (mu_folder_t, mu_url_t)

3.1.2 Mailbox
-------------

     `/* Prefix _mu_mailbox__ is reserved. */'
     `#include <mailutils/mailbox.h>'

 -- Data Type: mu_mailbox_t
     The `mu_mailbox_t' object is used to hold information and it is an
     opaque data structure to the user. Functions are provided to
     retrieve information from the data structure.

                                  mu_mailbox_t               mu_url_t
       -/var/mail-    +---//--->/------------------\   +-->/-----------\
      (  alain   )    |         |  mu_url_t      *-|---+   |  port     |
       ----------     |         |------------------+       |  hostname |
      (  jakob *-)----+         |  mu_observer_t *-|       |  file     |
       ----------               |------------------+       |  ...      |
      (  jeff    )              |  mu_stream_t     |       \-----------/
       ----------               |------------------|
      (  sean    )              |  mu_locker_t     |
       ----------               |------------------|
                                |  mu_message_t(1) |
                                |------------------|
                                |  mu_message_t(2) |
                                |  ......          |
                                |  mu_message_t(n) |
                                \------------------/

 -- Function: int mu_mailbox_create (mu_mailbox_t *MBOX, const char
          *NAME)
     The function `mu_mailbox_create' allocates and initializes MBOX.
     The concrete mailbox type instantiate is based on the scheme of
     the url NAME.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERR_OUT_PTR_NULL'
          The pointer MBOX supplied is `NULL'.

    `MU_ERR_NO_HANDLER'
          The url NAME supplied is invalid or not supported.

    `EINVAL'

    `ENOMEM'
          Not enough memory to allocate resources.

 -- Function: int mu_mailbox_create_default (mu_mailbox_t *MBOX, const
          char *NAME)
     Create a mailbox with `mu_mailbox_create()' based on the
     environment variable `MAIL' or the string formed by
     __PATH_MAILDIR_/USER" or `LOGNAME' if USER is null,

 -- Function: void mu_mailbox_destroy (mu_mailbox_t *MBOX)
     Destroys and releases resources held by MBOX.

 -- Function: int mu_mailbox_open (mu_mailbox_t MBOX, int FLAG)
     A connection is open, if no stream was provided, a stream is
     created based on the MBOX type. The FLAG can be OR'ed.  See
     `stream_create()' for FLAG's description.

     The return value is `0' on success and a code number on error
     conditions:
    `EAGAIN'
    `EINPROGRESS'
          Operation in progress.

    `EBUSY'
          Resource busy.

    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL' or flag is invalid.

    `ENOMEM'
          Not enough memory.

 -- Function: int mu_mailbox_close (mu_mailbox_t MBOX)
     The stream attach to MBOX is closed.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL'.

 -- Function: int mu_mailbox_flush (mu_mailbox_t MBOX, int EXPUNGE)

 -- Function: int mu_mailbox_get_folder (mu_mailbox_t MBOX, folder_t
          *FOLDER)
     Get the FOLDER.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL'.

 -- Function: int mu_mailbox_set_folder (mu_mailbox_t MBOX, mu_folder_t
          FOLDER)

 -- Function: int mu_mailbox_uidvalidity (mu_mailbox_t MBOX, unsigned
          long *NUMBER);
     Give the uid validity of MBOX.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL'.

 -- Function: int mu_mailbox_uidnext (mu_mailbox_t MBOX, size_t
          *NUMBER);
     Give the next predicted uid for MBOX.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL'.

 -- Function: int mu_mailbox_get_message (mu_mailbox_t MBOX, size_t
          MSGNO, mu_message_t *MESSAGE)
     Retrieve message number MSGNO, MESSAGE is allocated and
     initialized.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL' or MSGNO is invalid.

    `ENOMEM'
          Not enough memory.

 -- Function: int mu_mailbox_append_message (mu_mailbox_t MBOX,
          mu_message_t MESSAGE)
     The MESSAGE is appended to the mailbox MBOX.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL' or MESSAGE is invalid.

 -- Function: int mu_mailbox_messages_count (mu_mailbox_t MBOX, size_t
          *NUMBER);
     Give the number of messages in MBOX.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL'.

 -- Function: int mu_mailbox_messages_recent (mu_mailbox_t MBOX, size_t
          *NUMBER);
     Give the number of recent messages in MBOX.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL'.

 -- Function: int mu_mailbox_message_unseen (mu_mailbox_t MBOX, size_t
          *NUMBER);
     Give the number of first unseen message in MBOX.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL'.

 -- Function: int mu_mailbox_expunge (mu_mailbox_t MBOX)
     All messages marked for deletion are removed.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL'.

 -- Function: int mu_mailbox_save_attributes (mu_mailbox_t MBOX)

 -- Function: int mu_mailbox_get_size (mu_mailbox_t MBOX, mu_off_t
          *SIZE)
     Gives the MBOX size.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL'.

 -- Function: int mu_mailbox_is_updated (mu_mailbox_t MBOX)

 -- Function: int mu_mailbox_scan (mu_mailbox_t MBOX, size_t MSGNO,
          size_t *COUNT);
     Scan the mailbox for new messages starting at message MSGNO.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL'.

    `ENOMEM'
          Not enough memory.

 -- Function: int mu_mailbox_get_stream (mu_mailbox_t MBOX, mu_stream_t
          *STREAM)
     The mailbox stream is put in STREAM.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is invalid or STREAM is `NULL'.

 -- Function: int mu_mailbox_set_stream (mu_mailbox_t MBOX, mu_stream_t
          STREAM)
     Set the STREAM connection to use for the mailbox.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX or STREAM is `NULL'.

 -- Function: int mu_mailbox_get_locker (mu_mailbox_t MBOX, mu_locker_t
          *LOCKER)
     Get the MU_LOCKER_T object.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL'.

 -- Function: int mu_mailbox_set_locker (mu_mailbox_t MBOX, mu_locker_t
          LOCKER)
     Set the type of locking done by the MBOX.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL'.

 -- Function: int mu_mailbox_get_property (mu_mailbox_t MBOX,
          mu_property_t *PROPERTY)
     Get the property object.  The return value is `0' on success and a
     code number on error conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL'.

    `ENOMEM'

 -- Function: int mu_mailbox_get_url (mu_mailbox_t MBOX, mu_url_t *URL)
     Gives the constructed URL.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL'.

 -- Function: int mu_mailbox_has_debug (mu_mailbox_t MBOX)

 -- Function: int mu_mailbox_get_debug (mu_mailbox_t MBOX, mu_debug_t
          *DEBUG)
     Get a debug object.  The return value is `0' on success and a code
     number on error conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL'.

    `ENOMEM'

 -- Function: int mu_mailbox_set_debug (mu_mailbox_t MBOX, mu_debug_t
          DEBUG)

 -- Function: int mu_mailbox_get_observable (mu_mailbox_t mbox MBOX,
          mu_observable_t *OBSERVABLE)
     Get the observable object.

     The return value is `0' on success and a code number on error
     conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MBOX is `NULL'.

    `ENOMEM'
          Not enough memory.

 -- Function: int mu_mailbox_lock (mu_mailbox_t MBOX)

 -- Function: int mu_mailbox_unlock (mu_mailbox_t MBOX)

3.1.3 Mailer
------------

     `/* Prefix _mu_mailer__ is reserved. */'
     `#include <mailutils/mailer.h>'

 -- Function: int mu_mailer_create (mu_mailer_t *, const char *URL)

 -- Function: void mu_mailer_destroy (mu_mailer_t *)

 -- Function: int mu_mailer_open (mu_mailer_t, int FLAGS)

 -- Function: int mu_mailer_close (mu_mailer_t)

 -- Function: int mu_mailer_send_message (mu_mailer_t MAILER,
          mu_message_t MSG, mu_address_t FROM, mu_address_t TO);
     If FROM is not `NULL', it must contain a single fully qualified
     RFC2822 email address which will be used as the envelope from
     address. This is the address to which delivery status notifications
     are sent, so it never matters what it is set to until it *really*
     matters. This is equivalent to Sendmail's `-f' flag.

     The default for FROM is provided by the specific mailer.

     If to is not `NULL', then the message will be sent to the list of
     addresses that it specifies.

     The default for TO is to use the contents of the standard "To:",
     "Cc:", and "Bcc:" fields, this is equivalent to Sendmail's `-t'
     flag.

 -- Function: int mu_mailer_get_property (mu_mailer_t, mu_property_t *)

 -- Function: int mu_mailer_get_stream (mu_mailer_t, mu_stream_t *)

 -- Function: int mu_mailer_set_stream (mu_mailer_t, mu_stream_t)

 -- Function: int mu_mailer_get_debug (mu_mailer_t, mu_debug_t *)

 -- Function: int mu_mailer_set_debug (mu_mailer_t, mu_debug_t)

 -- Function: int mu_mailer_get_observable (mu_mailer_t, observable_t *)

 -- Function: int mu_mailer_get_url (mu_mailer_t, url_t *)

 -- Function: int mu_mailer_check_from (mu_address_t FROM)

 -- Function: int mu_mailer_check_to (mu_address_t TO)


Some Usage Notes
----------------

Some possible use cases the API must support are:

   * original submission

       0. fill in header addresses

       1. `mu_mailer_send_message(mailer, msg, NULL, NULL)'

             - from will be filled in if missing,

             - Bcc's will be deleted before delivery to a non-bcc
               address,

             - message-id and date will be added, if missing,

             - a `To:' or `Apparently-To:' header will be added if non
               is present (for RFC compliance)


   * MTA-style `.forward' (and Sieve-style redirect)

       1. get the envelope from of the message to be forwarded

       2. `mu_mailer_send_message(mailer, msg, from, to)'

   * MUA-style bounce

       1. add `Resent-[To,From,...]'

       2. `mu_mailer_send_message(mailer, msg, NULL, to)'

   * DSN "bounce"

       1. compose DSN

       2. `mu_mailer_deliver(mailer, msg, address_t("<>"), to)'

          Don't want mail loops, so the null but valid SMTP address of
          `<>'    is the envelope From.

The Sendmail Mailer
-------------------

`/sbin/sendmail' isn't always Sendmail... Sometimes it's a
Sendmail-compatible wrapper, so assume `/sbin/sendmail' understands
only a recipient list, `-f' and `-oi', these seem to be pretty basic.
Cross fingers.

   Pipe to "/sbin/sendmail -oi [-f FROM] [TO...]", supplying `-f' if
there was a from, and supplying the recipient list from the to (if
there is no recipient list, assume it will read the message contents
for the recipients).

   *Caution:* since the `stdout' and `stderr' of Sendmail is closed, we
have no way of ever giving feedback on failure. Also, what should the
return code be from `mu_mailer_send_message()' when Sendmail returns
`1'? `1' maps to `EPERM', which is less than descriptive!

The SMTP Mailer
---------------

This mailer does *not* canonicalize the message. This must be done
before sending the message, or it may be assumed that the MTA will do
so.

   It does blind out the Bcc: header before sending, though.

   *Caution:* Mutt always puts the recipient addresses on the command
line, even Bcc: ones, do we strip the Bcc: before forwarding with SMTP?

Non-RFC822 Addresses
--------------------

An address that has no domain is not and RFC822 email address. What do
I do with them? Should the user of the API be responsible for
determining what is mean by email to "John" means? Or should the be
able to configure Sendmail to decide globally what this means.  If so,
we can pass the address to Sendmail, but we have to decide for SMTP!
So, right now these addresses are rejected.  This could be changed.

3.1.4 Message
-------------

     `/* Prefix _mu_message__ is reserved. */'
     `#include <mailutils/message.h>'

   The `mu_message_t' object is a convenient way to manipulate
messages. It encapsulates the `envelope_t', the `header_t' and the
`body_t'.

         mailbox_t
         ----------                   mu_message_t
        (message[1])        +------>+--------------------+
         ----------         |       |  mu_envelope_t     |
        (message[2])        |       |--------------------|
         ----------         |       |  mu_header_t       |
        (message[3])--------+       |--------------------|
         ----------                 |  mu_body_t         |
        (message[n])                |--------------------|
         ----------                 |  mu_attribute_t    |
                                    |--------------------|
                                    |  mu_stream_t       |
                                    +--------------------+

 -- Function: void mu_message_create (mu_message_t *MSG, void *OWNER)

 -- Function: void mu_message_destroy (mu_message_t *MSG, void *OWNER)
     The resources allocate for MSG are freed.

 -- Function: int mu_message_create_copy (mu_message_t *TO,
          mu_message_t *FROM)

 -- Function: void* mu_message_get_owner (mu_message_t MSG)

 -- Function: int mu_message_is_modified (mu_message_t MSG)

 -- Function: int mu_message_clear_modified (mu_message_t MSG)

 -- Function: int mu_message_get_mailbox (mu_message_t MSG,
          mu_mailbox_t *MBOX)

 -- Function: int mu_message_set_mailbox (mu_message_t MSG,
          mu_mailbox_t MBOX, void *OWNER)

 -- Function: int mu_message_ref (mu_message_t MSG)

 -- Function: int mu_message_get_envelope (mu_message_t MSG,
          mu_envelope_t *ENVELOPE)

 -- Function: int mu_message_set_envelope (mu_message_t MSG,
          mu_envelope_t ENVELOPE, void *OWNER)

 -- Function: int mu_message_get_header (mu_message_t MSG, mu_header_t
          *HEADER)
     Retrieve MSG header.

 -- Function: int mu_message_set_header (mu_message_t MSG, mu_header_t
          HEADER, void *OWNER)

 -- Function: int mu_message_get_body (mu_message_t MSG, mu_body_t
          *BODY)

 -- Function: int mu_message_set_body (mu_message_t MSG, mu_body_t
          BODY, void *OWNER)

 -- Function: int mu_message_get_stream (mu_message_t MSG, mu_stream_t
          *STREAM)

 -- Function: int mu_message_set_stream (mu_message_t MSG, mu_stream_t
          STREAM, void *OWNER)

 -- Function: int mu_message_get_attribute (mu_message_t MSG,
          mu_attribute_t *ATTRIBUTE)

 -- Function: int mu_message_set_attribute (mu_message_t MSG,
          mu_attribute_t ATTRIBUTE, void *OWNER)

 -- Function: int mu_message_get_observable (mu_message_t MSG,
          mu_observable_t *OBSERVABLE)

 -- Function: int mu_message_is_multipart (mu_message_t MSG, int *MULTI)
     Set *MULTI to non-zero value if MSG is multi-part.

 -- Function: int mu_message_set_is_multipart (mu_message_t MSG, int
          (*_IS_MULTIPART) (mu_message_t, int *), void *);

 -- Function: int mu_message_size (mu_message_t MSG, size_t *SIZE)

 -- Function: int mu_message_set_size (mu_message_t MSG, int (*_SIZE)
          (mu_message_t, size_t *), void *OWNER)

 -- Function: int mu_message_lines (mu_message_t MSG, size_t *SIZE)

 -- Function: int mu_message_set_lines (mu_message_t MSG, int (*_LINES)
          (mu_message_t, size_t *), void *OWNER)

 -- Function: int mu_message_get_num_parts (mu_message_t MSG, size_t
          *NPARTS)

 -- Function: int mu_message_set_get_num_parts (mu_message_t MSG, int
          (*_GET_NUM_PARTS) (mu_message_t, size_t *), void *OWNER)

 -- Function: int mu_message_get_part (mu_message_t MSG, size_t PART,
          mu_message_t *MSG)

 -- Function: int mu_message_set_get_part (mu_message_t MSG, int
          (*_GET_PART) (mu_message_t, size_t, mu_message_t *), void
          *OWNER)

 -- Function: int mu_message_get_uidl (mu_message_t MSG, char *BUFFER,
          size_t BUFLEN, size_t *WRITEN)

 -- Function: int mu_message_set_uidl (mu_message_t MSG, int
          (*_GET_UIDL) (mu_message_t, char *, size_t, size_t *), void
          *OWNER)

 -- Function: int mu_message_get_uid (mu_message_t MSG, size_t *UID)

 -- Function: int mu_message_set_uid (mu_message_t MSG, int (*_GET_UID)
          (mu_message_t, size_t *), void *OWNER)

 -- Function: int mu_message_create_attachment (const char
          *CONTENT_TYPE, const char *ENCODING, const char *FILENAME,
          mu_message_t *NEWMSG)

 -- Function: int mu_message_save_attachment (mu_message_t MSG, const
          char *FILENAME, void **DATA)

 -- Function: int mu_message_encapsulate (mu_message_t MSG,
          mu_message_t *NEWMSG, void **DATA)

 -- Function: int mu_message_unencapsulate (mu_message_t MSG,
          mu_message_t *NEWMSG, void **DATA);

 -- Function: int mu_message_get_attachment_name (mu_message_t MSG,
          char *NAME, size_t BUFSIZE, size_t *SIZE);

 -- Function: int mu_message_aget_attachment_name (mu_message_t MSG,
          char **NAME);

 -- Function: int mu_message_save_to_mailbox (mu_message_t MSG,
          mu_ticket_t TICKET, mu_debug_t DEBUG, const char *TONAME);

3.1.5 Envelope
--------------

     `/* Prefix _mu_envelope__ is reserved. */'
     `#include <mailutils/envelope.h>'

 -- Function: int mu_envelope_create (mu_envelope_t *, void *)
     Primarily for internal use.

 -- Function: void mu_envelope_destroy (mu_envelope_t *, void *)
     Primarily for internal use.

 -- Function: void* mu_envelope_get_owner (mu_envelope_t)

 -- Function: int mu_envelope_sender (mu_envelope_t, char *, size_t,
          size_t *)
     Get the address that this message was reportedly received from.
     This would be the "mail from" argument if the message was delivered
     or received via SMTP, for example.

 -- Function: int mu_envelope_set_sender (mu_envelope_t, int (*_SENDER)
          (mu_envelope_t, char *, size_t, size_t *), void *)
     Primarily for internal use. The implementation of `mu_envelope_t'
     depends on the mailbox type, this allows the function which
     actually gets the sender to be set by the creator of an
     `mu_envelope_t'.

 -- Function: int mu_envelope_date (mu_envelope_t, char *, size_t,
          size_t *)
     Get the date that the message was delivered to the mailbox, in
     something close to ANSI `ctime()' format: Mon Jul 05 13:08:27 1999.

 -- Function: int mu_envelope_set_date (mu_envelope_t, int (*_DATE)
          (mu_envelope_t, char *, size_t, size_t *), void *)
     Primarily for internal use. The implementation of `mu_envelope_t'
     depends on the mailbox type, this allows the function which
     actually gets the date to be set by the creator of an
     `mu_envelope_t'.

3.1.6 Headers
-------------

     `/* Prefix _mu_header__ is reserved. */'
     `#include <mailutils/header.h>'

   So far we plan support for RFC822 and plan for RFC1522. With RFC1522
non-ASCII characters will be encoded.

 -- Function: int mu_header_create (mu_header_t *HDR, const char
          *BLURB, size_t LEN, void *OWNER)
     Initialize a HDR to a supported type. If BLURB is not `NULL', it
     is parsed.

 -- Function: void mu_header_destroy (mu_header_t *HDR, void *OWNER)
     The resources allocated for HDR are freed.

 -- Function: void* mu_header_get_owner (mu_header_t *HDR)

 -- Function: int mu_header_is_modified (mu_header_t HDR)

 -- Function: int mu_header_clear_modified (mu_header_t HDR)

 -- Function: int mu_header_set_value (mu_header_t HDR, const char *FN,
          const char *FV, int N)
     Some basic macros are already provided for RFC822.

    `MU_HEADER_UNIX_FROM'
          From

    `MU_HEADER_RETURN_PATH'
          Return-Path

    `MU_HEADER_RECEIVED'
          Received

    `MU_HEADER_DATE'
          Date

    `MU_HEADER_FROM'
          From

    `MU_HEADER_SENDER'
          Sender

    `MU_HEADER_RESENT_FROM'
          Resent-From

    `MU_HEADER_SUBJECT'
          Subject

    `MU_HEADER_SENDER'
          Sender

    `MU_HEADER_RESENT_SENDER'
          Resent-SENDER

    `MU_HEADER_TO'
          To

    `MU_HEADER_RESENT_TO'
          Resent-To

    `MU_HEADER_CC'
          Cc

    `MU_HEADER_RESENT_CC'
          Resent-Cc

    `MU_HEADER_BCC'
          Bcc

    `MU_HEADER_RESENT_BCC'
          Resent-Bcc

    `MU_HEADER_REPLY_TO'
          Reply-To

    `MU_HEADER_RESENT_REPLY_TO'
          Resent-Reply-To

    `MU_HEADER_MESSAGE_ID'
          Message-ID

    `MU_HEADER_RESENT_MESSAGE_ID'
          Resent-Message-ID

    `MU_HEADER_IN_REPLY_TO'
          In-Reply-To

    `MU_HEADER_REFERENCE'
          Reference

    `MU_HEADER_REFERENCES'
          References

    `MU_HEADER_ENCRYPTED'
          Encrypted

    `MU_HEADER_PRECEDENCE'
          Precedence

    `MU_HEADER_STATUS'
          Status

    `MU_HEADER_CONTENT_LENGTH'
          Content-Length

    `MU_HEADER_CONTENT_LANGUAGE'
          Content-Language

    `MU_HEADER_CONTENT_TRANSFER_ENCODING'
          Content-transfer-encoding

    `MU_HEADER_CONTENT_ID'
          Content-ID

    `MU_HEADER_CONTENT_TYPE'
          Content-Type

    `MU_HEADER_CONTENT_DESCRIPTION'
          Content-Description

    `MU_HEADER_CONTENT_DISPOSITION'
          Content-Disposition

    `MU_HEADER_CONTENT_MD5'
          Content-MD5

    `MU_HEADER_MIME_VERSION'
          MIME-Version

    `MU_HEADER_X_UIDL'
          X-UIDL

    `MU_HEADER_X_UID'
          X-UID

    `MU_HEADER_X_IMAPBASE'
          X-IMAPbase

    `MU_HEADER_ENV_SENDER'
          X-Envelope-Sender

    `MU_HEADER_ENV_DATE'
          X-Envelope-Date

    `MU_HEADER_FCC'
          Fcc

    `MU_HEADER_DELIVERY_DATE'
          Delivery-date

    `MU_HEADER_ENVELOPE_TO'
          Envelope-to

 -- Function: int mu_header_get_value (mu_header_t HDR, const char *FN,
          char *FV, size_t LEN, size_t *N)
     Value of field-name FN is returned in buffer FV of size LEN.  The
     number of bytes written is put in N.

 -- Function: int mu_header_aget_value (mu_header_t HDR, const char
          *FN, char **FV)
     The value is allocated.

 -- Function: int mu_header_get_address (mu_header_t HDR, const char
          *BUF, address_t *ADDR)

 -- Function: int mu_header_get_stream (mu_header_t HDR, stream_t
          *STREAM)

 -- Function: int mu_header_set_stream (mu_header_t HDR, stream_t
          STREAM, void *)

 -- Function: int mu_header_get_field_count (mu_header_t HDR, size_t
          *COUNT)

 -- Function: int mu_header_get_field_value (mu_header_t HDR, size_t
          INDEX, char *, size_t, size_t *)

 -- Function: int mu_header_get_field_name (mu_header_t HDR, size_t
          INDEX, char *, size_t, size_t *)

 -- Function: int mu_header_aget_field_value (mu_header_t HDR, size_t
          INDEX, char **)

 -- Function: int mu_header_aget_field_name (mu_header_t HDR, size_t
          INDEX, char **)

 -- Function: int mu_header_get_value_unfold (mu_header_t HDR, const
          char *NAME, char *BUFFER, size_t BUFLEN, size_t *N)

 -- Function: int mu_header_aget_value_unfold (mu_header_t HDR, const
          char *NAME, char **VALUE)

 -- Function: int mu_header_get_field_value_unfold (mu_header_t HDR,
          size_t NUM, char *BUF, size_t BUFLEN, size_t *NWRITTEN)

 -- Function: int mu_header_aget_field_value_unfold (mu_header_t HDR,
          size_t NUM, char **VALUE);

 -- Function: int mu_header_size (mu_header_t HDR, size_t *);

 -- Function: int mu_header_lines (mu_header_t HDR, size_t *);

 -- Function: int mu_header_set_set_value (mu_header_t HDR, int
          (*_SET_VALUE) (mu_header_t, const char *, const char *, int),
          void *);

 -- Function: int mu_header_set_get_value (mu_header_t HDR, int
          (*_GET_VALUE) (mu_header_t, const char *, char *, size_t,
          size_t *), void *);

 -- Function: int mu_header_set_get_fvalue (mu_header_t HDR, int
          (*_GET_VALUE) (mu_header_t, const char *, char *, size_t,
          size_t *), void *);

 -- Function: int mu_header_set_size (mu_header_t HDR, int (*_SIZE)
          (mu_header_t, size_t *), void *);

 -- Function: int mu_header_set_lines (mu_header_t HDR, int (*_LINES)
          (mu_header_t, size_t *), void *);

 -- Function: int mu_header_set_fill (mu_header_t HDR, int (*_FILL)
          (mu_header_t, char *, size_t, mu_off_t, size_t *), void
          *OWNER);

3.1.7 Body
----------

     `/* Prefix _mu_body__ is reserved. */'
     `#include <mailutils/body.h>'

 -- Function: int mu_body_create (mu_body_t *BODY, void *OWNER)
     Initialize an object BODY.

 -- Function: void mu_body_destroy (mu_body_t *BODY)
     The resources allocated are release.

 -- Function: void* mu_body_get_owner (mu_body_t BODY)

 -- Function: int mu_body_is_modified (mu_body_t BODY)

 -- Function: int mu_body_clear_modified (mu_body_t BODY)

 -- Function: int mu_body_get_stream (mu_body_t BODY, stream_t *STREAM)

 -- Function: int mu_body_set_stream (mu_body_t BODY, stream_t STREAM,
          void *OWNER)

 -- Function: int mu_body_get_filename (mu_body_t BODY, char *BUFFER,
          size_t BUFLEN, size_t *WRITEN)

 -- Function: int mu_body_size (mu_body_t BODY, size_t *SIZE)

 -- Function: int mu_body_set_size (mu_body_t BODY, int (*_SIZE)
          (mu_body_t, size_t *), void *OWNER)

 -- Function: int mu_body_lines (mu_body_t BODY, size_t *LINES)

 -- Function: int mu_body_set_lines (mu_body_t BODY, int (*_LINES)
          (mu_body_t, size_t *), void *OWNER)

3.1.8 Attribute
---------------

     `/* Prefix _mu_attribute__ is reserved. */'
     `#include <mailutils/attribute.h>'

 -- Function: int mu_attribute_create (mu_attribute_t *ATTR, void *)

 -- Function: void mu_attribute_destroy (mu_attribute_t *ATTR, void *)

 -- Function: void* mu_attribute_get_owner (mu_attribute_t ATTR)

 -- Function: int mu_attribute_is_modified (mu_attribute_t ATTR)

 -- Function: int mu_attribute_clear_modified (mu_attribute_t ATTR)

 -- Function: int mu_attribute_set_modified (mu_attribute_t ATTR)

 -- Function: int mu_attribute_is_userflag (mu_attribute_t ATTR)

 -- Function: int mu_attribute_is_seen (mu_attribute_t ATTR)

 -- Function: int mu_attribute_is_answered (mu_attribute_t ATTR)

 -- Function: int mu_attribute_is_flagged (mu_attribute_t ATTR)

 -- Function: int mu_attribute_is_deleted (mu_attribute_t ATTR)

 -- Function: int mu_attribute_is_draft (mu_attribute_t ATTR)

 -- Function: int mu_attribute_is_recent (mu_attribute_t ATTR)

 -- Function: int mu_attribute_is_read (mu_attribute_t ATTR)

 -- Function: int mu_attribute_set_userflag (mu_attribute_t ATTR, int)

 -- Function: int mu_attribute_set_seen (mu_attribute_t ATTR)

 -- Function: int mu_attribute_set_answered (mu_attribute_t ATTR)

 -- Function: int mu_attribute_set_flagged (mu_attribute_t ATTR)

 -- Function: int mu_attribute_set_deleted (mu_attribute_t ATTR)

 -- Function: int mu_attribute_set_draft (mu_attribute_t ATTR)

 -- Function: int mu_attribute_set_recent (mu_attribute_t ATTR)

 -- Function: int mu_attribute_set_read (mu_attribute_t ATTR)

 -- Function: int mu_attribute_unset_userflag (mu_attribute_t ATTR, int)

 -- Function: int mu_attribute_unset_seen (mu_attribute_t ATTR)

 -- Function: int mu_attribute_unset_answered (mu_attribute_t ATTR)

 -- Function: int mu_attribute_unset_flagged (mu_attribute_t ATTR)

 -- Function: int mu_attribute_unset_deleted (mu_attribute_t ATTR)

 -- Function: int mu_attribute_unset_draft (mu_attribute_t ATTR)

 -- Function: int mu_attribute_unset_recent (mu_attribute_t ATTR)

 -- Function: int mu_attribute_unset_read (mu_attribute_t ATTR)

 -- Function: int mu_attribute_get_flags (mu_attribute_t ATTR, int *)

 -- Function: int mu_attribute_set_flags (mu_attribute_t ATTR, int)

 -- Function: int mu_attribute_unset_flags (mu_attribute_t ATTR, int)

 -- Function: int mu_attribute_set_set_flags (mu_attribute_t ATTR, int
          (*_SET_FLAGS) (mu_attribute_t, int), void *)

 -- Function: int mu_attribute_set_unset_flags (mu_attribute_t ATTR,
          int (*_UNSET_FLAGS) (mu_attribute_t, int), void *)

 -- Function: int mu_attribute_set_get_flags (mu_attribute_t ATTR, int
          (*_GET_FLAGS) (mu_attribute_t, int *), void *)

 -- Function: int mu_attribute_is_equal (mu_attribute_t ATTR1,
          mu_attribute_t ATTR2)

 -- Function: int mu_attribute_copy (mu_attribute_t DST, mu_attribute_t
          SRC)

 -- Function: int mu_attribute_to_string (mu_attribute_t ATTR, char
          *BUF, size_t LEN, size_t *WRITEN)

 -- Function: int string_to_flags (const char *BUF, int *)

3.1.9 Stream
------------

     `#include <mailutils/stream.h>'

   These generic flags are interpreted as appropriate to the specific
streams.

`MU_STREAM_READ'
     The stream is open read only.

`MU_STREAM_WRITE'
     The stream is open write only.

`MU_STREAM_RDWR'
     The stream is open read and write.

`MU_STREAM_APPEND'
     The stream is open in append mode for writing.

`MU_STREAM_CREAT'
     The stream open will create the underlying resource (such as a
     file) if it doesn't exist already.

`MU_STREAM_NONBLOCK'
     The stream is set non blocking.

`MU_STREAM_NO_CHECK'
     Stream is destroyed without checking for the owner.

`MU_STREAM_SEEKABLE'

`MU_STREAM_NO_CLOSE'
     Stream doesn't close it's underlying resource when it is closed or
     destroyed.

`MU_STREAM_ALLOW_LINKS'

 -- Function: int mu_file_stream_create (mu_stream_t *STREAM, const
          char *FILENAME, int FLAGS)

 -- Function: int mu_tcp_stream_create (mu_stream_t *STREAM, const char
          *HOST, int PORT, int FLAGS)

 -- Function: int mu_mapfile_stream_create (mu_stream_t *STREAM, const
          char *FILENAME, int FLAGS)

 -- Function: int mu_memory_stream_create (mu_stream_t *STREAM, const
          char *FILENAME, int FLAGS)

 -- Function: int mu_encoder_stream_create (mu_stream_t *STREAM,
          mu_stream_t IOSTREAM, const char *ENCODING)

 -- Function: int mu_decoder_stream_create (mu_stream_t *STREAM,
          mu_stream_t IOSTREAM, const char *ENCODING)

 -- Function: int mu_stdio_stream_create (mu_stream_t *STREAM, FILE
          *STDIO, int FLAGS)
     If `MU_STREAM_NO_CLOSE' is specified, `fclose()' will not be
     called on STDIO when the stream is closed.

 -- Function: int mu_prog_stream_create (mu_stream_t *STREAM, const
          char *PROGNAME, int FLAGS)

 -- Function: int mu_filter_prog_stream_create (mu_stream_t *STREAM,
          const char *PROGNAME, mu_stream_t INPUT)

 -- Function: void mu_stream_destroy (mu_stream_t *STREAM, void *OWNER)

 -- Function: int mu_stream_open (mu_stream_t STREAM)

 -- Function: int mu_stream_close (mu_stream_t STREAM)

 -- Function: int mu_stream_is_seekable (mu_stream_t STREAM)

 -- Function: int mu_stream_get_fd (mu_stream_t STREAM, int *FD)

 -- Function: int mu_stream_get_fd2 (mu_stream_t STREAM, int *FD1, int
          *FD2)

 -- Function: int mu_stream_read (mu_stream_t STREAM, char *BUFFER,
          size_t BUFLEN, mu_off_t OFFSET, size_t *WRITEN)

 -- Function: int mu_stream_readline (mu_stream_t STREAM, char *BUFFER,
          size_t BUFLEN, mu_off_t OFFSET, size_t *WRITEN)

 -- Function: int mu_stream_size (mu_stream_t STREAM, mu_off_t *SIZE)

 -- Function: n int mu_stream_truncate (mu_stream_t STREAM, mu_off_t
          SIZE)

 -- Function: int mu_stream_write (mu_stream_t STREAM, const char
          *BUFFER, size_t BUFLEN, mu_off_t OFFSET, size_t *WRITEN)

 -- Function: int mu_stream_setbufsiz (mu_stream_t STREAM, size_t SIZE)

 -- Function: int mu_stream_flush (mu_stream_t STREAM)

 -- Function: int mu_stream_create (mu_stream_t *STREAM, int FLAGS,
          void *OWNER)
     Used to implement a new kind of stream.

 -- Function: void* mu_stream_get_owner (mu_stream_t STREAM)

 -- Function: void mu_stream_set_owner (mu_stream_t STREAM, void *OWNER)

 -- Function: int mu_stream_get_flags (mu_stream_t STREAM, int *FLAGS)

 -- Function: int mu_stream_set_flags (mu_stream_t STREAM, int FLAGS)

 -- Function: int mu_stream_get_property (mu_stream_t STREAM,
          property_t *)

 -- Function: int mu_stream_set_property (mu_stream_t STREAM,
          property_t, void *)

 -- Function: int mu_stream_get_state (mu_stream_t STREAM, int *STATE)
    `MU_STREAM_STATE_OPEN'
          Last action was `mu_stream_open'.

    `MU_STREAM_STATE_READ'
          Last action was `mu_stream_read' or `mu_stream_readline'.

    `MU_STREAM_STATE_WRITE'
          Last action was `mu_stream_write'.

    `MU_STREAM_STATE_CLOSE'
          Last action was `mu_stream_close'.

 -- Function: int mu_stream_set_destroy (mu_stream_t STREAM, void
          (*_DESTROY) (mu_stream_t), void *OWNER)

 -- Function: int mu_stream_set_open (mu_stream_t STREAM, int (*_OPEN)
          (mu_stream_t), void *OWNER)

 -- Function: int mu_stream_set_close (mu_stream_t STREAM, int
          (*_CLOSE) (mu_stream_t), void *OWNER)

 -- Function: int mu_stream_set_fd (mu_stream_t STREAM, int (*_GET_FD)
          (mu_stream_t, int *, int *), void *OWNER)

 -- Function: int mu_stream_set_read (mu_stream_t STREAM, int (*_READ)
          (mu_stream_t, char *, size_t, mu_off_t, size_t *), void
          *OWNER)

 -- Function: int mu_stream_set_readline (mu_stream_t STREAM, int
          (*_READLINE) (mu_stream_t, char *, size_t, mu_off_t, size_t
          *), void *OWNER)

 -- Function: int mu_stream_set_size (mu_stream_t STREAM, int (*_SIZE)
          (mu_stream_t, mu_off_t *), void *OWNER)

 -- Function: int mu_stream_set_truncate (mu_stream_t STREAM, int
          (*_TRUNCATE) (mu_stream_t, mu_off_t), void *OWNER)

 -- Function: int mu_stream_set_write (mu_stream_t STREAM, int
          (*_WRITE) (mu_stream_t, const char *, size_t, mu_off_t,
          size_t *), void *OWNER)

 -- Function: int mu_stream_set_flush (mu_stream_t STREAM, int
          (*_FLUSH) (mu_stream_t), void *OWNER)

 -- Function: int mu_stream_set_strerror (mu_stream_t STREAM, int
          (*_FP) (mu_stream_t, char **), void *OWNER)

 -- Function: int mu_stream_sequential_readline (mu_stream_ts STREAM,
          char *BUF, size_t SIZE, size_t *NBYTES)

 -- Function: int mu_stream_sequential_write (mu_stream_t STREAM, char
          *BUF, size_t SIZE)

 -- Function: int mu_stream_seek (mu_stream_t STREAM, mu_off_t OFF, int
          WHENCE)

 -- Function: int mu_stream_strerror (mu_stream_t STREAM, char **P)

   An example using `mu_tcp_stream_create()' to make a simple web
client:


     /* This is an example program to illustrate the use of stream functions.
        It connects to a remote HTTP server and prints the contents of its
        index page */

     #ifdef HAVE_CONFIG_H
     # include <config.h>
     #endif
     #include <stdio.h>
     #include <stdlib.h>
     #include <string.h>
     #include <errno.h>
     #include <unistd.h>
     #include <sys/time.h>

     #include <mailutils/mailutils.h>

     char wbuf[1024];
     char rbuf[1024];

     size_t io_timeout = 3;
     size_t io_attempts = 3;

     int
     http_stream_wait (mu_stream_t stream, int flags, size_t *attempt)
     {
       int rc;
       int oflags = flags;
       struct timeval tv;

       while (*attempt < io_attempts)
         {
           tv.tv_sec = io_timeout;
           tv.tv_usec = 0;
           rc = mu_stream_wait (stream, &oflags, &tv);
           switch (rc) {
           case 0:
             if (flags & oflags)
               return 0;
             /* FALLTHROUGH */
           case EAGAIN:
           case EINPROGRESS:
             ++*attempt;
             continue;

           default:
             return rc;
           }
         }
       return ETIMEDOUT;
     }

     int
     main (int argc, char **argv)
     {
       int ret, off = 0;
       mu_stream_t stream;
       size_t nb, size;
       size_t attempt;
       char *url = "www.gnu.org";

       if (argc > 3)
         {
           fprintf (stderr, "usage: %s [hostname [url]]\n", argv[0]);
           exit (1);
         }

       if (argc > 1)
         url = argv[1];

       snprintf (wbuf, sizeof wbuf, "GET %s HTTP/1.0\r\n\r\n",
                 argc == 3 ? argv[2] : "/");

       ret = mu_tcp_stream_create (&stream, url, 80, MU_STREAM_NONBLOCK);
       if (ret != 0)
         {
           mu_error ("mu_tcp_stream_create: %s", mu_strerror (ret));
           exit (EXIT_FAILURE);
         }

       for (attempt = 0; (ret = mu_stream_open (stream)); )
         {
           if ((ret == EAGAIN || ret == EINPROGRESS) && attempt < io_attempts)
             {
               ret = http_stream_wait(stream, MU_STREAM_READY_WR, &attempt);
               if (ret == 0)
                 continue;
             }
           mu_error ("mu_stream_open: %s", mu_strerror (ret));
           exit (EXIT_FAILURE);
         }

       for (attempt = 0, size = strlen (wbuf); size > 0; )
         {
           ret = mu_stream_write (stream, wbuf + off, strlen (wbuf), 0, &nb);
           if (ret == 0)
             {
               if (nb == 0)
                 {
                   mu_error("mu_stream_write: wrote 0 bytes");
                   exit (EXIT_FAILURE);
                 }
               off += nb;
               size -= nb;
             }
           else if (ret == EAGAIN)
             {
               if (attempt < io_attempts)
                 {
                   ret = http_stream_wait (stream, MU_STREAM_READY_WR, &attempt);
                   if (ret)
                     {
                       mu_error ("http_wait failed: %s", mu_strerror (ret));
                       return -1;
                     }
                   continue;
                 }
               else
                 {
                   mu_error ("mu_stream_write timed out");
                   exit (EXIT_FAILURE);
                 }
             }
           else
             {
               mu_error ("mu_stream_write: %s", mu_strerror (ret));
               exit (EXIT_FAILURE);
             }
         }

       attempt = 0;
       for (;;)
         {
           ret = mu_stream_read (stream, rbuf, sizeof (rbuf), 0, &nb);
           if (ret == 0)
             {
               if (nb == 0)
                 break;
               write (1, rbuf, nb);
             }
           else if (ret == EAGAIN)
             {
               if (attempt < io_attempts)
                 {
                   ret = http_stream_wait (stream, MU_STREAM_READY_RD, &attempt);
                   if (ret)
                     {
                       mu_error ("http_stream_wait failed: %s", mu_strerror (ret));
                       exit (EXIT_FAILURE);
                     }
                 }
               else
                 {
                   mu_error ("mu_stream_read: %s", mu_strerror (ret));
                   exit (EXIT_FAILURE);
                 }
             }
         }

       ret = mu_stream_close (stream);
       if (ret != 0)
         {
           mu_error ("mu_stream_close: %s", mu_strerror (ret));
           exit (EXIT_FAILURE);
         }

       mu_stream_destroy (&stream, NULL);
       exit (EXIT_SUCCESS);
     }

3.1.10 Iterator
---------------

     `/* Prefix _mu_iterator__ is reserved. */'
     `#include <mailutils/iterator.h>'

 -- Function: int mu_iterator_create (mu_iterator_t *ITERATOR, void
          *OBJ)

 -- Function: int mu_iterator_dup (mu_iterator_t *ITERATOR,
          mu_iterator_t ORIG)

 -- Function: void mu_iterator_destroy (mu_iterator_t *)

 -- Function: int mu_iterator_first (mu_iterator_t)

 -- Function: int mu_iterator_next (mu_iterator_t)

 -- Function: int mu_iterator_current (mu_iterator_t, void **ITEM)

 -- Function: int mu_iterator_is_done (mu_iterator_t)

 -- Function: int mu_iterator_attach (mu_iterator_t *ROOT,
          mu_iterator_t ITERATOR)

 -- Function: int mu_iterator_detach (mu_iterator_t *ROOT,
          mu_iterator_t ITERATOR)

 -- Function: void mu_iterator_advance (mu_iterator_t ITERATOR, void
          *ITEM)

 -- Function: int mu_iterator_set_first (mu_iterator_t ITERATOR, int
          (*FIRST) (void *))

 -- Function: int mu_iterator_set_next (mu_iterator_t ITERATOR, int
          (*NEXT) (void *))

 -- Function: int mu_iterator_set_getitem (mu_iterator_t ITERATOR, int
          (*GETITEM) (void *, void **))

 -- Function: int mu_iterator_set_finished_p (mu_iterator_t ITERATOR,
          int (*FINISHED_P) (void *))

 -- Function: int mu_iterator_set_dup (mu_iterator_t ITR, int (*DUP)
          (void **PTR, void *DATA))

 -- Function: int mu_iterator_set_destroy (mu_iterator_t ITR, int
          (*DESTROY) (mu_iterator_t ITR, void *DATA))

 -- Function: int mu_iterator_set_curitem_p (mu_iterator_t ITR, int
          (*CURITEM_P) (void *, void *))

3.1.11 Authenticator
--------------------

     `/* Prefixes _mu_authority__, _mu_ticket__, and _mu_wicket__ are reserved. */'
     `#include <mailutils/auth.h>'

   There are many ways to authenticate to a server. To be flexible the
authentication process is provided by three objects `mu_authority_t',
`mu_ticket_t', and `mu_wicket_t'. The `mu_authority_t' can implement
different protocol like APOP, MD5-AUTH, One Time Passwd, etc. By default
if a mailbox does not understand or know how to authenticate it falls
back to user/passwd authentication. The `mu_ticket_t' is a way for
Mailboxes and Mailers provide a way to authenticate when the URL does
not contain enough information. The default action is to call the
function `mu_authority_authenticate()' which will get the _user_ and
_passwd_ if not set, this function can be overridden by a custom method.

 -- Function: int mu_ticket_create (mu_ticket_t *, void *OWNER)

 -- Function: void mu_ticket_destroy (mu_ticket_t *, void *OWNER)

 -- Function: int mu_ticket_set_destroy (mu_ticket_t, void (*)
          (mu_ticket_t), void *OWNER)

 -- Function: void* mu_ticket_get_owner (mu_ticket_t)

 -- Function: int mu_ticket_set_pop (mu_ticket_t, int (*_POP)
          (mu_ticket_t, url_t, const char *, char **), void *)

 -- Function: int mu_ticket_pop (mu_ticket_t, url_t, const char *, char
          **)

 -- Function: int mu_ticket_set_data (mu_ticket_t, void *, void *OWNER)

 -- Function: int mu_ticket_get_data (mu_ticket_t, void **)


 -- Function: int mu_authority_create (mu_authority_t *, mu_ticket_t,
          void *)

 -- Function: void mu_authority_destroy (mu_authority_t *, void *)

 -- Function: void* mu_authority_get_owner (mu_authority_t)

 -- Function: int mu_authority_set_ticket (mu_authority_t, mu_ticket_t)

 -- Function: int mu_authority_get_ticket (mu_authority_t, mu_ticket_t
          *)

 -- Function: int mu_authority_authenticate (mu_authority_t)

 -- Function: int mu_authority_set_authenticate (mu_authority_t, int
          (*_AUTHENTICATE) (mu_authority_t), void *)

 -- Function: int mu_authority_create_null (mu_authority_t *AUTHORITY,
          void *OWNER)


 -- Function: int mu_wicket_create (mu_wicket_t *, const char *)

 -- Function: void mu_wicket_destroy (mu_wicket_t *)

 -- Function: int mu_wicket_set_filename (mu_wicket_t, const char *)

 -- Function: int mu_wicket_get_filename (mu_wicket_t, char *, size_t,
          size_t *)

 -- Function: int mu_wicket_set_ticket (mu_wicket_t, int (*)
          (mu_wicket_t, const char *, const char *, mu_ticket_t *))

 -- Function: int mu_wicket_get_ticket (mu_wicket_t, mu_ticket_t *,
          const char *, const char *)


   A simple example of an authenticate function:

     #include <stdio.h>
     #include <string.h>
     #include <mailutils/auth.h>

     int
     my_authenticate (auth_t auth, char **user, char **passwd)
     {
       char u[128] = "";
       char p[128] = "";

       /* prompt the user name */
       printf ("User: ");
       fflush (stdout);
       fgets (u, sizeof (u), stdin);
       u[strlen (u) - 1] = '\0'; /* nuke the trailing NL */

       /* prompt the passwd */
       printf ("Passwd: "); fflush (stdout);
       echo_off ();
       fgets (p, sizeof(p), stdin);
       echo_on ();
       p[strlen (p) - 1] = '\0';

       /* duplicate */
       *user = strdup (u);
       *passwd = strdup (p);
       return 0;
     }

3.1.12 Address
--------------

     `/* Prefix _address__ is reserved. */'
     `#include <mailutils/address.h>'

   The Internet address format is defined in RFC 822. RFC 822 has been
updated, and is now superceeded by RFC 2822, which makes some
corrections and clarifications. References to RFC 822 here apply
equally to RFC 2822.

   The RFC 822 format is more flexible than many people realize, here
is a quick summary of the syntax this parser implements, see RFC 822
for the details. `[]' pairs mean "optional", `/' means "one or the
other", and double-quoted characters are literals.

     addr-spec    = LOCAL-PART "@" DOMAIN
     mailbox      = ADDR-SPEC ["(" DISPLAY-NAME ")"] /
                    [DISPLAY-NAME] "<" [ROUTE] ADDR-SPEC ">"
     mailbox-list = MAILBOX ["," MAILBOX-LIST]
     group        = DISPLAY-NAME ":" [MAILBOX-LIST] ";"
     address      = MAILBOX / GROUP / UNIX-MBOX
     address-list = ADDRESS ["," ADDRESS-LIST]

   Unix-mbox is a non-standard extension meant to deal with the common
practice of using user names as addresses in mail utilities. It allows
addresses such as "root" to be parsed correctly. These are *not* valid
internet email addresses, they must be qualified before use.

   Several address functions have a set of common arguments with
consistent semantics, these are described here to avoid repetition.

   Since an address-list may contain multiple addresses, they are
accessed by a *one-based* index number, NO. The index is one-based
because pop, imap, and other message stores commonly use one-based
counts to access messages and attributes of messages.

   If LEN is greater than `0' it is the length of the buffer BUF, and
as much of the component as possible will be copied into the buffer.
The buffer will be `NULL' terminated.

   The size of a particular component may be queried by providing `0'
for the LEN of the buffer, in which case the buffer is optional.  In
this case, if N is provided *N is assigned the length of the component
string.

 -- Data Type: mu_address_t
     The `mu_address_t' object is used to hold information about a
     parsed RFC822 address list, and is an opaque data structure to the
     user. Functions are provided to retrieve information about an
     address in the address list.

 -- Function: int mu_address_create (mu_address_t *ADDR, const char
          *STRING)
     This function allocates and initializes ADDR by parsing the RFC822
     address-list STRING.

     The return value is `0' on success and a code number on error
     conditions:
    `EINVAL'
          Invalid usage, usually a required argument was `NULL'.

    `ENOMEM'
          Not enough memory to allocate resources.

    `ENOENT'
          Invalid RFC822 syntax, parsing failed.

 -- Function: int mu_address_createv (mu_address_t *ADDR, const char
          *SV, size_t LEN)
     This function allocates and initializes ADDR by parsing the array
     of pointers to RFC822 address-lists in SV. If LEN is `-1', then SV
     must be `NULL' terminated in the fashion of ARGV, otherwise LEN is
     the length of the array.

     The return value is `0' on success and a code number on error
     conditions:
    `EINVAL'
          Invalid usage, usually a required argument was `NULL'.

    `ENOMEM'
          Not enough memory to allocate resources.

    `ENOENT'
          Invalid RFC822 syntax, parsing failed.

 -- Function: void mu_address_destroy (mu_address_t *ADDR)
     The ADDR is destroyed.

 -- Function: int mu_address_get_nth (mu_address_t ADDR, size_t NO,
          mu_address_t *RET)

 -- Function: int mu_address_get_email (mu_address_t ADDR, size_t NO,
          char* BUF, size_t LEN, size_t *N)
     Accesses the NOth email address component of the address list. This
     address is the plain email address, correctly quoted, suitable for
     using in an smtp dialog, for example, or as the address part of a
     contact book entry.

     Note that the entry may be valid, but be a group name. In this
     case success is returned, but the length of the address is `0'.

     The return value is `0' on success and a code number on error
     conditions:
    `EINVAL'
          Invalid usage, usually a required argument was `NULL'.

    `ENOENT'
          The index NO is outside of the range of available addresses.

 -- Function: int mu_address_get_local_part (mu_address_t ADDR, size_t
          NO, char *BUF, size_t LEN, size_t *N)
     Accesses the local-part of an email addr-spec extracted while
     parsing the NOth email address.

     The return value is `0' on success and a code number on error
     conditions:
    `EINVAL'
          Invalid usage, usually a required argument was `NULL'.

    `ENOENT'
          The index NO is outside of the range of available addresses.

 -- Function: int mu_address_get_domain (mu_address_t ADDR, size_t NO,
          char *BUF, size_t LEN, size_t *N)
     Accesses the domain of an email addr-spec extracted while parsing
     the NOth email address. This will be `0' length for a unix-mbox.

     The return value is `0' on success and a code number on error
     conditions:
    `EINVAL'
          Invalid usage, usually a required argument was `NULL'.

    `ENOENT'
          The index NO is outside of the range of available addresses.

 -- Function: int mu_address_get_personal (mu_address_t ADDR, size_t
          NO, char *BUF, size_t LEN, size_t *N)
     Accesses the display-name describing the NOth email address. This
     display-name is optional, so may not be present. If it is not
     present, but there is an RFC822 comment after the address, that
     comment will be returned as the personal phrase, as this is a
     common usage of the comment even though it is not defined in the
     internet mail standard.

     A group is a kind of a special case. It has a display-name,
     followed by an optional mailbox-list. The display-name will be
     allocated an address all it's own, but all the other elements
     (local-part, domain, etc.) will be zero-length. So "a group: ;" is
     valid, will have a count of 1, but `mu_address_get_email()', and
     all the rest, will return zero-length output.

     The return value is `0' on success and a code number on error
     conditions:
    `EINVAL'
          Invalid usage, usually a required argument was `NULL'.

    `ENOENT'
          The index NO is outside of the range of available addresses.

 -- Function: int mu_address_get_comments (mu_address_t ADDR, size_t
          NO, char *BUF, size_t LEN, size_t *N)
     Accesses the comments extracted while parsing the NOth email
     address.  These comments have no defined meaning, and are not
     currently collected.

     The return value is `0' on success and a code number on error
     conditions:
    `EINVAL'
          Invalid usage, usually a required argument was `NULL'.

    `ENOENT'
          The index NO is outside of the range of available addresses.

 -- Function: int mu_address_get_route (mu_address_t ADDR, size_t NO,
          char *BUF, size_t LEN, size_t *N)
     Accesses the route of an email addr-spec extracted while parsing
     the NOth email address. This is a rarely used RFC822 address
     syntax, but is legal in SMTP as well. The entire route is returned
     as a string, those wishing to parse it should look at
     `mailutils/parse822.h'.

     The return value is `0' on success and a code number on error
     conditions:
    `EINVAL'
          Invalid usage, usually a required argument was `NULL'.

    `ENOENT'
          The index NO is outside of the range of available addresses.

 -- Function: int mu_address_aget_email (mu_address_t ADDR, size_t NO,
          char **BUFP)
     As above, but mallocs the email address, if present, and write a
     pointer to it into BUFP. BUFP will be `NULL' if there is no email
     address to return.

     The return value is `0' on success and a code number on error
     conditions:
    `EINVAL'
          Invalid usage, usually a required argument was `NULL'.

    `ENOENT'
          The index NO is outside of the range of available addresses.

 -- Function: int mu_address_aget_local_part (mu_address_t ADDR, size_t
          NO, char **BUF)

 -- Function: int mu_address_aget_domain (mu_address_t ADDR, size_t NO,
          char **BUF)

 -- Function: int mu_address_aget_personal (mu_address_t ADDR, size_t
          NO, char **BUF)

 -- Function: int mu_address_is_group (mu_address_t ADDR, size_t NO,
          int *YES)
     Sets *YES to `1' if this address is just the name of a group, `0'
     otherwise. This is faster than checking if the address has a
     non-zero length personal, and a zero-length local_part and domain.

     YES can be `NULL', though that doesn't serve much purpose other
     than determining that NO refers to an address.

     Currently, there is no way to determine the end of the group.

     The return value is `0' on success and a code number on error
     conditions:
    `EINVAL'
          Invalid usage, usually a required argument was `NULL'.

    `ENOENT'
          The index NO is outside of the range of available addresses.

 -- Function: int mu_address_to_string (mu_address_t *ADDR, char *BUF,
          size_t LEN, size_t *N)
     Returns the entire address list as a single RFC822 formatted
     address list.

     The return value is `0' on success and a code number on error
     conditions:
    `EINVAL'
          Invalid usage, usually a required argument was `NULL'.

    `ENOMEM'
          Not enough memory to allocate resources.

 -- Function: int mu_address_get_count (mu_address_t ADDR, size_t
          *COUNT)
     Returns a count of the addresses in the address list.

     If ADDR is `NULL', the count is `0'. If COUNT is not `NULL', the
     count will be written to *COUNT.

     The return value is `0'.

 -- Function: int mu_address_get_group_count (mu_address_t ADDR, size_t
          *)

 -- Function: int mu_address_get_email_count (mu_address_t ADDR, size_t
          *)

 -- Function: int mu_address_get_unix_mailbox_count (mu_address_t ADDR,
          size_t *)

 -- Function: int mu_address_contains_email (mu_address_t ADDR, const
          char *EMAIL)

 -- Function: int mu_address_union (mu_address_t *A, mu_address_t B)

 -- Function: size_t mu_address_format_string (mu_address_t ADDR, char
          *BUF, size_t BUFLEN)

Example
-------


     #ifdef HAVE_CONFIG_H
     # include <config.h>
     #endif
     #include <stdio.h>
     #include <string.h>
     #include <errno.h>

     #include <mailutils/address.h>
     #include <mailutils/errno.h>
     #include <mailutils/mutil.h>

     #define EPARSE MU_ERR_NOENT

     static int
     parse (const char *str)
     {
       size_t no = 0;
       size_t pcount = 0;
       int status;
       const char *buf;
       mu_address_t address = NULL;

       mu_set_user_email_domain ("localhost");
       status = mu_address_create (&address, str);
       mu_address_get_count (address, &pcount);

       if (status)
         {
           printf ("%s=> error %s\n\n", str, mu_errname (status));
           return 0;
         }
       else
         {
           printf ("%s=> pcount %lu\n", str, (unsigned long) pcount);
         }

       for (no = 1; no <= pcount; no++)
         {
           int isgroup;

           mu_address_is_group (address, no, &isgroup);
           printf ("%lu ", (unsigned long) no);

           if (isgroup)
             {
               mu_address_sget_personal (address, no, &buf);
               printf ("group <%s>\n", buf);
             }
           else
             {
               mu_address_sget_email (address, no, &buf);
               printf ("email <%s>\n", buf);
             }

           if (mu_address_sget_personal (address, no, &buf) == 0 && buf && !isgroup)
             printf ("   personal <%s>\n", buf);

           if (mu_address_sget_comments (address, no, &buf) == 0 && buf)
             printf ("   comments <%s>\n", buf);

           if (mu_address_sget_local_part (address, no, &buf) == 0 && buf)
             {
               printf ("   local-part <%s>", buf);

               if (mu_address_sget_domain (address, no, &buf) == 0 && buf)
                 printf (" domain <%s>", buf);

               printf ("\n");
             }

           if (mu_address_sget_route (address, no, &buf) == 0 && buf)
             printf ("   route <%s>\n", buf);
         }
       mu_address_destroy (&address);

       printf ("\n");
       return 0;
     }

     static int
     parseinput (void)
     {
       char buf[BUFSIZ];

       while (fgets (buf, sizeof (buf), stdin) != 0)
         {
           buf[strlen (buf) - 1] = 0;
           parse (buf);
         }

       return 0;
     }

     int
     main (int argc, const char *argv[])
     {
       argc = 1;

       if (!argv[argc])
         return parseinput ();

       for (; argv[argc]; argc++)
         {
           if (strcmp (argv[argc], "-") == 0)
             parseinput ();
           else
             parse (argv[argc]);
         }

       return 0;
     }

3.1.13 Locker
-------------

     `/* Prefix _mu_locker__ is reserved. */'
     `#include <mailutils/locker.h>'

 -- Function: int mu_locker_set_default_flags (int FLAGS, enum
          mu_locker_set_mode MODE)

 -- Function: void mu_locker_set_default_retry_timeout (time_t TO)

 -- Function: void mu_locker_set_default_retry_count (size_t N)

 -- Function: void mu_locker_set_default_expire_timeout (time_t T)

 -- Function: void mu_locker_set_default_external_program (char *PATH)

   A flags of 0 means that the default will be used.

 -- Function: int mu_locker_create (mu_locker_t *, const char
          *FILENAME, int FLAGS)

 -- Function: void mu_locker_destroy (mu_locker_t *)

   Time is measured in seconds.

 -- Function: int mu_locker_set_flags (mu_locker_t, int)

 -- Function: int mu_locker_set_expire_time (mu_locker_t, int)

 -- Function: int mu_locker_set_retries (mu_locker_t, int)

 -- Function: int mu_locker_set_retry_sleep (mu_locker_t, int)

 -- Function: int mu_locker_set_external (mu_locker_t, const char
          *PROGRAM)

 -- Function: int mu_locker_get_flags (mu_locker_t, int *)

 -- Function: int mu_locker_get_expire_time (mu_locker_t, int*)

 -- Function: int mu_locker_get_retries (mu_locker_t, int *)

 -- Function: int mu_locker_get_retry_sleep (mu_locker_t, int *)

 -- Function: int mu_locker_get_external (mu_locker_t, char **)

 -- Function: int mu_locker_lock (mu_locker_t)

 -- Function: int mu_locker_touchlock (mu_locker_t)

 -- Function: int mu_locker_unlock (mu_locker_t)

 -- Function: int mu_locker_remove_lock (mu_locker_t)

3.1.14 URL
----------

A mailbox or a mailer can be described in a URL, the string will
contain the necessary information to initialize `mailbox_t', or
`mailer_t' properly.

POP3
....

The POP URL scheme contains a POP server, optional port number and the
authentication mechanism. The general form is

     <pop://[USER[;AUTH=AUTH]@]HOST[:PORT]>
      or
     <pop://[USER[:PASSWD]@]HOST[:PORT]>

   If _:port_ is omitted the default value is 110. Different forms of
authentication can be specified with _;AUTH=TYPE_.  The special string
_;AUTH=*_ indicates that the client will use a default scheme base on
the capability of the server.

     <pop://obelix@gaulois.org>
     <pop://asterix;AUTH=*@france.com>
     <pop://falbala;AUTH=+APOP@france.com>
     <pop://obelix;AUTH=+APOP@village.gaulois.org:2000>
     <pop://obelix:menhir@village.gaulois.org:2000>

   For more complete information see `RFC 2368'.

POP3S (POP3 Over SSL)
.....................

The POP3S URL scheme contains a POP server over SSL, optional port
number and the authentication mechanism. The general form is

     <pops://[USER[;AUTH=AUTH]@]HOST[:PORT]>
      or
     <pops://[USER[:PASSWD]@]HOST[:PORT]>

   If _:port_ is omitted the default value is 995.

IMAP
....

The IMAP URL scheme contains an IMAP server, optional port number and
the authentication mechanism. The general form is

     <imap://[USER[;AUTH=TYPE]]@HOST[:PORT][/MAILBOX]>
      or
     <imap://[USER[:PASSWD]]@HOST[:PORT][/MAILBOX]>

   If _:port_ is omitted the default value is 143. Different forms of
authentication can be specified with _;AUTH=TYPE_.  The special string
_;AUTH=*_ indicates that the client will use a default scheme base on
the capability of the server.

     <imap://obelix@imap.gaulois.org>
     <imap://asterix;AUTH=*@imap.france.com>
     <imap://asterix:potion@imap.france.com>

   For more complete information see `RFC 2192'.

IMAPS (IMAP Over SSL)
.....................

The IMAPS URL scheme contains an IMAP server over SSL, optional port
number and the authentication mechanism. The general form is

     <imaps://[USER[;AUTH=TYPE]]@HOST[:PORT][/MAILBOX]>
      or
     <imaps://[USER[:PASSWD]]@HOST[:PORT][/MAILBOX]>

   If _:port_ is omitted the default value is 993.

File
....

Local folder should be handle by this URL. It is preferable to let the
mailbox recognize the type of mailbox and take the appropriate action.

     <file://PATH>
     <file://var/mail/user>
     <file://home/obelix/Mail>

   For MMDF, MH local mailboxes URLs are provided,  but it is
preferable to use <file://PATH> and let the library figure out which
one.

     <mmdf://PATH>
     <mh://PATH>

Mailto
......

After setting a mailer, <mailto:> is used to tell the mailer where and
to whom the message is for.

     <mailto://HOSTNAME>

   Mailto can be used to generate short messages, for example to
subscribe to mailing lists.

     <mailto://bug-mailutils@gnu.org?body=subscribe>
     <mailto://bug-mailutils@gnu.org?Subject=hello&body=subscribe>

   For more complete information see `RFC 2368'.

URL Functions
.............

Helper functions are provided to retrieve and set the _URL_ fields.

 -- Function: int mu_url_create (mu_url_t *URL, const char *NAME)
     Create the url data structure, but do not parse it.

 -- Function: void mu_url_destroy (mu_url_t *URL)
     Destroy the url and free its resources.

 -- Function: int mu_url_parse (mu_url_t)
     Parses the url, after calling this the get functions can be called.

     The syntax, condensed from `RFC 1738', and extended with the ;auth=
     of `RFC 2384' (for POP) and `RFC 2192' (for IMAP) is:

          url =
              scheme ":" [ "//"

              [ USER [ ( ":" PASSWORD ) | ( ";auth=" AUTH ) ] "@" ]

              HOST [ ":" PORT ]

              [ ( "/" URLPATH ) | ( "?" QUERY ) ] ]

     This is a generalized URL syntax, and may not be exactly
     appropriate for any particular scheme.

 -- Function: int mu_url_get_scheme (const mu_url_t, char *, size_t,
          size_t *)

 -- Function: int mu_url_get_user (const mu_url_t, char *, size_t,
          size_t *)

 -- Function: int mu_url_get_passwd (const mu_url_t, char *, size_t,
          size_t *)

 -- Function: int mu_url_get_auth (const mu_url_t, char *, size_t,
          size_t *)

 -- Function: int mu_url_get_host (const mu_url_t, char *, size_t,
          size_t *)

 -- Function: int mu_url_get_port (const mu_url_t, long *)

 -- Function: int mu_url_get_path (const mu_url_t, char *, size_t,
          size_t *)

 -- Function: int mu_url_get_query (const mu_url_t, char *, size_t,
          size_t *)

 -- Function: const char* mu_url_to_string (const mu_url_t)

 -- Function: int mu_url_is_scheme (mu_url_t, const char *SCHEME)

 -- Function: int mu_url_is_same_scheme (mu_url_t, mu_url_t)

 -- Function: int mu_url_is_same_user (mu_url_t, mu_url_t)

 -- Function: int mu_url_is_same_path (mu_url_t, mu_url_t)

 -- Function: int mu_url_is_same_host (mu_url_t, mu_url_t)

 -- Function: int mu_url_is_same_port (mu_url_t, mu_url_t)

 -- Function: char * mu_url_decode (const char *STRING)
     Decodes an `RFC 1738' encoded string, returning the decoded string
     in allocated memory. If the string is not encoded, this
     degenerates to a `strdup()'.

 -- Function: int mu_url_is_ticket (mu_url_t TICKET, mu_url_t URL)

Example
.......


     #ifdef HAVE_CONFIG_H
     # include <config.h>
     #endif
     #include <stdlib.h>
     #include <stdio.h>
     #include <string.h>
     #include <mailutils/error.h>
     #include <mailutils/errno.h>
     #include <mailutils/url.h>

     #define CAT2(a,b) a ## b

     #define GET_AND_PRINT(field,u,buf,status)                               \
           status = CAT2(mu_url_sget_,field) (u, &buf);                      \
           if (status == MU_ERR_NOENT)                                       \
             buf = "";                                                       \
           else if (status)                                                  \
             {                                                              \
               mu_error ("cannot get %s: %s", #field, mu_strerror (status)); \
               exit (1);                                                     \
             }                                                               \
           printf ("\t" #field " <%s>\n", buf)

     static void
     print_fvpairs (mu_url_t url)
     {
       size_t fvc, i;
       char **fvp;
       int rc = mu_url_sget_fvpairs (url, &fvc, &fvp);
       if (rc)
         {
           mu_error ("cannot get F/V pairs: %s", mu_strerror (rc));
           exit (1);
         }
       if (fvc == 0)
         return;
       for (i = 0; i < fvc; i++)
         printf ("\tparam[%d] <%s>\n", i, fvp[i]);
     }

     static void
     print_query (mu_url_t url)
     {
       size_t qargc, i;
       char **qargv;
       int rc = mu_url_sget_query (url, &qargc, &qargv);
       if (rc)
         {
           mu_error ("cannot get query: %s", mu_strerror (rc));
           exit (1);
         }
       if (qargc == 0)
         return;
       for (i = 0; i < qargc; i++)
         printf ("\tquery[%d] <%s>\n", i, qargv[i]);
     }

     int
     main ()
     {
       char str[1024];
       long port = 0;
       mu_url_t u = NULL;

       while (fgets (str, sizeof (str), stdin) != NULL)
         {
           int rc;
           const char *buf;

           str[strlen (str) - 1] = '\0';     /* chop newline */
           if (strspn (str, " \t") == strlen (str))
             continue;               /* skip empty lines */
           if ((rc = mu_url_create (&u, str)) != 0)
             {
               fprintf (stderr, "mu_url_create %s ERROR: [%d] %s",
                        str, rc, mu_strerror (rc));
               exit (1);
             }
           if ((rc = mu_url_parse (u)) != 0)
             {
               printf ("%s => FAILED: [%d] %s\n",
                       str, rc, mu_strerror (rc));
               continue;
             }
           printf ("%s => SUCCESS\n", str);

           GET_AND_PRINT (scheme, u, buf, rc);
           GET_AND_PRINT (user, u, buf, rc);
           GET_AND_PRINT (passwd, u, buf, rc);
           GET_AND_PRINT (auth, u, buf, rc);
           GET_AND_PRINT (host, u, buf, rc);

           rc = mu_url_get_port (u, &port);
           if (rc)
             {
               mu_error ("cannot get %s: %s", "port", mu_strerror (rc));
               exit (1);
             }
           printf ("\tport %ld\n", port);

           GET_AND_PRINT (path, u, buf, rc);
           print_fvpairs (u);
           print_query (u);

           mu_url_destroy (&u);

         }
       return 0;
     }

3.1.15 Parse822
---------------

     `/* Prefix _mu_parse822__ is reserved. */'
     `#include <mailutils/parse822.h>'

 -- Function: int mu_parse822_is_char (char C)

 -- Function: int mu_parse822_is_digit (char C)

 -- Function: int mu_parse822_is_ctl (char C)

 -- Function: int mu_parse822_is_space (char C)

 -- Function: int mu_parse822_is_htab (char C)

 -- Function: int mu_parse822_is_lwsp_char (char C)

 -- Function: int mu_parse822_is_special (char C)

 -- Function: int mu_parse822_is_atom_char (char C)

 -- Function: int mu_parse822_is_q_text (char C)

 -- Function: int mu_parse822_is_d_text (char C)

 -- Function: int mu_parse822_is_smtp_q (char C)

 -- Function: int mu_parse822_skip_crlf (const char **P, const char *E)

 -- Function: int mu_parse822_skip_lwsp_char (const char **P, const
          char *E)

 -- Function: int mu_parse822_skip_lwsp (const char **P, const char *E)

 -- Function: int mu_parse822_skip_comments (const char **P, const char
          *E)

 -- Function: int mu_parse822_skip_nl (const char **P, const char *E)

 -- Function: int mu_parse822_digits (const char **P, const char *E,
          int MIN, int MAX, int *DIGITS)

 -- Function: int mu_parse822_special (const char **P, const char *E,
          char C)

 -- Function: int mu_parse822_comment (const char **P, const char *E,
          char **COMMENT)

 -- Function: int mu_parse822_atom (const char **P, const char *E, char
          **ATOM)

 -- Function: int mu_parse822_quoted_pair (const char **P, const char
          *E, char **QPAIR)

 -- Function: int mu_parse822_quoted_string (const char **P, const char
          *E, char **QSTR)

 -- Function: int mu_parse822_word (const char **P, const char *E, char
          **WORD)

 -- Function: int mu_parse822_phrase (const char **P, const char *E,
          char **PHRASE)

 -- Function: int mu_parse822_d_text (const char **P, const char *E,
          char **DTEXT)

 -- Function: int mu_parse822_address_list (mu_address_t *A, const char
          *S)

 -- Function: int mu_parse822_mail_box (const char **P, const char *E,
          mu_address_t *A)

 -- Function: int mu_parse822_group (const char **P, const char *E,
          mu_address_t *A)

 -- Function: int mu_parse822_address (const char **P, const char *E,
          mu_address_t *A)

 -- Function: int mu_parse822_route_addr (const char **P, const char
          *E, mu_address_t *A)

 -- Function: int mu_parse822_route (const char **P, const char *E,
          char **ROUTE)

 -- Function: int mu_parse822_addr_spec (const char **P, const char *E,
          mu_address_t *A)

 -- Function: int mu_parse822_unix_mbox (const char **P, const char *E,
          mu_address_t *A)

 -- Function: int mu_parse822_local_part (const char **P, const char
          *E, char **LOCAL_PART)

 -- Function: int mu_parse822_domain (const char **P, const char *E,
          char **DOMAIN)

 -- Function: int mu_parse822_sub_domain (const char **P, const char
          *E, char **SUB_DOMAIN)

 -- Function: int mu_parse822_domain_ref (const char **P, const char
          *E, char **DOMAIN_REF)

 -- Function: int mu_parse822_domain_literal (const char **P, const
          char *E, char **DOMAIN_LITERAL)

 -- Function: int mu_parse822_quote_string (char **QUOTED, const char
          *RAW)

 -- Function: int mu_parse822_quote_local_part (char **QUOTED, const
          char *RAW)

 -- Function: int mu_parse822_field_body (const char **P, const char
          *E, char **FIELDBODY)

 -- Function: int mu_parse822_field_name (const char **P, const char
          *E, char **FIELDNAME)

 -- Function: int mu_parse822_day (const char **P, const char *E, int
          *DAY)

 -- Function: int mu_parse822_date (const char **P, const char *E, int
          *DAY, int *MON, int *YEAR)

 -- Function: int mu_parse822_time (const char **P, const char *E, int
          *H, int *M, int *S, int *TZ, const char **TZ_NAME)

 -- Function: int mu_parse822_date_time (const char **P, const char *E,
          struct tm *TM, mu_timezone *TZ)

3.1.16 Mailcap
--------------

     `/* Prefix _mu_mailcap__ is reserved. */'
     `#include <mailutils/mailcap.h>'

   The standard `RFC 1524' (A User Agent Configuration Mechanism)
suggests a file format to be used to inform a mail user agent about
facilities for handling mail in various format. The configuration file
is known also as mailcap and it is tipically found in UNIX platforms, a
example of `/etc/mailcap':

     application/pgp; gpg < %s | metamail; needsterminal; \
            test=test %{encapsulation}=entity ; copiousoutput

   A mailcap file consists of a set of mailcap entries per line, lines
beginning with `#' are considered comments and ignored. Long mailcap
entry may be continued on multiple lines if each line ends with a
backslash character `\', the multiline will be considered a single
mailcap entry. The overall format in BNF:

     Mailcap-File = *MAILCAP-LINE
     Mailcap-Line = COMMENT | MAILCAP-ENTRY
     Comment = NEWLINE | "#" * CHAR NEWLINE
     Newline = <newline as defined by OS convention>

   Each mailcap entry consists of a number of fields, separated by
semi-colons. The first two fields are required and must occur in the
specified order, the remaining fields are optional.

     Mailcap-Entry = TYPEFIELD ";" VIEW-COMMAND ";" *[ ";" FIELD ]

 -- Data Type: mu_mailcap_t, mu_mailcap_entry_t
     The `mu_mailcap_t' and `mu_mailcap_entry_t' objects are used to
     hold information and it is an opaque data structure to the user.
     Functions are provided to retrieve information from the data
     structure.

                             mu_mailcap_t                  mu_mailcap_entry_t
     -/etc/mailcap-  +--->/------------------------\  +-->/------------------\
     (  alain   )         |  mu_mailcap_entry[0]*--|--+   |  typefield       |
                          |  mu_mailcap_entry[1]   |      |  view-command    |
                          |  .....                 |      |  field[0]        |
                          |  mu_mailcap_entry[n]   |      |  .....           |
                          \------------------------/      |  field[n]        |
                                                          \------------------/

An Example of Parsing a Mailcap File:
-------------------------------------


     #ifdef HAVE_CONFIG_H
     # include <config.h>
     #endif
     #include <stdlib.h>
     #include <stdio.h>
     #include <mailutils/mailcap.h>
     #include <mailutils/stream.h>
     #include <mailutils/error.h>

     int
     main (int argc, char **argv)
     {
       mu_stream_t stream = NULL;
       int status = 0;
       char *file = argc == 1 ? "/etc/mailcap" : argv[1];
       mu_mailcap_t mailcap = NULL;

       status = mu_file_stream_create (&stream, file, MU_STREAM_READ);
       if (status)
         {
           mu_error ("cannot create file stream %s: %s",
                     file, mu_strerror (status));
           exit (1);
         }

       status = mu_stream_open (stream);
       if (status)
         {
           mu_error ("cannot open file stream %s: %s",
                     file, mu_strerror (status));
           exit (1);
         }

       status = mu_mailcap_create (&mailcap, stream);
       if (status == 0)
         {
           int i;
           size_t count = 0;
           char buffer[256];

           mu_mailcap_entries_count (mailcap, &count);
           for (i = 1; i <= count; i++)
             {
               size_t j;
               mu_mailcap_entry_t entry = NULL;
               size_t fields_count = 0;

               printf ("entry[%d]\n", i);

               mu_mailcap_get_entry (mailcap, i, &entry);

               /* typefield.  */
               mu_mailcap_entry_get_typefield (entry, buffer,
                                               sizeof (buffer), NULL);
               printf ("\ttypefield: %s\n", buffer);

               /* view-command.  */
               mu_mailcap_entry_get_viewcommand (entry, buffer,
                                                 sizeof (buffer), NULL);
               printf ("\tview-command: %s\n", buffer);

               /* fields.  */
               mu_mailcap_entry_fields_count (entry, &fields_count);
               for (j = 1; j <= fields_count; j++)
                 {
                   int status = mu_mailcap_entry_get_field (entry, j, buffer,
                                                            sizeof (buffer), NULL);
                   if (status)
                     {
                       mu_error ("cannot retrieve field %lu: %s",
                                 (unsigned long) j,
                                 mu_strerror (status));
                       break;
                     }
                   printf ("\tfields[%d]: %s\n", j, buffer);
                 }
               printf ("\n");
             }
           mu_mailcap_destroy (&mailcap);
         }

       return 0;
     }

 -- Function: int mu_mailcap_create (mu_mailcap_t *MAILCAP, mu_stream_t
          STREAM)
     The function allocates, parses the buffer from the STREAM and
     initializes MAILCAP.  The return value is `0' on success and a
     code number on error conditions:
    `MU_ERROR_INVALID_PARAMETER'
          MAILCAP is `NULL' or STREAM is invalid.

 -- Function: void mu_mailcap_destroy (mu_mailcap_t *MAILCAP)
     Release any resources from the mailcap object.

 -- Function: int mu_mailcap_entries_count (mu_mailcap_t MAILCAP,
          size_t *COUNT)
     The function returns the number of entries found in the mailcap.
     The return value is `0' on success and a code number on error
     conditions:
    `EINVAL'
          MAILCAP or COUNT is `NULL'.

 -- Function: int mu_mailcap_get_entry (mu_mailcap_t MAILCAP, size_t
          NO, mu_mailcap_entry_t *ENTRY)
     Returns in ENTRY the mailcap entry of NO.

 -- Function: int mu_mailcap_entry_fields_count (mu_mailcap_entry_t
          ENTRY, size_t *COUNT)
     The function returns the number of fields found in the entry.  The
     return value is `0' on success and a code number on error
     conditions:
    `EINVAL'
          ENTRY or COUNT is `NULL'.

 -- Function: int mu_mailcap_entry_get_typefield (mu_mailcap_entry_t
          ENTRY, char *BUFFER, size_t BUFLEN, size_t *N)

 -- Function: int mu_mailcap_entry_get_viewcommand (mu_mailcap_entry_t
          ENTRY, char *BUFFER, size_t BUFLEN, size_t *N)

 -- Function: int mu_mailcap_entry_get_field (mu_mailcap_entry_t ENTRY,
          size_t NO, char *BUFFER, size_t BUFLEN, size_t *N)

 -- Function: int mu_mailcap_entry_get_value (mu_mailcap_entry_t ENTRY,
          const char *KEY, char *BUFFER, size_t BUFLEN, size_t *N)

 -- Function: int mu_mailcap_entry_get_compose (mu_mailcap_entry_t
          ENTRY, char *BUFFER, size_t BUFLEN, size_t *N)
     Helper function saving in buffer, the argument of "compose" field.

 -- Function: int mu_mailcap_entry_get_composetyped (mu_mailcap_entry_t
          ENTRY, char *BUFFER, size_t BUFLEN, size_t *N)
     Helper function saving in buffer, the argument of "composetyped"
     field.

 -- Function: int mu_mailcap_entry_get_edit (mu_mailcap_entry_t ENTRY,
          char *BUFFER, size_t BUFLEN, size_t *N)
     Helper function saving in buffer, the argument of "edit" field.

 -- Function: int mu_mailcap_entry_get_textualnewlines
          (mu_mailcap_entry_t ENTRY, char *BUFFER, size_t BUFLEN,
          size_t *N)
     Helper function saving in buffer, the argument of
     "textualnewlines" field.

 -- Function: int mu_mailcap_entry_get_test (mu_mailcap_entry_t ENTRY,
          char *BUFFER, size_t BUFLEN, size_t *N)
     Helper function saving in buffer, the argument of "test" field.

 -- Function: int mu_mailcap_entry_get_x11bitmap (mu_mailcap_entry_t
          ENTRY, char *BUFFER, size_t BUFLEN, size_t *N)
     Helper function saving in buffer, the argument of "x11-bitmap"
     field.

 -- Function: int mu_mailcap_entry_get_description (mu_mailcap_entry_t
          ENTRY, char *BUFFER, size_t BUFLEN, size_t *N)
     Helper function saving in buffer, the argument of "description"
     field.

 -- Function: int mu_mailcap_entry_get_nametemplate (mu_mailcap_entry_t
          ENTRY, char *BUFFER, size_t BUFLEN, size_t *N)
     Helper function saving in buffer, the argument of "nametemplate"
     field.

 -- Function: int mu_mailcap_entry_get_notes (mu_mailcap_entry_t ENTRY,
          char *BUFFER, size_t BUFLEN, size_t *N)
     Helper function saving in buffer, the argument of "notes" field.

 -- Function: int mu_mailcap_entry_needsterminal (mu_mailcap_entry_t
          ENTRY, int *ON)
     Helper function. Returns *ON != 0 if the flag `needsterminal' is
     in the record.

 -- Function: int mu_mailcap_entry_copiousoutput (mu_mailcap_entry_t
          ENTRY, int *ON)
     Helper function. Returns *ON != 0 if the flag COPIOUSOUTPUT is in
     the record.

3.2 Authentication Library
==========================

The functions from `libmailbox' library get user information from the
system user database. The library `libmuauth' extends this
functionality, allowing `libmailbox' functions to obtain information
about a user from several places, like SQL database, etc. The method
used is described in detail in *note authentication: Auth Statement.
This chapter contains a very succinct description of the underlying
library mechanism.

3.2.1 Data Types
----------------

 -- Data Type: mu_auth_fp
     This is a pointer to authentication or authorization data. It is
     defined as follows:

          typedef int (*mu_auth_fp) (struct mu_auth_data **RETURN_DATA,
                                     void *KEY,
                                     void *FUNC_DATA,
                                     void *CALL_DATA);

     Its arguments are:

    RETURN_DATA
          Upon successful return authorization handler leaves in this
          memory location a pointer to the filled `mu_auth_data'
          structure with the user's information.

          For authentication handlers this argument is always `NULL' and
          should be ignored.

    KEY
          The search key value. Its actual type depends upon type of
          the handler.

          For authorization handlers it is `const char*' if the handler
          is called by `mu_get_auth_by_name()' and `uid_t *' if it is
          called by `mu_get_auth_by_uid()'.

          For authentication handlers it is always `struct
          mu_auth_data*' representing the user's data obtained by a
          previous call to a `mu_get_auth_by_...' function.

    FUNC_DATA
          Any data associated with this handler.

    CALL_DATA
          Any call specific data. This argument is not used at the
          moment.

 -- Data Type: mu_auth_data
     The `mu_auth_data' is used to return the information about the
     user. It is similar to system `struct passwd', except that it is
     more mailutils-specific. Its definition is:

          struct mu_auth_data {
            /* These are from struct passwd */
            char    *name;       /* user name */
            char    *passwd;     /* user password */
            uid_t   uid;         /* user id */
            gid_t   gid;         /* group id */
            char    *gecos;      /* real name */
            char    *dir;        /* home directory */
            char    *shell;      /* shell program */
            /* */
            char    *mailbox;    /* Path to the user's system mailbox */
            int     change_uid;  /* Should the uid be changed? */
          };

 -- Data Type: mu_auth_module
     The `mu_auth_module' structure contains full information about a
     libmuauth module. It is declared as follows:

          struct mu_auth_module {
            char           *name;              /* Module name */
            struct argp    *argp;              /* Corresponding argp structure */
            mu_auth_fp     authenticate;       /* Authentication function ... */
            void           *authenticate_data; /* ... and its specific data */
            mu_auth_fp     auth_by_name;       /* Get user info by user name */
            void           *auth_by_name_data; /* ... and its specific data */
            mu_auth_fp     auth_by_uid;        /* Get user info by user id */
            void           *auth_by_uid_data;  /* ... and its specific data */
          };

3.2.2 Initializing `libmuauth'
------------------------------

 -- Function: void mu_auth_init (void)
     This function registers the command line capability "auth". It
     must be called after registering `libmuauth' modules and before
     calling `mu_agrp_parse()'. If an error occurs, this function prints
     diagnostic message and aborts the program.

 -- Function: void MU_AUTH_REGISTER_ALL_MODULES (void)
     This macro registers all default modules and calls
     `mu_auth_init()'.

3.2.3 Module Creation and Destruction
-------------------------------------

 -- Function: int mu_auth_data_alloc (struct mu_auth_data **PTR, const
          char *NAME, const char *PASSWD, uid_t UID, gid_t GID, const
          char *GECOS, const char *DIR, const char *SHELL, const char
          *MAILBOX, int CHANGE_UID)
     Create a `mu_auth_data' structure and initialize it with the given
     values. Returns 0 on success and 1 otherwise.

 -- Function: void mu_auth_data_free (struct mu_auth_data *PTR)
     Free the `mu_auth_data' structure allocated by a call to
     `mu_auth_data_alloc()'.

 -- Function: void mu_auth_register_module (struct mu_auth_module *MOD)
     Register the module defined by the MOD argument.

3.2.4 Obtaining Authorization Information
-----------------------------------------

 -- Function: int mu_auth_runlist (list_t FLIST, struct mu_auth_data
          **RETURN_DATA, void *KEY, void *CALL_DATA);
     The list is expected to contain `mu_auth_fp' pointers. Each of them
     is dereferenced and executed until either the list is exhausted or
     any of the functions returns non-zero, whichever occurs first. The
     RETURN_DATA and KEY arguments are passed as the first two
     parameters to the function (see the definition of `mu_auth_fp',
     notice the footnote), the `call_data' is passed as its last
     parameter.

     The function returns 0 if none of the functions from `list'
     succeeded, i.e. returned non-zero value. Otherwise it returns the
     return code from the succeeded function.

 -- Function: struct mu_auth_data * mu_get_auth_by_name (const char
          *USERNAME)
     Search the information about given user by its username. Similar to
     system's `getpwnam' call).

 -- Function: struct mu_auth_data * mu_get_auth_by_uid (uid_t UID)
     Search the information about given user by its uid. Similar to
     system's `getpwuid' call).

 -- Function: int mu_authenticate (struct mu_auth_data *AUTH_DATA, char
          *PASS)
     Authenticate the user whose data are in AUTH_DATA using password
     PASS. Return 0 if the user is authenticated.

3.2.5 Existing Modules
----------------------

 -- Function: int mu_auth_nosupport (struct mu_auth_data **RETURN_DATA,
          void *KEY, void *FUNC_DATA, void *CALL_DATA);
     The "not-supported" module. Always returns `ENOSYS'.

 -- Variable: mu_auth_system_module
     This module is always registered even if `libmuauth' is not linked.
     It performs usual authentication using system user database
     (`/etc/password' et al.)

 -- Variable: mu_auth_generic_module
     This module is always registered even if `libmuauth' is not linked.
     Both its authorization handlers are `mu_auth_nosupport'. Its
     authentication handler computes the MD5 or DES hash over the
     supplied password with the seed taken from `passwd' member of its
     KEY argument. Then it compares the obtained hash with the `passwd'
     member itself and returns 1 if both strings match.

 -- Variable: mu_auth_pam_module
     Implements PAM authentication. Both authorization handlers are
     `mu_auth_nosupport()'.

 -- Variable: mu_auth_sql_module
     Implements authentication and authorization via MySQL database. The
     credentials for accessing the database are taken from global
     variables `sql_host', `sql_port', `sql_user', `sql_passwd' and
     `sql_db'. The SQL queries for retrieving user information from
     global variables `sql_getpwnam_query' and `sql_getpwuid_query'.
     The variable `sql_getpass_query' keeps the query used for
     retrieving user's password. , for information on command line
     options used to set these variables.

 -- Variable: mu_auth_virtual_module
     Implements `mu_get_auth_by_name' method using virtual mail domains.
     Neither `mu_get_auth_by_uid' nor `mu_authenticate' is implemented.
     This module must be used together with `generic' module.

3.2.6 Using `libmuauth' in Your Programs
----------------------------------------

To link your program against `libmuauth', obtain loader arguments by
running `mailutils-config' as follows:

     mailutils-config --link auth
   *Note mailutils-config::, for more information about this utility.

   Here is a sample Makefile fragment:

     MU_LDFLAGS=`mailutils-config --link auth`
     MU_INCLUDES=`mailutils-config --include`

     myprog: myprog.c
             $(CC) -omyprog $(CFLAGS) $(MU_INCLUDES) myprog.c $(MU_LDFLAGS)

   If your program will be using only default modules provided by the
library, then it will suffice to call `MU_AUTH_REGISTER_ALL_MODULES()'
somewhere near the start of your program. As an example, consider the
following code fragment (it is taken from the `imap4d' daemon):

     int
     main (int argc, char **argv)
     {
       struct group *gr;
       int status = EXIT_SUCCESS;

       state = STATE_NONAUTH; /* Starting state in non-auth.  */

       MU_AUTH_REGISTER_ALL_MODULES ();
       mu_argp_parse (&argp, &argc, &argv, 0, imap4d_capa,
                      NULL, &daemon_param);
       ...

   Otherwise, if your program will use it's own modules, first register
them with `mu_auth_register_module' and then call `mu_auth_init()',
e.g.:

     struct mu_auth_module radius_module = {
       ...
     };

     struct mu_auth_module ext_module = {
       ...
     };

     int
     main (int argc, char **argv)
     {
       mu_auth_register_module (&radius_module);
       mu_auth_register_module (&ext_module);
       mu_auth_init ();

       ...

   These two approaches may be combined, allowing you to use both your
modules and the ones provided by Mailutils. Consider the example below:

     int
     main (int argc, char **argv)
     {
       mu_auth_register_module (&radius_module);
       mu_auth_register_module (&ext_module);
       MU_AUTH_REGISTER_ALL_MODULES ();

       ...
     }

3.3 Mailutils to Scheme Interface
=================================

The library `libmu_scm' provides an interface between Mailutils and
Guile, allowing to access the Mailutils functionality from a Scheme
program. For more information about Guile, refer to *note Overview:
(guile)Top. For information about Scheme programming language, *Note
Top: (r4rs)Top.

3.3.1 Address Functions
-----------------------

 -- Scheme procedure: mu-address-get-personal address num
     Return personal part of the NUMth email address from ADDRESS.


 -- Scheme procedure: mu-address-get-comments address num
     Return comment part of the NUMth email address from ADDRESS.


 -- Scheme procedure: mu-address-get-email address num
     Return email part of the NUMth email address from ADDRESS.


 -- Scheme procedure: mu-address-get-domain address num
     Return domain part of the NUMth email address from ADDRESS.


 -- Scheme procedure: mu-address-get-local address num
     Return local part of the NUMth email address from ADDRESS.


 -- Scheme procedure: mu-address-get-count address
     Return number of parts in email address ADDRESS.


 -- Scheme procedure: mu-username->email name
     Deduce user's email address from his username. If NAME is omitted,
     current username is assumed


3.3.2 Mailbox Functions
-----------------------

 -- Scheme procedure: mu-mail-directory url
     If URL is given, sets it as a name of the user's mail directory.
     Returns the current value of the mail directory.

 -- Scheme procedure: mu-folder-directory url
     If URL is given, sets it as a name of the user's folder directory.
     Returns the current value of the folder directory.

 -- Scheme procedure: mu-mailbox-open url mode
     Opens the mailbox specified by URL. MODE is a string, consisting of
     the characters described below, giving the access mode for the
     mailbox

     MODE          Meaning
     -------------------------------------------------------------- 
     r             Open for reading.
     w             Open for writing.
     a             Open for appending to the end of the mailbox.
     c             Create the mailbox if it does not exist.


 -- Scheme procedure: mu-mailbox-close mbox
     Closes mailbox MBOX.

 -- Scheme procedure: mu-mailbox-get-url mbox
     Returns url of the mailbox MBOX.

 -- Scheme procedure: mu-mailbox-get-port mbox mode
     Returns a port associated with the contents of the MBOX.  MODE is
     a string defining operation mode of the stream. It may contain any
     of the two characters: `r' for reading, `w' for writing.


 -- Scheme procedure: mu-mailbox-get-message mbox msgno
     Retrieve from message #MSGNO from the mailbox MBOX.

 -- Scheme procedure: mu-mailbox-messages-count mbox
     Returns number of messages in the mailbox MBOX.

 -- Scheme procedure: mu-mailbox-expunge mbox
     Expunges deleted messages from the mailbox MBOX.

 -- Scheme procedure: mu-mailbox-append-message mbox mesg
     Appends message MESG to the mailbox MBOX.

3.3.3 Message Functions
-----------------------

 -- Scheme procedure: mu-message-create
     Creates an empty message.


 -- Scheme procedure: mu-message-copy mesg
     Creates the copy of the message MESG.


 -- Scheme procedure: mu-message-destroy mesg
     Destroys the message MESG.

 -- Scheme procedure: mu-message-set-header mesg header value replace
     Sets new VALUE to the header HEADER of the message MESG.  If
     HEADER is already present in the message its value is replaced
     with the supplied one if the optional REPLACE is #t. Otherwise, a
     new header is created and appended.

 -- Scheme procedure: mu-message-get-size mesg
     Returns the size of the message MESG .

 -- Scheme procedure: mu-message-get-lines mesg
     Returns number of lines in the given message.


 -- Scheme procedure: mu-message-get-sender mesg
     Returns email address of the sender of the message MESG.


 -- Scheme procedure: mu-message-get-header mesg header
     Returns value of the header HEADER from the message MESG.


 -- Scheme procedure: mu-message-get-header-fields mesg headers
     Returns the list of headers in the message MESG. Optional argument
     HEADERS gives a list of header names to restrict return value to.


 -- Scheme procedure: mu-message-set-header-fields mesg list replace
     Set the headers in the message MESG from LIST LIST is a list of
     conses (cons HEADER VALUE). The function sets these headers in the
     message MESG.  Optional parameter REPLACE specifies whether the
     new header values should replace the headers already present in the
     message.

 -- Scheme procedure: mu-message-delete mesg flag
     Mark the message MESG as deleted. Optional argument FLAG allows to
     toggle deletion mark. The message is deleted if it is `#t' and
     undeleted if it is `#f'

 -- Scheme procedure: mu-message-get-flag mesg flag
     Return value of the attribute FLAG of the message MESG.

 -- Scheme procedure: mu-message-set-flag mesg flag value
     Set the attribute FLAG of the message MESG. If optional VALUE is
     #f, the attribute is unset.

 -- Scheme procedure: mu-message-get-user-flag mesg flag
     Return the value of the user attribute FLAG from the message MESG.

 -- Scheme procedure: mu-message-set-user-flag mesg flag value
     Set the given user attribute FLAG in the message MESG. If optional
     argument VALUE is `#f', the attribute is unset.

 -- Scheme procedure: mu-message-get-port mesg mode full
     Returns a port associated with the given MESG. MODE is a string
     defining operation mode of the stream. It may contain any of the
     two characters: `r' for reading, `w' for writing.  If optional
     argument FULL is specified, it should be a boolean value.  If it
     is `#t' then the returned port will allow access to any part of
     the message (including headers). If it is `#f' then the port
     accesses only the message body (the default).


 -- Scheme procedure: mu-message-get-body mesg
     Returns the message body for the message MESG.

 -- Scheme procedure: mu-message-multipart? mesg
     Returns `#t' if MESG is a multipart MIME message.

 -- Scheme procedure: mu-message-get-num-parts mesg
     Returns number of parts in a multipart MIME message. Returns `#f'
     if the argument is not a multipart message.

 -- Scheme procedure: mu-message-get-part mesg part
     Returns part #PART from a multipart MIME message MESG.

 -- Scheme procedure: mu-message-send mesg mailer from to
     Sends the message MESG. Optional MAILER overrides default mailer
     settings in mu-mailer. Optional FROM and TO give sender and
     receiver addresses.


 -- Scheme procedure: mu-message-get-uid mesg
     Returns uid of the message MESG


 -- Scheme procedure: mu-body-read-line body
     Read next line from the BODY.

 -- Scheme procedure: mu-body-write body text
     Append TEXT to message BODY.

3.3.4 MIME Functions
--------------------

 -- Scheme procedure: mu-mime-create flags mesg
     Creates a new MIME object. Both arguments are optional.  FLAGS
     specifies the type of the object to create (`0' is a reasonable
     value). MESG gives the message to create the MIME object from.

 -- Scheme procedure: mu-mime-multipart? mime
     Returns `#t' if MIME is a multipart object.


 -- Scheme procedure: mu-mime-get-num-parts mime
     Returns number of parts in the MIME object MIME.

 -- Scheme procedure: mu-mime-get-part mime num
     Returns NUMth part from the MIME object MIME.

 -- Scheme procedure: mu-mime-add-part mime mesg
     Adds MESG to the MIME object MIME.

 -- Scheme procedure: mu-mime-get-message mime
     Converts MIME object MIME to a message.


3.3.5 Logging Functions
-----------------------

 -- Scheme procedure: mu-openlog ident option facility
     Opens a connection to the system logger for Guile program.  IDENT,
     OPTION and FACILITY have the same meaning as in openlog(3)

 -- Scheme procedure: mu-logger prio text
     Distributes TEXT via syslogd priority PRIO.

 -- Scheme procedure: mu-closelog
     Closes the channel to the system logger opened by `mu-openlog'.

3.3.6 Other Functions
---------------------

 -- Scheme procedure: mu-register-format rest
     Registers desired mailutils formats. Any number of arguments can
     be given.  Each argument must be one of the following strings:

     Argument             Meaning
     -------------------------------------------------------------- 
     `mbox'               Regular UNIX mbox format
     `mh'                 MH mailbox format
     `maildir'            Maildir mailbox format
     `pop'                POP mailbox format
     `imap'               IMAP mailbox format
     `sendmail'           sendmail mailer format
     `smtp'               SMTP mailer format

     If called without arguments, the function registers all available
     formats


 -- Scheme procedure: mu-strerror err
     Return the error message corresponding to ERR, which must be an
     integer value.


3.3.7 Direct Linking
--------------------

If you plan to link your program directly to `libguile', it will
probably make sense to link `libmu_scm' directly as well. The arguments
to the program loader may be obtained by running

     mailutils-config --link guile
   *Note mailutils-config::, for more information about this utility.

   Here is a sample Makefile fragment:

     MU_LDFLAGS=`mailutils-config --link guile`
     MU_INCLUDES=`mailutils-config --include`

     myprog: myprog.c
             $(CC) -omyprog $(CFLAGS) $(MU_INCLUDES) myprog.c $(MU_LDFLAGS)

3.3.8 Dynamic Linking
---------------------

Dynamic linking is the preferred method of using `libmu_scm'. It uses
Guile "use-modules" mechanism. An interface module `mailutils.scm' is
provided in order to facilitate using this method. This module is
installed in the package data directory (by default it is
`PREFIX/share/mailutils'). A sample use of this module is:

     (set! %load-path (list "/usr/local/share/mailutils"))
     (use-modules (mailutils))

     # Now you may use mailutils functions:

     (let ((mb (mu-mailbox-open "/var/spool/mail/gray" "r")))
     ...

   _Note_, that you should explicitly modify the `%load-path' before
calling `use-modules', otherwise Guile will not be able to find
`mailutils.scm'.

3.4 Sieve Library
=================

`Libsieve' is GNU implementation of the mail filtering language Sieve.
The library is built around a "Sieve Machine" -- an abstract computer
constructed specially to handle mail filtering tasks.  This computer
has two registers: program counter and numeric accumulator; a runtime
stack of unlimited depth and the code segment. A set of functions is
provided for creating and destroying instances of Sieve Machine,
manipulating its internal data, compiling and executing a sieve program.

   The following is a typical scenario of using `libsieve':

  1. Application program creates the instance of sieve machine.

  2. Then `mu_sieve_compile' function is called to translate the Sieve
     source into an equivalent program executable by the Machine

  3. A mailbox is opened and associated with the Machine

  4. The Machine executes the program over the mailbox

  5. When the execution of the program is finished, all messages upon
     which an action was executed other than `keep' are marked with the
     delete flag. Thus, running `mailbox_expunge' upon the mailbox
     finishes the job, leaving in the mailbox only those messages that
     were preserved by the filter.

  6. Finally, the instance of Sieve Machine is destroyed and the
     resources allocated for it are reclaimed.


   The following sections describe in detail the functions from the
Sieve Library.

3.4.1 Sieve Data Types
----------------------

 -- Data Type: sieve_machine_t
     This is an opaque data type representing a pointer to an instance
     of sieve machine. The `sieve_machine_t' keeps all information
     necessary for compiling and executing the script.

     It is created by `sieve_machine_create()' and destroyed by
     `sieve_machine_destroy()'. The functions for manipulating this data
     type are described in *note Manipulating the Sieve Machine::.

 -- Data Type: mu_sieve_data_type
     This enumeration keeps the possible types of sieve data. These are:

    `SVT_VOID'
          No datatype.

    `SVT_NUMBER'
          Numeric type.

    `SVT_STRING'
          Character string.

    `SVT_STRING_LIST'
          A `mu_list_t'. Each item in this list represents a character
          string.

    `SVT_TAG'
          A sieve tag. See `mu_sieve_runtime_tag_t' below.

    `SVT_IDENT'
          A character string representing an identifier.

    `SVT_VALUE_LIST'
          A `mu_list_t'. Each item in this list is of
          `mu_sieve_value_t' type.

    `SVT_POINTER'
          An opaque pointer.

 -- Data Type: mu_sieve_value_t
     The `mu_sieve_value_t' keeps an instance of sieve data. It is
     defined as follows:

          typedef struct
          {
            mu_sieve_data_type type;        /* Type of the data */
            union {
              char *string;                 /* String value or identifier */
              size_t number;                /* Numeric value */
              mu_list_t list;               /* List value */
              mu_sieve_runtime_tag_t *tag;  /* Tag value */
              void *ptr;                    /* Pointer value */
            } v;
          }
          mu_sieve_value_t;

     Depending on the value of `type' member, following members of the
     union `v' keep the actual value:

    `SVT_VOID'
          Never appears.

    `SVT_NUMBER'
          The numeric value is kept in `number' member.

    `SVT_STRING'
          The string is kept in `string' member.

    `SVT_STRING_LIST'
    `SVT_VALUE_LIST'
          The list itself is pointed to by `list' member

    `SVT_TAG'
          The tag value is pointed to by `tag' member.

    `SVT_IDENT'
          The `string' member points to the identifier name.

    `SVT_POINTER'
          The data are pointed to by `ptr' member.


 -- Data Type: mu_sieve_tag_def_t
     This structure represents a definition of a tagged (optional)
     argument to a sieve action or test. It is defined as follows:

          typedef struct
          {
            char *name;                 /* Tag name */
            mu_sieve_data_type argtype; /* Type of tag argument. */
          }
          mu_sieve_tag_def_t;

     The `name' member points to the tag's name _without leading
     colon_. The `argtype' is set to `SVT_VOID' if the tag does not
     take argument, or to the type of the argument otherwise.

 -- Data Type: mu_sieve_runtime_tag_t
     This structure represents the tagged (optional) argument at a
     runtime.  It is defined as:

          struct mu_sieve_runtime_tag
          {
            char *tag;                   /* Tag name */
            mu_sieve_value_t *arg;       /* Tag argument (if any) */
          };

     The `arg' member is `NULL' if the tag does not take an argument.

 -- Data Type: mu_sieve_locus_t
     Objects of this type represent a location in the Sieve source file:

          typedef struct
          {
            const char *source_file;
            size_t source_line;
          }
          mu_sieve_locus_t;

 -- Data Type: mu_sieve_handler_t
     This is a pointer to function handler for a sieve action or test.
     It is defined as follows:
          typedef int (*mu_sieve_handler_t) (mu_sieve_machine_t MACH,
                                             mu_list_t ARGS,
                                             mu_list_t TAGS);

     The arguments to the handler have the following meaning:

    MACH
          Sieve machine being processed.

    ARGS
          A list of required arguments to the handler

    TAGS
          A list of optional arguments (tags).

 -- Data Type: mu_sieve_printf_t
     A pointer to a diagnostic output function. It is defined as
     follows:
          typedef int (*mu_sieve_printf_t) (void *DATA,
                                            const char *FMT, va_list AP);

    DATA
          A pointer to application specific data. These data are passed
          as second argument to `mu_sieve_machine_init()'.

    FMT
          Printf-like format string.

    AP
          Other arguments.

 -- Data Type: mu_sieve_parse_error_t
     This data type is declared as follows:
          typedef int (*mu_sieve_parse_error_t) (void *DATA,
                                                 const char *FILENAME,
                                                 int LINENO,
                                                 const char *FMT,
                                                 va_list AP);

     It is used to declare error handlers for parsing errors. The
     application-specific data are passed in the DATA argument.
     Arguments FILENAME and LINE indicate the location of the error in
     the source text, while FMT and AP give verbose description of the
     error.

 -- Data Type: mu_sieve_action_log_t
     A pointer to the application-specific logging function:

          typedef void (*mu_sieve_action_log_t) (void *DATA,
                                                 const mu_sieve_locus_t *LOCUS,
                                                 size_t MSGNO,
                                                 mu_message_t MSG,
                                                 const char *ACTION,
                                                 const char *FMT,
                                                 va_list AP);

    DATA
          Application-specific data.

    LOCUS
          Location in the Sieve source file.

    SCRIPT
          Name of the sieve script being executed.

    MSGNO
          Ordinal number of the message in mailbox, if appropriate.
          When execution is started using `sieve_message()', this
          argument is zero.

    MSG
          The message this action is executed upon.

    ACTION
          The name of the action.

    FMT
    VAR
          These two arguments give the detailed description of the
          action.

 -- Data Type: mu_sieve_relcmp_t
 -- Data Type: mu_sieve_relcmpn_t
          typedef int (*mu_sieve_relcmp_t) (int, int);
          typedef int (*mu_sieve_relcmpn_t) (size_t, size_t);

 -- Data Type: mu_sieve_comparator_t
          typedef int (*mu_sieve_comparator_t) (const char *, const char *);

     A pointer to the comparator handler function. The function compares
     its two operands and returns 1 if they are equal, and 0 otherwise.
     _Notice_, that the sense of the return value is inverted in
     comparison with most standard libc functions like `stcmp()', etc.


 -- Data Type: mu_sieve_retrieve_t
          typedef int (*mu_sieve_retrieve_t) (void *item, void *data, int idx,
                                              char **pval);

     A pointer to generic retriever function. See description of
     `mu_sieve_vlist_compare()' for details of its usage.

 -- Data Type: mu_sieve_destructor_t
          typedef void (*mu_sieve_destructor_t) (void *data);

     A pointer to destructor function. The function frees any resources
     associated with `data'. See the description of
     `mu_sieve_machine_add_destructor()' for more information.

 -- Data Type: mu_sieve_tag_checker_t
          typedef int (*mu_sieve_tag_checker_t) (const char *NAME,
                                                 mu_list_t TAGS,
                                                 mu_list_t ARGS)

     A pointer to tag checker function. The purpose of the function is
     to perform compilation-time consistency test on tags. Its
     arguments are:

    NAME
          Name of the test or action whose tags are being checked.

    TAGS
          A list of `mu_sieve_runtime_tag_t' representing tags.

    ARGS
          A list of `mu_sieve_value_t' representing required arguments
          to NAME.

     The function is allowed to make any changes in TAGS and ARGS. It
     should return 0 if the syntax is correct and non-zero otherwise.
     It is responsible for issuing the diagnostics in the latter case.
     [FIXME: describe how to do that]


3.4.2 Manipulating the Sieve Machine
------------------------------------

This subsection describes functions used to create an instance of the
sieve machine, read or alter its internal fields and destroy it.

 -- Function: int mu_sieve_machine_init (mu_sieve_machine_t *MACH, void
          *DATA)
     The `mu_sieve_machine_init()' function creates an instance of a
     sieve machine. A pointer to the instance itself is returned in the
     argument MACH. The user-specific data to be associated with the
     new machine are passed in DATA argument. The function returns 0 on
     success, non-zero error code otherwise,

 -- Function: void mu_sieve_machine_destroy (mu_sieve_machine_t *PMACH)
     This function destroys the instance of sieve machine pointed to by
     MACH parameter. After execution of `mu_sieve_machine_destroy()'
     PMACH contains `NULL'. The destructors registered with
     `mu_sieve_machine_add_destructor()' are executed in LIFO order.

 -- Function: int mu_sieve_machine_add_destructor (mu_sieve_machine_t
          MACH, mu_sieve_destructor_t DESTR, void *PTR);
     This function registers a destructor function DEST. The purpose of
     the destructor is to free any resources associated with the item
     PTR. The destructor function takes a single argument -- a pointer
     to the data being destroyed. All registered destructors are called
     in reverse order upon execution of `mu_sieve_machine_destroy()'.
     Here's a short example of the use of this function:

          static void
          free_regex (void *data)
          {
            regfree ((regex_t*)data);
          }

          int
          match_part_checker (const char *name, list_t tags, list_t args)
          {
            regex_t *regex;

            /* Initialise the regex: */
            regex = mu_sieve_malloc (mach, sizeof (*regex));
            /* Make sure it will be freed when necessary */
            mu_sieve_machine_add_destructor (sieve_machine, free_regex, regex);
            .
            .
            .
          }

 -- Function: void * mu_sieve_get_data (mu_sieve_machine_t MACH)
     This function returns the application-specific data associated with
     the instance of sieve machine. See `mu_sieve_machine_init()'.

 -- Function: mu_message_t mu_sieve_get_message (mu_sieve_machine_t
          MACH)
     This function returns the current message.

 -- Function: size_t mu_sieve_get_message_num (mu_sieve_machine_t MACH)
     This function returns the current message number in the mailbox.
     If there are no mailbox, i.e. the execution of the sieve code is
     started with `mu_sieve_message', this function returns 1.

 -- Function: int mu_sieve_get_debug_level (mu_sieve_machine_t MACH)
     Returns the debug level set for this instance of sieve machine.

 -- Function: mu_ticket_t mu_sieve_get_ticket (mu_sieve_machine_t MACH)
     Returns the authentication ticket for this machine.

 -- Function: mu_mailer_t mu_sieve_get_mailer (mu_sieve_machine_t MACH)
     Returns the mailer.

 -- Function: int mu_sieve_get_locus (mu_sieve_machine_t MACH,
          mu_sieve_locus_t *LOCUS)
     Returns the locus in the Sieve source file corresponding to the
     code pointer where the Sieve machine currently is.

 -- Function: char * mu_sieve_get_daemon_email (mu_sieve_machine_t MACH)
     This function returns the "daemon email" associated with this
     instance of sieve machine. The daemon email is an email address
     used in envelope from addresses of automatic reply messages. By
     default its local part is `<MAILER-DAEMON>' and the domain part is
     the machine name.

 -- Function: void mu_sieve_set_error (mu_sieve_machine_t MACH,
          mu_sieve_printf_t ERROR_PRINTER)
     This function sets the error printer function for the machine. If
     it is not set, the default error printer will be used. It is
     defined as follows:

          int
          _sieve_default_error_printer (void *unused, const char *fmt,
                                        va_list ap)
          {
            return mu_verror (fmt, ap);
          }

 -- Function: void mu_sieve_set_parse_error (mu_sieve_machine_t MACH,
          mu_sieve_parse_error_t P)
     This function sets the parse error printer function for the
     machine. If it is not set, the default parse error printer will be
     used. It is defined as follows:

          int
          _sieve_default_parse_error (void *unused,
                                      const char *filename, int lineno,
                                      const char *fmt, va_list ap)
          {
            if (filename)
              fprintf (stderr, "%s:%d: ", filename, lineno);
            vfprintf (stderr, fmt, ap);
            fprintf (stderr, "\n");
            return 0;
          }

 -- Function: void mu_sieve_set_debug (mu_sieve_machine_t MACH,
          mu_sieve_printf_t DEBUG);
     This function sets the debug printer function for the machine. If
     it is not set, the default debug printer is `NULL' which means no
     debugging information will be displayed.

 -- Function: void mu_sieve_set_debug_level (mu_sieve_machine_t MACH,
          mu_debug_t DBG, int LEVEL)
     This function sets the debug level for the given instance of sieve
     machine. The DBG argument is the `mu_debug_t' object to be used
     with mailutils library, the LEVEL argument specifies the debugging
     level for the sieve library itself. It is a bitwise or of the
     following values:

    `MU_SIEVE_DEBUG_TRACE'
          Trace the execution of the sieve script.

    `MU_SIEVE_DEBUG_INSTR'
          Print the sieve machine instructions as they are executed.

    `MU_SIEVE_DEBUG_DISAS'
          Dump the disassembled code of the sieve machine. Do not run
          it.

    `MU_SIEVE_DRY_RUN'
          Do not executed the actions, only show what would have been
          done.

 -- Function: void mu_sieve_set_logger (mu_sieve_machine_t MACH,
          mu_sieve_action_log_t LOGGER)
     This function sets the logger function. By default the logger
     function is `NULL', which means that the executed actions are not
     logged.

 -- Function: void mu_sieve_set_ticket (mu_sieve_machine_t MACH,
          mu_ticket_t TICKET)
     This function sets the authentication ticket to be used with this
     machine.

 -- Function: void mu_sieve_set_mailer (mu_sieve_machine_t MACH,
          mu_mailer_t MAILER)
     This function sets the mailer. The default mailer is `"sendmail:"'.

 -- Function: void mu_sieve_set_daemon_email (mu_sieve_machine_t MACH,
          const char *EMAIL)
     This functions sets the "daemon email" for `reject' and `redirect'
     actions.

 -- Function: int mu_sieve_is_dry_run (mu_sieve_machine_t MACH)
     The `mu_sieve_is_dry_run()' returns 1 if the machine is in "dry
     run" state, i.e. it will only log the actions that would have been
     executed without actually executing them. The dry run state is set
     by calling `mu_sieve_set_debug_level()' if its last argument has
     the `MU_SIEVE_DRY_RUN' bit set.

 -- Function: const char * mu_sieve_type_str (mu_sieve_data_type TYPE)
     Returns the string representation for the given sieve data type.
     The return value is a pointer to a static constant string.

3.4.3 Logging and Diagnostic Functions
--------------------------------------

 -- Function: void mu_sieve_error (mu_sieve_machine_t MACH, const char
          *FMT, ...)
     Format and output an error message using error printer of the
     machine MACH.

 -- Function: void mu_sieve_debug (mu_sieve_machine_t MACH, const char
          *FMT, ...)
     Format and output a debug message using debug printer of the
     machine MACH.

 -- Function: void mu_sieve_log_action (mu_sieve_machine_t MACH, const
          char *ACTION, const char *FMT, ...)
     Log a sieve action using logger function associated with the
     machine MACH.

 -- Function: void mu_sieve_abort (mu_sieve_machine_t MACH)
     Immediately abort the execution of the script.

3.4.4 Symbol Space Functions
----------------------------

 -- Function: mu_sieve_register_t * mu_sieve_test_lookup
          (mu_sieve_machine_t MACH, const char *NAME)
     Find a register object describing the test NAME. Returns `NULL' if
     no such test exists.

 -- Function: mu_sieve_register_t * mu_sieve_action_lookup
          (mu_sieve_machine_t MACH, const char *NAME)
     Find a register object describing the action NAME. Returns `NULL'
     if no such action exists.

 -- Function: int mu_sieve_register_test (mu_sieve_machine_t MACH,
          const char *NAME, mu_sieve_handler_t HANDLER,
          mu_sieve_data_type *ARG_TYPES, mu_sieve_tag_group_t *TAGS,
          int REQUIRED)

 -- Function: int mu_sieve_register_action (mu_sieve_machine_t MACH,
          const char *NAME, mu_sieve_handler_t HANDLER,
          mu_sieve_data_type *ARG_TYPES, mu_sieve_tag_group_t *TAGS,
          int REQUIRED)

 -- Function: int mu_sieve_register_comparator (mu_sieve_machine_t
          MACH, const char *NAME, int REQUIRED, mu_sieve_comparator_t
          IS, mu_sieve_comparator_t CONTAINS, mu_sieve_comparator_t
          MATCHES, mu_sieve_comparator_t REGEX, mu_sieve_comparator_t
          EQ)

 -- Function: int mu_sieve_tag_lookup (mu_list_t TAGLIST, char *NAME,
          mu_sieve_value_t **ARG)

 -- Function: int mu_sieve_load_ext (mu_sieve_machine_t MACH, const
          char *NAME)

3.4.5 Memory Allocation
-----------------------

The following functions act as their libc counterparts. The allocated
memory is associated with the MACH argument and is automatically freed
upon the call to `mu_sieve_machine_destroy (MACH)'.

 -- Function: void * mu_sieve_malloc (mu_sieve_machine_t MACH, size_t
          SIZE)
     Allocates SIZE bytes and returns a pointer to the allocated memory.

 -- Function: char * mu_sieve_mstrdup (mu_sieve_machine_t MACH, const
          char *STR)
     This function returns a pointer to a new string  which is a
     duplicate of the string STR.

 -- Function: void * mu_sieve_mrealloc (mu_sieve_machine_t MACH, void
          *PTR, size_t SIZE)
     Changes the size of the memory block pointed to by PTR to SIZE
     bytes. The contents will be unchanged to the minimum of the old
     and new sizes; newly allocated memory will be uninitialized. If
     PTR is `NULL', the call is equivalent to `mu_sieve_malloc(MACH,
     SIZE)'; if SIZE is equal to zero, the call is equivalent to
     `mu_sieve_mfree(PTR)'. Unless PTR is `NULL', it must have been
     returned by an earlier call to `mu_sieve_malloc()' or
     `mu_sieve_mrealloc()'.

 -- Function: void mu_sieve_mfree (mu_sieve_machine_t MACH, void *PTR)
     `mu_sieve_mfree()' frees the memory space pointed to by PTR and
     detaches it from the destructor list of MACH. The PTR must have
     been returned by a previous call to `mu_sieve_malloc()' or
     `mu_sieve_mrealloc()'. Otherwise, or if `mu_sieve_mfree(PTR)' has
     already been called before, undefined behaviour occurs.

     If PTR is `NULL', no operation is performed.

3.4.6 Compiling and Executing the Script
----------------------------------------

 -- Function: int mu_sieve_compile (mu_sieve_machine_t MACH, const char
          *NAME)
     Compile the sieve script from the file NAME.

 -- Function: int mu_sieve_mailbox (mu_sieve_machine_t MACH,
          mu_mailbox_t MBOX)
     Execute the code from the given instance of sieve machine MACH
     over each message in the mailbox MBOX.

 -- Function: int mu_sieve_message (mu_sieve_machine_t MACH,
          mu_message_t MESSAGE)
     Execute the code from the given instance of sieve machine MACH
     over the MESSAGE.

 -- Function: int mu_sieve_disass (mu_sieve_machine_t MACH)
     Dump the disassembled code of the sieve machine MACH.

3.4.7 Writing Loadable Commands
-------------------------------

This section contains an example of how to write external loadable
commands for GNU libsieve.


     /*  This is an example on how to write extension tests for GNU sieve.
         It provides test "numaddr".

         Syntax:   numaddr [":over" / ":under"] <header-names: string-list>
                   <limit: number>

         The "numaddr" test counts Internet addresses in structured headers
         that contain addresses. It returns true if the total number of
         addresses satisfies the requested relation:

         If the argument is ":over" and the number of addresses is greater than
         the number provided, the test is true; otherwise, it is false.

         If the argument is ":under" and the number of addresses is less than
         the number provided, the test is true; otherwise, it is false.

         If the argument is empty, ":over" is assumed. */

     #ifdef HAVE_CONFIG_H
     # include <config.h>
     #endif

     #include <stdlib.h>
     #include <mailutils/libsieve.h>

     struct val_ctr {  /* Data passed to the counter function */
       mu_header_t hdr;   /* Headers of the current message */
       size_t limit;   /* Limit for the number of addresses */
       size_t count;   /* Number of addresses counted so far */
     };

     /* Count addresses in a single header value.

        Input:
          ITEM is the name of the header to scan.
          DATA is a pointer to the val_ctr structure
        Return value:
          non-zero if the limit on the number of addresses has been reached. */

     static int
     _count_items (void *item, void *data)
     {
       char *name = item;
       struct val_ctr *vp = data;
       char *val;
       mu_address_t addr;
       size_t count = 0;

       if (mu_header_aget_value (vp->hdr, name, &val))
         return 0;
       if (mu_address_create (&addr, val) == 0)
         {
           mu_address_get_count (addr, &count);
           mu_address_destroy (&addr);
           vp->count += count;
         }
       free (val);
       return vp->count >= vp->limit;
     }

     /* Handler for the numaddr test */
     static int
     numaddr_test (mu_sieve_machine_t mach, mu_list_t args, mu_list_t tags)
     {
       mu_sieve_value_t *h, *v;
       struct val_ctr vc;
       int rc;

       if (mu_sieve_get_debug_level (mach) & MU_SIEVE_DEBUG_TRACE)
         {
           mu_sieve_locus_t locus;
           mu_sieve_get_locus (mach, &locus);
           mu_sieve_debug (mach, "%s:%lu: NUMADDR\n",
                        locus.source_file,
                        (unsigned long) locus.source_line);
         }

       /* Retrieve required arguments: */
       /* First argument: list of header names */
       h = mu_sieve_value_get (args, 0);
       if (!h)
         {
           mu_sieve_error (mach, "numaddr: can't get argument 1");
           mu_sieve_abort (mach);
         }
       /* Second argument: Limit on the number of addresses */
       v = mu_sieve_value_get (args, 1);
       if (!v)
         {
           mu_sieve_error (mach, "numaddr: can't get argument 2");
           mu_sieve_abort (mach);
         }

       /* Fill in the val_ctr structure */
       mu_message_get_header (mu_sieve_get_message (mach), &vc.hdr);
       vc.count = 0;
       vc.limit = v->v.number;

       /* Count the addresses */
       rc = mu_sieve_vlist_do (h, _count_items, &vc);

       /* Here rc >= 1 iff the counted number of addresses is greater or equal
          to vc.limit. If `:under' tag was given we reverse the return value */
       if (mu_sieve_tag_lookup (tags, "under", NULL))
         rc = !rc;

       return rc;
     }

     /* Syntactic definitions for the numaddr test */

     /* Required arguments: */
     static mu_sieve_data_type numaddr_req_args[] = {
       SVT_STRING_LIST,
       SVT_NUMBER,
       SVT_VOID
     };

     /* Tagged arguments: */
     static mu_sieve_tag_def_t numaddr_tags[] = {
       { "over", SVT_VOID },
       { "under", SVT_VOID },
       { NULL }
     };

     static mu_sieve_tag_group_t numaddr_tag_groups[] = {
       { numaddr_tags, NULL },
       { NULL }
     };

     /* Initialization function. It is the only function exported from this
        module. */
     int
     SIEVE_EXPORT(numaddr,init) (mu_sieve_machine_t mach)
     {
       return mu_sieve_register_test (mach, "numaddr", numaddr_test,
                                   numaddr_req_args, numaddr_tag_groups, 1);
     }

4 Sieve Language
****************

The input language understood by the GNU Sieve Library is a superset of
the Sieve language as described in RFC 3028.

4.1 Lexical Structure
=====================

Whitespace and Comments
-----------------------

Comments are semantically equivalent to whitespace and can be used
anyplace that whitespace is (with one exception in multi-line strings,
as described below).

   There are two kinds of comments: hash comments, that begin with a
`#' character that is not contained within a string and continue until
the next newline, and C-style or bracketed comments, that are delimited
by `/*' and `*/' tokens. The bracketed comments may span multiple
lines. E.g.:

     if size :over 100K
       { # this is a comment
         discard;
       }

     if size :over 100K
       { /* this is a comment
            this is still a comment */ discard /* this is a comment again
          */ ;
       }

   Like in C, bracketed comments do not nest.

Lexical Tokens
--------------

The basic lexical entities are "identifiers" and "literals".

   An "identifier" is a sequence of letters, digits and underscores,
that begins with a letter or underscore. For example, `header' and
`check_822_again' are valid identifiers, whereas `1st' is not.  A
special form of identifier is "tag": it is an identifier prefixed with
a colon (`:'), e.g.: `:comparator'.

   A "literal" is a data that is not executed, merely evaluated "as
is", to be used as arguments to commands. There are four kinds of
literals:

   * Number 

     "Numbers" are given as ordinary unsigned decimal numbers. An
     optional suffix may be used to indicate a multiple of a power of
     two.  The suffixes are: `K' specifying "kibi-", or 1,024 (2^10)
     times the value of the number; `M' specifying "mebi-", or 1,048,576
     (2^20) times the value of the number; and `G' specifying "tebi-",
     or 1,073,741,824 (2^30) times the value of the number.

     The numbers have 32 bits of magnitude.

   * String A "string" is any sequence of characters enclosed in double
     quotes (`"'). A string cannot contain newlines and double quote
     characters. This limitation will disappear in future releases.

   * Multiline Strings A "multiline string" is used to represent large
     blocks of text with embedded newlines and special characters. It
     starts with the keyword `text:' followed by a newline and ends
     with a dot (`.') on a newline by itself. Any characters between
     these two markers are taken verbatim. For example:

          text:
          ** This is an automatic response from my message **
          ** filtering program.                            **

          I can not attend your message right now. However it
          will be saved, and I will read it as soon as I am back.

          Regards,
          Fred
          .

     Notice that a hashed comment or whitespace may occur between
     `text:' and the newline. However, when used inside the multiline
     string a hash sign looses its special meaning (except in one case,
     see below) and is taken as is, as well as bracketed comment
     delimiters.  In other words, no comments are allowed within a
     multiline string. E.g.:

          text: # This is a comment

          Sample text
          # This line is taken verbatim
          /* And this line too */
          .

     The only exception to this rule is that preprocessor `include'
     statement is expanded as usual when found within a multiline string
     (*note Preprocessor::), e.g.:

          text:
          #include <myresponse.txt>
          .

     This results in the contents of file `myresponse.txt' being read
     and interpreted as the contents of the multiline string.

     GNU libsieve extends the described syntax as follows. If the
     keyword `text:' is immediately followed by a dash (`-'), then all
     leading tab characters are stripped from input lines and the line
     containing delimiter (`.'). This allows multiline strings within
     scripts to be indented in a natural fashion.

     Furthermore, if the `text:' (optionally followed by `-') is
     immediately followed by a word, this word will be used as ending
     delimiter of multiline string instead of the default dot. For
     example:

          if header "from" "me@example.com"
            {
              reject text:-EOT
                  I do not accept messages from
                  this address.
                  .
                  .
                  EOT
               # Notice that this the multiline string ends here.
               # The single dots above will be part of it.
              ;
            }

   * String Lists 

     A "string list" is a comma-delimited list of quoted strings,
     enclosed in a pair of square brackets, e.g.:

          ["me@example.com", "me00@landru.example.edu"]

     For convenience, in any context where a list of strings is
     appropriate, a single string is allowed without being a member of
     a list: it is equivalent to a list with a single member. For
     example, the following two statements are equivalent:

          exists "To";
          exists ["To"];


4.2 Syntax
==========

Being designed for the sole purpose of filtering mail, Sieve has a very
simple syntax.

4.2.1 Commands
--------------

The basic syntax element is a "command". It is defined as follows:

     COMMAND-NAME [TAGS] ARGS
   where COMMAND-NAME is an identifier representing the name of the
command, TAGS is an optional list of "optional" or "tagged arguments"
and ARGS is a list of "required" or "positional arguments".

   Positional arguments are literals delimited with whitespace. They
provide the command with the information necessary to its proper
functioning. Each command has a fixed number of positional arguments. It
is an error to supply more arguments to the command or to give it fewer
arguments than it accepts.

   Optional arguments allow to modify the behaviour of the command, like
command line options in UNIX do. They are a list of "tags" (*note
Lexical Structure::) separated by whitespace. An optional argument may
have at most one parameter.

   Each command understands a set of optional arguments. Supplying it
tags that it does not understand results in an error.

   For example, consider the following command

     header :mime :comparator "i;octet" ["to", "from"] "bug-mailutils@gnu.org"

Here, given that `header' takes two positional arguments: `header' is
command name, the list `["to", "from"]' is first positional argument
and the string `"bug-mailutils@gnu.org"' is second positional argument.
There are two optional arguments: `:mime' and `:comparator'. The latter
has a string `"i;octet"' as its parameter.

4.2.2 Actions Described
-----------------------

An "action" is a Sieve command that performs some operation over a
message. Actions do the main job in any Sieve program. Syntactically,
an action is a command terminated with semicolon, e.g.:

     keep;

     fileinto "mbox";

   GNU Sieve provides the full set of actions described in RFC 3028.
It also allows to extend this set using loadable actions. *Note
Actions::, for detailed discussion of actions.

4.2.3 Control Flow
------------------

The only control flow statement Sieve has is `if' statement. In its
simplest form it is:

     if `condition' { ... }

   The effect of this statement is that the sequence of actions between
the curly braces is executed only if the `condition' evaluates to
`true'.

   A more elaborate form of this statement allows to execute two
different sets of actions depending on whether the condition is true or
not:

     if `condition' { ... } else { ... }

   The most advanced form of the "if" statement allows to select an
action depending on what condition from the set of conditions is met.

     if `cond1' { ... } elsif `cond2' { ... } else { ... }

   There may be any number of "elsif" branches in an "if" statement.
However it may have at most one "else" branch.  Notes for C programmers:

  1. The braces surrounding each branch of an "if" statement are
     required.

  2. The "else if" construct is disallowed. Use "elsif" keyword instead.

   Here's an example of "if" statement:

     if header :contains "from" "coyote"
       {
         discard;
       }
     elsif header :contains ["subject"] ["$$$"]
       {
         discard;
       }
     else
       {
         fileinto "INBOX";
       }

   The following section describes in detail conditions used in "if"
statements.

4.2.4 Tests and Conditions
--------------------------

"Tests" are Sieve commands that return boolean value. E.g. the test

     header :contains "from" "coyote"

returns true only if the header "From" of the current message contains
substring "coyote".

   The tests shipped with the GNU Sieve are described in *note Tests::.

   "Condition" is a Sieve expression that evaluates to `true' or
`false'. In its simplest form, condition is just a Sieve test.

   To reverse the sense of a condition use keyword `not', e.g.:

     not header :contains "from" "coyote"

   The results of several conditions may be joined together by logical
`and' and `or' operations. The special form `allof' takes several tests
as its arguments and computes the logical `and' of their results.
Similarly, the form `anyof' performs logical `or' over the results of
its arguments. E.g.:

     if anyof (not exists ["From", "Date"],
               header :contains "from" "fool@example.edu")
       {
         discard;
       }

4.3 Preprocessor
================

Preprocessor statements are a GNU extension to the Sieve language.  The
syntax for a preprocessor statement is similar to that used in `C'
programming language, i.e. a pound character (`#') followed by a
preprocessor directive and its arguments. Any amount of whitespace can
be inserted between the `#' and the directive.  Currently implemented
directives are `include' and `searchpath'.

Sieve #include directive
------------------------

The `#include' directive reads in the contents of the given file.  The
contents is "inserted" into the text being parsed starting at the line
where the directive appears. The directive takes two forms:

`#include "FILENAME"'
     The FILENAME is taken relative to the current directory.

`#include <FILENAME>"'
     The FILENAME is searched in the list of include directories as
     specified by the `-I' command line options.

   If FILENAME starts with a directory separator character (`/') both
forms have the same effect.

Sieve #searchpath directive
---------------------------

The `#searchpath' directive adds its argument to the list of
directories searched for loadable modules. It has the same effect as
`library-path' Sieve configuration statement (*note library-path: Sieve
Configuration.).

4.4 Require Statement
=====================

     Syntax:   require STRING;
               require STRING-LIST;

   The require statement informs the parser that a script makes use of
a certain extension. Multiple capabilities can be declared using the
second form of the statement. The actual handling of a capability name
depends on its suffix.

   If the name starts with `comparator-', it is understood as a request
to use the specified comparator. The comparator name consists of the
characters following the suffix.

   If the name starts with `test-', it means a request to use the given
test. The test name consists of the characters following the suffix.

   Otherwise, the capability is understood as a name of an action to be
used.

   The `require' statement, if present, must be used before any other
statement that is using the required capability. As an extension, the
GNU sieve allows the `require' and any other statements to be
interspersed.

   By default the following actions and comparators need not be
explicitly required:

   * stop

   * keep

   * discard

   * i;octet

   * i;ascii-casemap

   Example:

     require ["fileinto", "reject"];

     require "fileinto";

     require "comparator-i;ascii-numeric";

   When processing arguments for `require' statement, GNU libsieve uses
the following algorithm:

  1. Look up the name in a symbol table. If the name begins with
     `comparator-' it is looked up in the comparator table. If it
     begins with `test-', the test table is used instead. Otherwise the
     name is looked up in the action table.

  2. If the name is found, the search is terminated.

  3. Otherwise, transform the name. First, any `comparator-' or `test-'
     prefix is stripped. Then, any character other than alphanumeric
     characters, `.' and `,' is replaced with dash (`-'). The name thus
     obtained is used as a file name of an external loadable module.

  4. Try to load the module. The module is searched in the following
     search paths (in the order given):

       1. Mailutils module directory. By default it is
          `$prefix/lib/mailutils'.

       2. Sieve library path as given with the `-L' options in the
          command line

       3. Additional search directories specified with the
          `#searchpath' directive.

       4. The value of the environment variable `LTDL_LIBRARY_PATH'.

       5. System library search path: The system dependent library
          search path (e.g. on Linux it is set by the contents of the
          file `/etc/ld.so.conf' and the value of the environment
          variable `LD_LIBRARY_PATH').

     The value of `LTDL_LIBRARY_PATH' and `LD_LIBRARY_PATH' must be a
     colon-separated list of absolute directories, for example,
     `"/usr/lib/mypkg:/lib/foo"'.

     In any of these directories, `libsieve' first attempts to find and
     load the given filename. If this fails, it tries to append the
     following suffixes to the file name:

       1. the libtool archive extension `.la'

       2. the extension used for native dynamic libraries on the host
          platform, e.g., `.so', `.sl', etc.

  5. If the module is found, `libsieve' executes its initialization
     function (see below) and again looks up the name in the symbol
     table. If found, search terminates successfully.

  6. If either the module is not found, or the symbol wasn't found
     after execution of the module initialization function, search is
     terminated with an error status. `libsieve' then issues the
     following diagnostic message:

          source for the required action NAME is not available

4.5 Comparators
===============

GNU libsieve supports the following built-in comparators:

`i;octet'
     This comparator simply compares the two arguments octet by octet

`i;ascii-casemap'
     It treats uppercase and lowercase characters in the ASCII subset of
     UTF-8 as the same. This is the default comparator.

`i;ascii-numeric'
     Treats the two arguments as ASCII representation of decimal
     numbers and compares their numeric values. This comparator must be
     explicitly required prior to use.

4.6 Tests
=========

This section describes the built-in tests supported by GNU libsieve.
In the discussion below the following macro-notations are used:

MATCH-TYPE
     This tag specifies the matching type to be used with the test. It
     can be one of the following:

    `:is'
          The `:is' match type describes an absolute match; if the
          contents of the first string are absolutely the same as the
          contents of the second string, they match. Only the string
          "frobnitzm" is the string "frobnitzm". The null key ":is" and
          only ":is" the null value.  This is the default match-type.

    `:contains'
          The `:contains' match type describes a substring match. If
          the value argument contains the key argument as a substring,
          the match is true.  For instance, the string "frobnitzm"
          contains "frob" and "nit", but not "fbm". The null key "" is
          contained in all values.

    `:matches'
          The `:matches' version specifies a wildcard match using the
          characters `*' and `?'. `*' matches zero or more characters,
          and `?' matches a single character. `?' and `*' may be
          escaped as `\\?' and `\\*' in strings to match against
          themselves. The first backslash escapes the second backslash;
          together, they escape the `*'.

    `:regex'
          The `:regex' version specifies a match using POSIX Extended
          Regular Expressions.

    `:value RELATION'
          The `:value' match type does a relational comparison between
          strings. Valid values for RELATION are:

         "eq"
               Equal

         "ne"
               Not Equal

         "gt"
               Greater Than

         "ge"
               Greater than or Equal

         "lt"
               Less Than

         "le"
               Less than or Equal

    `:count RELATION'
          This match type first determines the number of the specified
          entities (headers, addresses, etc.) in the message and does a
          relational comparison of the number of entities to the values
          specified in the test expression. The test expression must be
          a list of one element.

COMPARATOR
     A COMPARATOR syntax item is defined as follows:

          :comparator "COMPARATOR-NAME"
     It instructs sieve to use the given comparator with the test.  If
     COMPARATOR-NAME is not one of `i;octet', `i;ascii-casemap' it must
     be required prior to using it.  For example:

          require "comparator-i;ascii-numeric";

          if header :comparator "i;ascii-numeric" :is "X-Num" "10"
            {
              ...

ADDRESS-PART
     This syntax item is used when testing structured Internet
     addresses. It specifies which part of an address must be used in
     comparisons.  Exactly one of the following tags may be used:

    `:all'
          Use the whole address. This is the default.

    `:localpart'
          Use local part of the address.

    `:domain'
          Use domain part of the address.


   _Notice_, that MATCH-TYPE modifiers interact with comparators. Some
comparators are not suitable for matching with `:contains' or
`:matches'. If this occurs, sieve issues an appropriate error message.
For example, the statement:

     if header :matches :comparator "i;ascii-numeric"
   would result in the following error message:

     comparator `i;ascii-numeric' is incompatible with match type `:matches'
     in call to `header'

   GNU Sieve supports two kinds of tests. "Built-in tests" are defined
within the library and do not require any external files.  "External
tests" are loadable modules that can be linked in at run time using the
`require' statement (*note Require Statement::).

4.6.1 Built-in Tests
--------------------

 -- Test: false
     This test always evaluates to "false".

 -- Test: true
     This test always evaluates to "true".

 -- Test:  address [ADDRESS-PART] [COMPARATOR] [MATCH-TYPE]
          HEADER-NAMES KEY-LIST
     Tagged arguments:

    ADDRESS-PART
          Selects the address part to compare. Default is the whole
          email address (`:all').

    COMPARATOR
          Specifies the comparator to be used instead of the default
          `i;ascii-casemap'.

    MATCH-TYPE
          Specifies the match type to be used instead of the default
          `:is'.

     Required arguments:

    HEADER-NAMES
          A list of header names.

    KEY-LIST
          A list of address values.
     The `address' test matches Internet addresses in structured headers
     that contain addresses. It returns `true' if any header contains
     any key in the specified part of the address, as modified by
     COMPARATOR and MATCH-TYPE optional arguments.

     This test returns `true' if any combination of the HEADER-NAMES
     and KEY-LIST arguments match.

     The `address' primitive never acts on the phrase part of an email
     address, nor on comments within that address. Use the `header' test
     instead. It also never acts on group names, although it does act
     on the addresses within the group construct.

     Example:

          if address :is :all "from" "tim@example.com"
            {
               discard;
            }

 -- Test:  size [:over | :under] LIMIT(number)
     The `size' test deals with the size of a message. The required
     argument LIMIT represents the size of the message in bytes. It may
     be suffixed with the following quantifiers:

    `k'
    `K'
          The number is expressed in kilobytes.

    `m'
    `M'
          The number is expressed in megabytes.

    `g'
    `G'
          The number is expressed in gigabytes.

     If the tagged argument is `:over', and the size of the message is
     greater than NUMBER, the test is true; otherwise, it is false.

     If the argument is `:under', and the size of the message is less
     than the NUMBER, the test is true; otherwise, it is false.

     Otherwise, the test is true only if the size of the message equals
     exactly NUMBER. This is a GNU extension.

     The size of a message is defined to be the number of octets from
     the initial header until the last character in the message body.

 -- Test:  envelope [ADDRESS-PART] [COMPARATOR] [MATCH-TYPE]
          ENVELOPE-PART(string-list) KEY-LIST(string-list)
     Tagged arguments:

    ADDRESS-PART
          Selects the address part to compare. Default is the whole
          email address (`:all').

    COMPARATOR
          Specifies the comparator to be used instead of the default
          `i;ascii-casemap'.

    MATCH-TYPE
          Specifies the match type to be used instead of the default
          `:is'.
     Required arguments:

    ENVELOPE-PARTS
          A list of envelope parts to operate upon.

    KEY-LIST
          A list of address values.
     The `envelope' test is true if the specified part of the SMTP
     envelope matches the specified key.

     If the envelope-part strings is (case insensitive) `from', then
     matching occurs against the FROM address used in the `SMTP MAIL'
     command.

     _Notice_, that due to the limitations imposed by SMTP envelope
     structure the use of any other values in ENVELOPE-PARTS header is
     meaningless.

 -- Test:  exists HEADER-NAMES(string-list)
     Required arguments:

    HEADER-NAMES
          List of message header names.


     The `exists' test is `true' if the headers listed in HEADER-NAMES
     argument exist within the message. All of the headers must exist
     or the test is false.

     The following example throws out mail that doesn't have a From
     header and a Date header:

          if not exists ["From","Date"]
            {
               discard;
            }

 -- Test:  header [COMPARATOR] [MATCH-TYPE] [:mime]
          HEADER-NAMES(string-list) KEY-LIST(string-list)

     Tagged arguments:

    COMPARATOR
          Specifies the comparator to be used instead of the default
          `i;ascii-casemap'.

    MATCH-TYPE
          Specifies the match type to be used instead of the default
          `:is'.

    :mime
          This tag instructs `header' to search through the mime
          headers in multipart messages as well.



     Required arguments:

    HEADER-NAMES
          A list of header names.

    KEY-LIST
          A list of header values.


     The `header' test evaluates to true if any header name matches any
     key. The type of match is specified by the optional match argument,
     which defaults to ":is" if not explicitly given.

     The test returns `true' if any combination of the HEADER-NAMES and
     KEY-LIST arguments match.

     If a header listed in HEADER-NAMES exists, it contains the null
     key (`""'). However, if the named header is not present, it does
     not contain the null key. So if a message contained the header

          X-Caffeine: C8H10N4O2


     these tests on that header evaluate as follows:

          header :is ["X-Caffeine"] [""] => false
          header :contains ["X-Caffeine"] [""] => true

4.6.2 External Tests
--------------------

 -- Test:  numaddr [:over | :under] HEADER-NAMES(string-list)
          COUNT(number)


Synopsis
........

          require "test-numaddr";
          ...
          if numaddr ARGS
            {
              ...
            }

Description
...........

     This test is provided as an example of loadable extension tests.
You must use `require "test-numaddr"' statement before actually using
it.

     The `numaddr' test counts Internet addresses in structured headers
that contain addresses. It returns true if the total number of
addresses satisfies the requested relation.

     If the tagged argument is `:over' and the number of addresses is
greater than COUNT, the test is true; otherwise, it is false.

     If the tagged argument is `:under' and the number of addresses is
less than COUNT, the test is true; otherwise, it is false.

     If the tagged argument is not given, `:over' is assumed.

 -- Test:  spamd [:host TCP-HOST(string)] [:port TCP-PORT(number)]
          [:socket UNIX-SOCKET(string)] [:user NAME(string)] [:over |
          :under LIMIT(string)]
Synopsis
........

          require "test-spamd";
          ...
          if spamd ARGS
            {
              # This is spam
              ...
            }

Description
...........

     This test is an interface to SpamAssassin filter. It connects to
the `spamd' daemon using connection parameters specified by tagged
arguments `:host' and `:port' (if the daemon is listening on an INET
socket), or `:socket' (if the daemon is listening on a UNIX socket) and
returns true, if SpamAssassin qualifies the message as spam. Tagged
argument LIMIT alters the default behavior. Its value is a string
representation of a floating point number. If the tag `:over' is used,
then the test returns true if the spam score returned from SpamAssassin
is greater than LIMIT.  Otherwise, if `:under' is used, the test
returns true if the spam score is less than LIMIT. The comparison takes
into account three decimal digits.

     Tagged argument `:user' allows to select a specific user profile.
If it is not given, the user name is determined using the effective UID.

     Before returning, the `spamd' test adds the following headers to
the message:

    X-Spamd-Status
          `YES' or `NO', depending on whether the message is qualified
          as spam or ham.

    X-Spamd-Score
          Actual spam score value.

    X-Spamd-Threshold
          Spam score threshold, as configured in SpamAssassin settings.

    X-Spamd-Keywords
          Comma-separated list of keywords, describing the spam checks
          that succeeded for this message.

Example
.......

          request "test-spamd";

          if spamd :host 127.0.0.1 :port 3333
            {
               discard;
            }


 -- Test:  list [COMPARATOR] [MATCH-TYPE] [ :delim DELIMITERS(string) ]
          HEADERS(string-list) KEYS(string-list)
Synopsis
........

          require "test-list";
          if list ARGS
            {
               ...
            }

Description
...........

     The `list' test evaluates to true if any of HEADERS match any key
from KEYS. Each header is regarded as containing a list of keywords. By
default, comma is assumed as list separator. This can be overridden by
specifying the `:delim' tag, whose value is a string consisting of
valid list delimiter characters.

Example
.......

     This test can be used in conjunction with the `spamd' test
described above:

          require ["fileinto", "test-spamd", "test-list"];

          if spamd :host 127.0.0.1 :port 3333
            {
               if list :matches :delim " ,"
                       "X-Spamd-Keywords" [ "HTML_*", "FORGED_*" ]
                 {
                    fileinto "~/mail/spam";
                 }
               else
                 {
                    discard;
                 }
            }

 -- Test:  timestamp [:before | :after] HEADER(string) DATE(string)
Synopsis
........

          require "test-timestamp";

          if timestamp ARG
            {
               ...
            }

Description
...........

     The `timestamp' test compares the value of a structured date header
field (HEADER) with the given date (DATE).

     If the tagged argument is `:after' and the date from the header is
after the specified date the result is true, otherwise, if the header
date is before the given date, the result is false.

     If the tagged argument is `:before' and the date from the header is
before the specified date the result is true, otherwise, if the header
date is after the given date, the result is false.

     If no tagged argument is supplied, `:after' is assumed.

     Almost any date format is understood. *Note Date Input Formats::,
for a detailed information on date formats.

Example
.......

     The test below succeeds if the date in `X-Expire-Timestamp' header
is more than 5 days older than the current date:

          require "test-timestamp";

          if timestamp :before "X-Expire-Timestamp" "now - 5 days"
            {
               discard;
            }

4.7 Actions
===========

There are two groups of GNU Sieve actions: "built-in actions", which
are defined within the library, and "external actions", i.e.  loadable
modules that can be linked in at run time using the `require' statement
(*note Require Statement::).

4.7.1 Built-in Actions
----------------------

The GNU libsieve supports the following built-in actions:

   * stop

   * keep

   * discard

   * fileinto

   * reject

   * redirect

   Among them the first three actions do not need to be explicitly
required by a `require' statement, while the others do.

   These actions are described in detail below.

 -- Action: stop
     The `stop' action ends all processing. If no actions have been
     executed, then the `keep' action is taken.

 -- Action: keep
     The effect of this action is to preserve the current message in the
     mailbox. This action is executed if no other action has been
     executed.

 -- Action: discard
     `Discard' silently throws away the current message. No notification
     is returned to the sender, the message is deleted from the mailbox.

     Example:
          if header :contains ["from"] ["idiot@example.edu"]
            {
              discard;
            }

 -- Action: fileinto [:permissions MODE] FOLDER
     Required arguments:

    FOLDER
          A string representing the folder name

     Tagged arguments:

    `:permissions MODE'
          Specifies the permissions to use, if the mailbox is created.

     The `fileinto' action delivers the message into the specified
     folder. If the folder is local, it is created using permissions
     `0600', for regular files, and `0700' for directories. This
     default can be changed by using the `:permissions' tag. Its
     argument is a mode specification, similar to that used by `chmod'
     shell utility. It is a list of permissions settings separated by
     commas. Each setting begins with one of the following letters:

    g
          Set permissions for the users in the file group.

    o
          Set permissions for users not in the file's group.

     This letter must be followed by either `+' or `=' and the list of
     permissions to be set. This latter list is a string containing any
     one or both of the following characters:

    r
          Grant permission to read.

    w
          Grant permission to write.

     For example, the following instruction creates the mailbox
     `~/shared' which will be world readable and writable for the group:

            fileinto :permissions "g=rw,o=r" "~/shared"

     Notice that:

       1. The `:permissions' setting are affected by the current umask
          value.

       2. Only `r' and `w' permissions can be set, since other
          permissions do not seem to be useful for mailboxes. However,
          for mailboxes that have a directory structure (such as
          maildir and MH), any settings in `g' and `o' sets imply
          setting the executable bit.

       3. Owner's permissions cannot be set. The owner always has all
          permissions on the mailbox he created.

       4. The `:permissions' settings apply only to local mailboxes.
          They are ignored for remote mailboxes.


 -- Action: reject REASON
     The optional `reject' action refuses delivery of a message by
     sending back a message delivery notification to the sender. It
     resends the message to the sender, wrapping it in a "reject" form,
     noting that it was rejected by the recipient. The required
     argument REASON is a string specifying the reason for rejecting
     the message.

     Example:

     If the message contained
          Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST)
          From: coyote@desert.example.org
          To: roadrunner@acme.example.com
          Subject: I have a present for you

          I've got some great birdseed over here at my place.
          Want to buy it?


     and the user's script contained:

          if header :contains "from" "coyote@desert.example.org"
            {
              reject "I am not taking mail from you, and I don't want
                      your birdseed, either!";
            }
     then the original sender <coyote@desert.example.org> would receive
     the following notification:

          To: <coyote@desert.example.org>
          X-Authentication-Warning: roadrunner set sender using -f flag
          Content-Type: multipart/mixed; boundary=----- =_aaaaaaaaaa0
          MIME-Version: 1.0
          ----- =_aaaaaaaaaa0
          The original message was received at
          Tue, 1 Apr 1997 09:07:15 -0800 from
          coyote@desert.example.org.
          Message was refused by recipient's mail filtering program.
          Reason given was as follows:

          I am not taking mail from you, and I don't want your
          birdseed, either!

          ----- =_aaaaaaaaaa0
          Content-Type: message/delivery-status

          Reporting-UA: sieve; GNU Mailutils 0.1.3
          Arrival-Date: Tue, 1 Apr 1997 09:07:15 -0800
          Final-Recipient: RFC822; roadrunner@acme.example.com
          Action: deleted
          Disposition: automatic-action/MDN-sent-automatically;deleted
          Last-Attempt-Date: Tue, 1 Apr 1997 09:07:15 -0800

          ----- =_aaaaaaaaaa0
          Content-Type: message/rfc822

          From: coyote@desert.example.org
          To: roadrunner@acme.example.com
          Subject: I have a present for you

          I've got some great birdseed over here at my place.
          Want to buy it?
          ----- =_aaaaaaaaaa0

     If the REASON argument is rather long, the common approach is to
     use the combination of the `text:' and `#include' keywords, e.g.:

          if header :mime :matches "Content-Type"
                    [ "*application/msword;*", "*audio/x-midi*" ]
            {
              reject text:
          #include "nomsword.txt"
              .
              ;
            }


 -- Action: redirect ADDRESS
     The `redirect' action is used to send the message to another user
     at a supplied ADDRESS, as a mail forwarding feature does. This
     action makes no changes to the message body or existing headers,
     but it may add new headers. It also modifies the envelope
     recipient.

     The `redirect' command performs an MTA-style "forward" -- that is,
     what you get from a `.forward' file using `sendmail' under UNIX.
     The address on the SMTP envelope is replaced with the one on the
     `redirect' command and the message is sent back out. _Notice_,
     that it differs from the MUA-style forward, which creates a new
     message with a different sender and message ID, wrapping the old
     message in a new one.

4.7.2 External Actions
----------------------

     (_The information in this node may be obsolete or otherwise
     inaccurate._ This message will disappear, once this node revised.)

GNU Mailutils is shipped with a set of external Sieve actions. These
actions are compiled as loadable modules and must be required prior to
use (*note Require Statement::).

 -- Action:  moderator [:keep] [:address ADDRESS(string)] [:source
          SIEVE-FILE(string)]
Synopsis
........

          require "moderator"
          moderator ARGS;

Description
...........

     This action is a moderator robot for Mailman-driven mail archives.
A Mailman moderation request is a MIME message consisting of the
following three parts:

     N             Content-Type                Description
     ---------------------------------------------------------------------- 
     1             text/plain                  Introduction for the human
                                               reader.
     2             message/rfc822              Original submission.
     3             message/rfc822              Mailman control message.

     Replying to part 3 (keeping the subject intact) instructs Mailman
to discard the original submission.

     Replying to part 3 while adding an `Approved:' header with the list
password in it approves the submission.

     The `moderator' action spawns an inferior Sieve machine and
filters the original submission (part 2) through it. If the inferior
machine marks the message as deleted, the action replies to the control
message, thereby causing the submission to be discarded. The `From:'
address of the reply can be modified using `:address' tag. After
discarding the message, `moderator' marks it as deleted, unless it is
given `:keep' tag.

     The argument of `:source' tag, if given, specifies the Sieve
source file to be used on the message. If `:tag' is not present,
`moderator' will create and use a copy of the existing Sieve machine.

     The action checks the message structure: it will bail out if the
message does not have exactly 3 MIME parts, or if parts 2 and 3 are not
of `message/rfc822' type. It is the responsibility of the caller to
make sure the message is actually a valid Mailman moderation request
(see the example below).

Example
.......

          if allof(header :is "Sender" "mailman-bounces@gnu.org",
                   header :is "X-List-Administrivia" "yes")
            {
               moderator :source "~/.sieve/mailman.sv";
            }

 -- Action:  pipe [:envelope] COMMAND(string)
Synopsis
........

          require "pipe";
          if pipe ARGS
            {
               ...
            }

Description
...........

     The `pipe' action sends executes a command specified by its
argument and sends the entire message to its standard input. The
COMMAND argument supplies the command line.

     The envelope of the message is included, if the `:envelope' tag is
given.

Example
.......

     The example below uses the `maidag' utility (*note maidag::) to
forward the message to user `gray' on the machine `mail.gnu.org'.

          require "pipe";

          pipe "/usr/sbin/maidag --url smtp://gray@mail.gnu.org"

 -- Action:  vacation [:days NDAYS(number)] [:subject SUBJECT(string)]
          [:aliases ADDRLIST(string-list)] [:addresses
          NOREPLY-ADDRESS(string-list)] [:reply_regex EXPR(string)]
          [:reply_prefix PREFIX(string)] REPLY-TEXT(string)
Syntax
......

          require "vacation";
          vacation ARGS;

Description
...........

     The `vacation' action returns a message with REPLY-TEXT to the
sender. It is intended to inform the sender that the recipient is not
currently reading his mail.

     If the `:subject' tag is given, its argument sets the subject of
the message. Otherwise, the subject is formed by prefixing original
subject with `Re:', or PREFIX, given with the `:reply_prefix' tag.
Before prefixing, any original prefixes matching extended regular
expression EXPR (`:reply_regex' tag) are stripped from the subject
line. If `:reply_regex' is not specified, the default regexp is `^re:
*'.

     The `:aliases' tag instructs `vacation' to handle messages for any
address in ADDRLIST in the same manner as those received for the user's
principal email.

     Before processing, `vacation' compares the sender address with its
"address exclusion list". Elements of this list are extended
case-insensitive regular expressions. If the sender address matches any
of these expressions, the message will not be replied. The default
exclusion list is:

              .*-REQUEST@.*
              .*-RELAY@.*
              .*-OWNER@.*
              ^OWNER-.*
              ^postmaster@.*
              ^UUCP@.*
              ^MAILER@.*
              ^MAILER-DAEMON@.*

     New entries can be added to this list using `:addresses' tag.

     The `:days' tag sets the "reply interval". A reply is sent to each
sender once in NDAYS days. GNU Sieve keeps track of sender addresses
and dates in a DBM file `.vacation' stored in the user's home
directory. This tag is available only if Mailutils is compiled with DBM
support.

4.8 GNU Extensions
==================

This section summarizes the GNU extensions to the sieve language

  1. Multiline strings syntax

     GNU libsieve understands the following multiline string syntax:

          text:[-][DELIMITER]
          ....
          DELIMITER

     The meaning of optional flags is the same as in shell "here
     document" construct: the dash strips all leading tab characters
     from the string body, thus allowing it to be indented in a natural
     fashion; DELIMITER introduces the new end-of-text delimiter
     instead of the default dot. If DELIMITER starts with a backslash,
     no preprocessing will be performed within a string.

  2. Handling of the `require' statement.

        * According to the RFC an error must occur if a `require'
          appears after a command other than `require'. The GNU sieve
          library allows interspersing the `require' and other
          statements. The only requirement is that `require' must occur
          before a statement that is using the required capability
          (*note Require Statement::).

        * Prefixing the required capability with "test" requires the use
          of an extension test.

  3. `header' test

     The `header' takes an optional argument `:mime', meaning to scan
     the headers from each part of a multipart message.

  4. `size' test

     The `size' test allows to omit the optional argument
     (:over|:under). In this case exact equality is assumed.

  5. `envelope' test

     The only value that can be meaningfully used as the first required
     argument of an `envelope' test is `from'. This limitation may
     disappear from the subsequent releases.

  6. `fileinto' action

     The `fileinto' action allows to specify permissions on the mailbox,
     in case it is created (*note fileinto::).

  7. Match type optional argument.

     Along with the usual `:is', `:matches' and `contains' matching
     type, GNU sieve library understands `:regex' type. This matching
     type toggles POSIX Extended Regular Expression matching.

5 Reporting Bugs
****************

Email bug reports to <bug-mailutils@gnu.org>.

   As the purpose of bug reporting is to improve software, please be
sure to include maximum information when reporting a bug. The
information needed is:

   * Version of the package you are using.

   * Compilation options used when configuring the package.

   * Conditions under which the bug appears.

   The archives of bug-mailutils mailing list are available from
`http://mail.gnu.org/mailman/listinfo/bug-mailutils'.

6 Getting News About GNU Mailutils
**********************************

The two places to look for any news regarding GNU Mailutils are the
Mailutils homepage at `http://www.gnu.org/software/mailutils', and the
project page at `http://savannah.gnu.org/projects/mailutils'.

   The updated versions of this manual are available online from
`http://www.gnu.org/software/mailutils/manual'.

7 Acknowledgement
*****************

In no particular order,

   * Jakob Kaivo <jkaivo@ndn.net>,

   * Jeff Bailey <jbailey@gnu.org>,

   * Sean Perry <shaleh@debian.org>,

   * Thomas Fletcher <thomasf@qnx.com>,

   * Dave Inglis <dinglis@qnx.com>,

   * Brian Edmond <briane@qnx.com>,

   * Sam Roberts <sroberts@uniserve.com>,

   * Sergey Poznyakoff <gray@Mirddin.farlep.net>,

   * Franc,ois Pinard  <pinard@IRO.UMontreal.CA>.

   * Jordi Mallach <jordi@sindominio.net>

   * Wojciech Polak <polak@gnu.org>

Appendix A References
*********************

   * SMTP

        - `RFC 2821: Simple Mail Transfer Protocol'

        - `RFC 2368: The mailto URL scheme'

        - `RFC 2487: SMTP Service Extension for Secure SMTP over TLS'

   * POP3

        - `RFC 1939: Post Office Protocol - Version 3'

        - `RFC 1734: POP3 AUTHentication command'

        - `RFC 1957: Some Observations on Implementations of the Post
          Office Protocol (POP3)'

        - `RFC 2449: POP3 Extension Mechanism'

        - `RFC 2384: POP URL Scheme'

        - `RFC 2595: Using TLS with IMAP, POP3 and ACAP'

   * IMAP4

        - `RFC 2060: INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1'

        - `RFC 2088: IMAP4 non-synchronizing literals'

        - `RFC 2193: IMAP4 Mailbox Referrals'

        - `RFC 2221: IMAP4 Login Referrals'

        - `RFC 2342: IMAP4 Namespace'

        - `RFC 2192: IMAP URL Scheme'

        - `RFC 1731: IMAP4 Authentication Mechanisms'

        - `RFC 2245: Anonymous SASL Mechanism'

        - `RFC 2595: Using TLS with IMAP, POP3 and ACAP'

   * message formats

        - `RFC 2822: Internet Message Format'

        - `RFC 2045: Multipurpose Internet Mail Extensions (MIME) Part
          One: Format of Internet Message Bodies'

        - `RFC 2046: Multipurpose Internet Mail Extensions (MIME) Part
          Two: Media Types'

        - `RFC 2047: Multipurpose Internet Mail Extensions (MIME) Part
          Three: Message Header Extensions for Non-ASCII Text'

        - `RFC 2049: Multipurpose Internet Mail Extensions (MIME) Part
          Five: Conformance Criteria and Examples'

        - `RFC 2111: Content-ID and Message-ID Uniform Resource
          Locators'

   * miscellaneous related topics

        - `RFC 1738: Uniform Resource Locators (URL)'

        - `RFC 2298: An Extensible Message Format for Message
          Disposition Notifications'

        - `RFC 3028: Sieve: A Mail Filtering Language'

        - `RFC 3431: Sieve Extension: Relational Tests'

        - `Internet Email Protocols: A Developer's Guide, by Kevin
          Johnson'

Appendix B Date Input Formats
*****************************

First, a quote:

     Our units of temporal measurement, from seconds on up to months,
     are so complicated, asymmetrical and disjunctive so as to make
     coherent mental reckoning in time all but impossible. Indeed, had
     some tyrannical god contrived to enslave our minds to time, to
     make it all but impossible for us to escape subjection to sodden
     routines and unpleasant surprises, he could hardly have done
     better than handing down our present system.  It is like a set of
     trapezoidal building blocks, with no vertical or horizontal
     surfaces, like a language in which the simplest thought demands
     ornate constructions, useless particles and lengthy
     circumlocutions. Unlike the more successful patterns of language
     and science, which enable us to face experience boldly or at least
     level-headedly, our system of temporal calculation silently and
     persistently encourages our terror of time.

     ...  It is as though architects had to measure length in feet,
     width in meters and height in ells; as though basic instruction
     manuals demanded a knowledge of five different languages. It is no
     wonder then that we often look into our own immediate past or
     future, last Tuesday or a week from Sunday, with feelings of
     helpless confusion. ...

     -- Robert Grudin, `Time and the Art of Living'.

   This section describes the textual date representations that GNU
programs accept. These are the strings you, as a user, can supply as
arguments to the various programs. The C interface (via the `get_date'
function) is not described here.

B.1 General date syntax
=======================

A "date" is a string, possibly empty, containing many items separated
by whitespace. The whitespace may be omitted when no ambiguity arises.
The empty string means the beginning of today (i.e., midnight). Order
of the items is immaterial. A date string may contain many flavors of
items:

   * calendar date items

   * time of day items

   * time zone items

   * day of the week items

   * relative items

   * pure numbers.

We describe each of these item types in turn, below.

   A few ordinal numbers may be written out in words in some contexts.
This is most useful for specifying day of the week items or relative
items (see below). Among the most commonly used ordinal numbers, the
word `last' stands for -1, `this' stands for 0, and `first' and `next'
both stand for 1. Because the word `second' stands for the unit of time
there is no way to write the ordinal number 2, but for convenience
`third' stands for 3, `fourth' for 4, `fifth' for 5, `sixth' for 6,
`seventh' for 7, `eighth' for 8, `ninth' for 9, `tenth' for 10,
`eleventh' for 11 and `twelfth' for 12.

   When a month is written this way, it is still considered to be
written numerically, instead of being "spelled in full"; this changes
the allowed strings.

   In the current implementation, only English is supported for words
and abbreviations like `AM', `DST', `EST', `first', `January',
`Sunday', `tomorrow', and `year'.

   The output of the `date' command is not always acceptable as a date
string, not only because of the language problem, but also because
there is no standard meaning for time zone items like `IST'. When using
`date' to generate a date string intended to be parsed later, specify a
date format that is independent of language and that does not use time
zone items other than `UTC' and `Z'. Here are some ways to do this:

     $ LC_ALL=C TZ=UTC0 date
     Mon Mar  1 00:21:42 UTC 2004
     $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
     2004-03-01 00:21:42Z
     $ date --iso-8601=ns | tr T ' '  # --iso-8601 is a GNU extension.
     2004-02-29 16:21:42,692722128-0800
     $ date --rfc-2822  # a GNU extension
     Sun, 29 Feb 2004 16:21:42 -0800
     $ date +'%Y-%m-%d %H:%M:%S %z'  # %z is a GNU extension.
     2004-02-29 16:21:42 -0800
     $ date +'@%s.%N'  # %s and %N are GNU extensions.
     @1078100502.692722128

   Alphabetic case is completely ignored in dates. Comments may be
introduced between round parentheses, as long as included parentheses
are properly nested. Hyphens not followed by a digit are currently
ignored. Leading zeros on numbers are ignored.

   Invalid dates like `2005-02-29' or times like `24:00' are rejected.
In the typical case of a host that does not support leap seconds, a
time like `23:59:60' is rejected even if it corresponds to a valid leap
second.

B.2 Calendar date items
=======================

A "calendar date item" specifies a day of the year. It is specified
differently, depending on whether the month is specified numerically or
literally. All these strings specify the same calendar date:

     1972-09-24     # ISO 8601.
     72-9-24        # Assume 19xx for 69 through 99,
                    # 20xx for 00 through 68.
     72-09-24       # Leading zeros are ignored.
     9/24/72        # Common U.S. writing.
     24 September 1972
     24 Sept 72     # September has a special abbreviation.
     24 Sep 72      # Three-letter abbreviations always allowed.
     Sep 24, 1972
     24-sep-72
     24sep72

   The year can also be omitted. In this case, the last specified year
is used, or the current year if none. For example:

     9/24
     sep 24

   Here are the rules.

   For numeric months, the ISO 8601 format `YEAR-MONTH-DAY' is allowed,
where YEAR is any positive number, MONTH is a number between 01 and 12,
and DAY is a number between 01 and 31. A leading zero must be present
if a number is less than ten. If YEAR is 68 or smaller, then 2000 is
added to it; otherwise, if YEAR is less than 100, then 1900 is added to
it. The construct `MONTH/DAY/YEAR', popular in the United States, is
accepted. Also `MONTH/DAY', omitting the year.

   Literal months may be spelled out in full: `January', `February',
`March', `April', `May', `June', `July', `August', `September',
`October', `November' or `December'. Literal months may be abbreviated
to their first three letters, possibly followed by an abbreviating dot.
It is also permitted to write `Sept' instead of `September'.

   When months are written literally, the calendar date may be given as
any of the following:

     DAY MONTH YEAR
     DAY MONTH
     MONTH DAY YEAR
     DAY-MONTH-YEAR

   Or, omitting the year:

     MONTH DAY

B.3 Time of day items
=====================

A "time of day item" in date strings specifies the time on a given day.
Here are some examples, all of which represent the same time:

     20:02:00.000000
     20:02
     8:02pm
     20:02-0500      # In EST (U.S. Eastern Standard Time).

   More generally, the time of day may be given as
`HOUR:MINUTE:SECOND', where HOUR is a number between 0 and 23, MINUTE
is a number between 0 and 59, and SECOND is a number between 0 and 59
possibly followed by `.' or `,' and a fraction containing one or more
digits.  Alternatively, `:SECOND' can be omitted, in which case it is
taken to be zero. On the rare hosts that support leap seconds, SECOND
may be 60.

   If the time is followed by `am' or `pm' (or `a.m.' or `p.m.'), HOUR
is restricted to run from 1 to 12, and `:MINUTE' may be omitted (taken
to be zero). `am' indicates the first half of the day, `pm' indicates
the second half of the day. In this notation, 12 is the predecessor of
1: midnight is `12am' while noon is `12pm'.  (This is the zero-oriented
interpretation of `12am' and `12pm', as opposed to the old tradition
derived from Latin which uses `12m' for noon and `12pm' for midnight.)

   The time may alternatively be followed by a time zone correction,
expressed as `SHHMM', where S is `+' or `-', HH is a number of zone
hours and MM is a number of zone minutes.  The zone minutes term, MM,
may be omitted, in which case the one- or two-digit correction is
interpreted as a number of hours.  You can also separate HH from MM
with a colon.  When a time zone correction is given this way, it forces
interpretation of the time relative to Coordinated Universal Time
(UTC), overriding any previous specification for the time zone or the
local time zone. For example, `+0530' and `+05:30' both stand for the
time zone 5.5 hours ahead of UTC (e.g., India).  This is the best way to
specify a time zone correction by fractional parts of an hour.  The
maximum zone correction is 24 hours.

   Either `am'/`pm' or a time zone correction may be specified, but not
both.

B.4 Time zone items
===================

A "time zone item" specifies an international time zone, indicated by a
small set of letters, e.g., `UTC' or `Z' for Coordinated Universal
Time. Any included periods are ignored. By following a
non-daylight-saving time zone by the string `DST' in a separate word
(that is, separated by some white space), the corresponding daylight
saving time zone may be specified.  Alternatively, a
non-daylight-saving time zone can be followed by a time zone
correction, to add the two values. This is normally done only for
`UTC'; for example, `UTC+05:30' is equivalent to `+05:30'.

   Time zone items other than `UTC' and `Z' are obsolescent and are not
recommended, because they are ambiguous; for example, `EST' has a
different meaning in Australia than in the United States. Instead, it's
better to use unambiguous numeric time zone corrections like `-0500', as
described in the previous section.

   If neither a time zone item nor a time zone correction is supplied,
time stamps are interpreted using the rules of the default time zone
(*note Specifying time zone rules::).

B.5 Day of week items
=====================

The explicit mention of a day of the week will forward the date (only
if necessary) to reach that day of the week in the future.

   Days of the week may be spelled out in full: `Sunday', `Monday',
`Tuesday', `Wednesday', `Thursday', `Friday' or `Saturday'. Days may be
abbreviated to their first three letters, optionally followed by a
period. The special abbreviations `Tues' for `Tuesday', `Wednes' for
`Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed.

   A number may precede a day of the week item to move forward
supplementary weeks. It is best used in expression like `third monday'.
In this context, `last DAY' or `next DAY' is also acceptable; they move
one week before or after the day that DAY by itself would represent.

   A comma following a day of the week item is ignored.

B.6 Relative items in date strings
==================================

"Relative items" adjust a date (or the current date if none) forward or
backward. The effects of relative items accumulate. Here are some
examples:

     1 year
     1 year ago
     3 years
     2 days

   The unit of time displacement may be selected by the string `year'
or `month' for moving by whole years or months. These are fuzzy units,
as years and months are not all of equal duration. More precise units
are `fortnight' which is worth 14 days, `week' worth 7 days, `day'
worth 24 hours, `hour' worth 60 minutes, `minute' or `min' worth 60
seconds, and `second' or `sec' worth one second. An `s' suffix on these
units is accepted and ignored.

   The unit of time may be preceded by a multiplier, given as an
optionally signed number. Unsigned numbers are taken as positively
signed. No number at all implies 1 for a multiplier. Following a
relative item by the string `ago' is equivalent to preceding the unit
by a multiplier with value -1.

   The string `tomorrow' is worth one day in the future (equivalent to
`day'), the string `yesterday' is worth one day in the past (equivalent
to `day ago').

   The strings `now' or `today' are relative items corresponding to
zero-valued time displacement, these strings come from the fact a
zero-valued time displacement represents the current time when not
otherwise changed by previous items. They may be used to stress other
items, like in `12:00 today'. The string `this' also has the meaning of
a zero-valued time displacement, but is preferred in date strings like
`this thursday'.

   When a relative item causes the resulting date to cross a boundary
where the clocks were adjusted, typically for daylight saving time, the
resulting date and time are adjusted accordingly.

   The fuzz in units can cause problems with relative items. For
example, `2003-07-31 -1 month' might evaluate to 2003-07-01, because
2003-06-31 is an invalid date. To determine the previous month more
reliably, you can ask for the month before the 15th of the current
month. For example:

     $ date -R
     Thu, 31 Jul 2003 13:02:39 -0700
     $ date --date='-1 month' +'Last month was %B?'
     Last month was July?
     $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
     Last month was June!

   Also, take care when manipulating dates around clock changes such as
daylight saving leaps. In a few cases these have added or subtracted as
much as 24 hours from the clock, so it is often wise to adopt universal
time by setting the `TZ' environment variable to `UTC0' before
embarking on calendrical calculations.

B.7 Pure numbers in date strings
================================

The precise interpretation of a pure decimal number depends on the
context in the date string.

   If the decimal number is of the form YYYYMMDD and no other calendar
date item (*note Calendar date items::) appears before it in the date
string, then YYYY is read as the year, MM as the month number and DD as
the day of the month, for the specified calendar date.

   If the decimal number is of the form HHMM and no other time of day
item appears before it in the date string, then HH is read as the hour
of the day and MM as the minute of the hour, for the specified time of
day. MM can also be omitted.

   If both a calendar date and a time of day appear to the left of a
number in the date string, but no relative item, then the number
overrides the year.

B.8 Seconds since the Epoch
===========================

If you precede a number with `@', it represents an internal time stamp
as a count of seconds. The number can contain an internal decimal point
(either `.' or `,'); any excess precision not supported by the internal
representation is truncated toward minus infinity. Such a number cannot
be combined with any other date item, as it specifies a complete time
stamp.

   Internally, computer times are represented as a count of seconds
since an epoch--a well-defined point of time. On GNU and POSIX systems,
the epoch is 1970-01-01 00:00:00 UTC, so `@0' represents this time,
`@1' represents 1970-01-01 00:00:01 UTC, and so forth. GNU and most
other POSIX-compliant systems support such times as an extension to
POSIX, using negative counts, so that `@-1' represents 1969-12-31
23:59:59 UTC.

   Traditional Unix systems count seconds with 32-bit two's-complement
integers and can represent times from 1901-12-13 20:45:52 through
2038-01-19 03:14:07 UTC. More modern systems use 64-bit counts of
seconds with nanosecond subcounts, and can represent all the times in
the known lifetime of the universe to a resolution of 1 nanosecond.

   On most hosts, these counts ignore the presence of leap seconds.
For example, on most hosts `@915148799' represents 1998-12-31 23:59:59
UTC, `@915148800' represents 1999-01-01 00:00:00 UTC, and there is no
way to represent the intervening leap second 1998-12-31 23:59:60 UTC.

B.9 Specifying time zone rules
==============================

Normally, dates are interpreted using the rules of the current time
zone, which in turn are specified by the `TZ' environment variable, or
by a system default if `TZ' is not set. To specify a different set of
default time zone rules that apply just to one date, start the date
with a string of the form `TZ="RULE"'. The two quote characters (`"')
must be present in the date, and any quotes or backslashes within RULE
must be escaped by a backslash.

   For example, with the GNU `date' command you can answer the question
"What time is it in New York when a Paris clock shows 6:30am on October
31, 2004?" by using a date beginning with `TZ="Europe/Paris"' as shown
in the following shell transcript:

     $ export TZ="America/New_York"
     $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
     Sun Oct 31 01:30:00 EDT 2004

   In this example, the `--date' operand begins with its own `TZ'
setting, so the rest of that operand is processed according to
`Europe/Paris' rules, treating the string `2004-10-31 06:30' as if it
were in Paris. However, since the output of the `date' command is
processed according to the overall time zone rules, it uses New York
time.  (Paris was normally six hours ahead of New York in 2004, but
this example refers to a brief Halloween period when the gap was five
hours.)

   A `TZ' value is a rule that typically names a location in the `tz'
database (http://www.twinsun.com/tz/tz-link.htm).  A recent catalog of
location names appears in the TWiki Date and Time Gateway
(http://twiki.org/cgi-bin/xtra/tzdate). A few non-GNU hosts require a
colon before a location name in a `TZ' setting, e.g.,
`TZ=":America/New_York"'.

   The `tz' database includes a wide variety of locations ranging from
`Arctic/Longyearbyen' to `Antarctica/South_Pole', but if you are at sea
and have your own private time zone, or if you are using a non-GNU host
that does not support the `tz' database, you may need to use a POSIX
rule instead. Simple POSIX rules like `UTC0' specify a time zone without
daylight saving time; other rules can specify simple daylight saving
regimes. *Note Specifying the Time Zone with `TZ': (libc)TZ Variable.

B.10 Authors of `get_date'
==========================

`get_date' was originally implemented by Steven M. Bellovin
(<smb@research.att.com>) while at the University of North Carolina at
Chapel Hill. The code was later tweaked by a couple of people on
Usenet, then completely overhauled by Rich $alz (<rsalz@bbn.com>) and
Jim Berets (<jberets@bbn.com>) in August, 1990. Various revisions for
the GNU system were made by David MacKenzie, Jim Meyering, Paul Eggert
and others.

   This chapter was originally produced by Franc,ois Pinard
(<pinard@iro.umontreal.ca>) from the `getdate.y' source code, and then
edited by K. Berry (<kb@cs.umb.edu>).

Appendix C Configuring Help Summary
***********************************

Running `PROG --help' displays the short usage summary for PROG utility
(*note Common Options::). This summary is organized by "groups" of
semantically close options. The options within each group are printed
in the following order: a short option, eventually followed by a list
of corresponding long option names, followed by a short description of
the option. For example, here is an excerpt from the actual `sieve
--help' output:

  -c, --compile-only         Compile script and exit
  -d, --debug[=FLAGS]        Debug flags
  -e, --email=ADDRESS        Override user email address

   The exact visual representation of the help output is configurable
via `ARGP_HELP_FMT' environment variable. The value of this variable is
a comma-separated list of "format variable" assignments. There are two
kinds of format variables. An "offset variable" keeps the offset of
some part of help output text from the leftmost column on the screen. A
"boolean" variable is a flag that toggles some output feature on or
off. Depending on the type of the corresponding variable, there are two
kinds of assignments:

Offset assignment
     The assignment to an offset variable has the following syntax:

          VARIABLE=VALUE

     where VARIABLE is the variable name, and VALUE is a numeric value
     to be assigned to the variable.

Boolean assignment
     To assign `true' value to a variable, simply put this variable
     name. To assign `false' value, prefix the variable name with
     `no-'. For example:

          # Assign `true' value:
          dup-args
          # Assign `false' value:
          no-dup-args

   Following variables are declared:

 -- Help Output: boolean dup-args
     If true, arguments for an option are shown with both short and long
     options, even when a given option has both forms, for example:

            -e ADDRESS, --email=ADDRESS        Override user email address

     If false, then if an option has both short and long forms, the
     argument is only shown with the long one, for example:

            -e, --email=ADDRESS        Override user email address

     and a message indicating that the argument is applicable to both
     forms is printed below the options. This message can be disabled
     using `dup-args-note' (see below).

     The default is false.

 -- Help Output: boolean dup-args-note
     If this variable is true, which is the default, the following
     notice is displayed at the end of the help output:

          Mandatory or optional arguments to long options are also
          mandatory or optional for any corresponding short options.

     Setting `no-dup-args-note' inhibits this message. Normally, only
     one of variables `dup-args' or `dup-args-note' should be set.

 -- Help Output: offset short-opt-col
     Column in which short options start. Default is 2.

          $ sieve --help|grep ADDRESS
            -e, --email=ADDRESS        Override user email address
          $ ARGP_HELP_FMT=short-opt-col=6 sieve --help|grep ARCHIVE
                -e, --email=ADDRESS        Override user email address

 -- Help Output: offset long-opt-col
     Column in which long options start. Default is 6. For example:

          $ sieve --help|grep ADDRESS
            -e, --email=ADDRESS        Override user email address
          $ ARGP_HELP_FMT=long-opt-col=16 sieve --help|grep ADDRESS
            -e,           --email=ADDRESS        Override user email address

 -- Help Output: offset doc-opt-col
     Column in which "doc options" start. A doc option isn't actually
     an option, but rather an arbitrary piece of documentation that is
     displayed in much the same manner as the options. For example, in
     the output of `folder --help':

     Usage: folder [OPTION...] [action] [msg]
     GNU MH folder
       Actions are:
           --list                 List the contents of the folder stack
       ...

     the string `Actions are:' is a doc option. Thus, if you set
     `ARGP_HELP_FMT=doc-opt-col=6' the above part of the help output
     will look as follows:

     Usage: folder [OPTION...] [action] [msg]
     GNU MH folder
           Actions are:
           --list                 List the contents of the folder stack
       ...

 -- Help Output: offset opt-doc-col
     Column in which option description starts. Default is 29.

          $ sieve --help|grep ADDRESS
            -e, --email=ADDRESS        Override user email address
          $ ARGP_HELP_FMT=opt-doc-col=19 sieve --help|grep ADDRESS
            -e, --email=ADDRESS   Override user email address
          $ ARGP_HELP_FMT=opt-doc-col=9 sieve --help|grep -i ADDRESS
            -e, --email=ADDRESS
                   Override user email address

     Notice, that the description starts on a separate line if
     `opt-doc-col' value is too small.

 -- Help Output: offset header-col
     Column in which "group headers" are printed. A group header is a
     descriptive text preceding an option group. For example, in the
     following text:

      Sieve options
       -I, --includedir=DIR       Append directory DIR to the
                                  list of include directories
      the text `Sieve options' is a group header.

     The default value is 1.

 -- Help Output: offset usage-indent
     Indentation of wrapped usage lines. Affects `--usage' output.
     Default is 12.

 -- Help Output: offset rmargin
     Right margin of the text output. Used for wrapping.

Appendix D GNU Free Documentation License
*****************************************

                      Version 1.2, November 2002

     Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
     51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     functional and useful document "free" in the sense of freedom: to
     assure everyone the effective freedom to copy and redistribute it,
     with or without modifying it, either commercially or
     noncommercially.  Secondarily, this License preserves for the
     author and publisher a way to get credit for their work, while not
     being considered responsible for modifications made by others.

     This License is a kind of "copyleft", which means that derivative
     works of the document must themselves be free in the same sense. It
     complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does. But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book. We
     recommend this License principally for works whose purpose is
     instruction or reference.

  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work, in any medium,
     that contains a notice placed by the copyright holder saying it
     can be distributed under the terms of this License. Such a notice
     grants a world-wide, royalty-free license, unlimited in duration,
     to use that work under the conditions stated herein. The
     "Document", below, refers to any such manual or work. Any member
     of the public is a licensee, and is addressed as "you". You accept
     the license if you copy, modify or distribute the work in a way
     requiring permission under copyright law.

     A "Modified Version" of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A "Secondary Section" is a named appendix or a front-matter section
     of the Document that deals exclusively with the relationship of the
     publishers or authors of the Document to the Document's overall
     subject (or to related matters) and contains nothing that could
     fall directly within that overall subject.  (Thus, if the Document
     is in part a textbook of mathematics, a Secondary Section may not
     explain any mathematics.)  The relationship could be a matter of
     historical connection with the subject or with related matters, or
     of legal, commercial, philosophical, ethical or political position
     regarding them.

     The "Invariant Sections" are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in
     the notice that says that the Document is released under this
     License. If a section does not fit the above definition of
     Secondary then it is not allowed to be designated as Invariant.
     The Document may contain zero Invariant Sections. If the Document
     does not identify any Invariant Sections then there are none.

     The "Cover Texts" are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License. A
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
     be at most 25 words.

     A "Transparent" copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, that is suitable for revising the document
     straightforwardly with generic text editors or (for images
     composed of pixels) generic paint programs or (for drawings) some
     widely available drawing editor, and that is suitable for input to
     text formatters or for automatic translation to a variety of
     formats suitable for input to text formatters. A copy made in an
     otherwise Transparent file format whose markup, or absence of
     markup, has been arranged to thwart or discourage subsequent
     modification by readers is not Transparent.  An image format is
     not Transparent if used for any substantial amount of text. A copy
     that is not "Transparent" is called "Opaque".

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and
     standard-conforming simple HTML, PostScript or PDF designed for
     human modification. Examples of transparent image formats include
     PNG, XCF and JPG. Opaque formats include proprietary formats that
     can be read and edited only by proprietary word processors, SGML or
     XML for which the DTD and/or processing tools are not generally
     available, and the machine-generated HTML, PostScript or PDF
     produced by some word processors for output purposes only.

     The "Title Page" means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page. For
     works in formats which do not have any title page as such, "Title
     Page" means the text near the most prominent appearance of the
     work's title, preceding the beginning of the body of the text.

     A section "Entitled XYZ" means a named subunit of the Document
     whose title either is precisely XYZ or contains XYZ in parentheses
     following text that translates XYZ in another language.  (Here XYZ
     stands for a specific section name mentioned below, such as
     "Acknowledgements", "Dedications", "Endorsements", or "History".)
     To "Preserve the Title" of such a section when you modify the
     Document means that it remains a section "Entitled XYZ" according
     to this definition.

     The Document may include Warranty Disclaimers next to the notice
     which states that this License applies to the Document. These
     Warranty Disclaimers are considered to be included by reference in
     this License, but only as regards disclaiming warranties: any other
     implication that these Warranty Disclaimers may have is void and
     has no effect on the meaning of this License.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License. You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute. However,
     you may accept compensation in exchange for copies. If you
     distribute a large enough number of copies you must also follow
     the conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies (or copies in media that commonly
     have printed covers) of the Document, numbering more than 100, and
     the Document's license notice requires Cover Texts, you must
     enclose the copies in covers that carry, clearly and legibly, all
     these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover. Both covers must also clearly
     and legibly identify you as the publisher of these copies. The
     front cover must present the full title with all words of the
     title equally prominent and visible. You may add other material on
     the covers in addition.  Copying with changes limited to the
     covers, as long as they preserve the title of the Document and
     satisfy these conditions, can be treated as verbatim copying in
     other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a
     machine-readable Transparent copy along with each Opaque copy, or
     state in or with each Opaque copy a computer-network location from
     which the general network-using public has access to download
     using public-standard network protocols a complete Transparent
     copy of the Document, free of added material.  If you use the
     latter option, you must take reasonably prudent steps, when you
     begin distribution of Opaque copies in quantity, to ensure that
     this Transparent copy will remain thus accessible at the stated
     location until at least one year after the last time you
     distribute an Opaque copy (directly or through your agents or
     retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of
     copies, to give them a chance to provide you with an updated
     version of the Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with
     the Modified Version filling the role of the Document, thus
     licensing distribution and modification of the Modified Version to
     whoever possesses a copy of it. In addition, you must do these
     things in the Modified Version:

       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of
          previous versions (which should, if there were any, be listed
          in the History section of the Document). You may use the same
          title as a previous version if the original publisher of that
          version gives permission.

       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has fewer than five), unless they release you
          from this requirement.

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document's
          license notice.

       H. Include an unaltered copy of this License.

       I. Preserve the section Entitled "History", Preserve its Title,
          and add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on
          the Title Page. If there is no section Entitled "History" in
          the Document, create one stating the title, year, authors,
          and publisher of the Document as given on its Title Page,
          then add an item describing the Modified Version as stated in
          the previous sentence.

       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on. These may be placed in the
          "History" section.  You may omit a network location for a
          work that was published at least four years before the
          Document itself, or if the original publisher of the version
          it refers to gives permission.

       K. For any section Entitled "Acknowledgements" or "Dedications",
          Preserve the Title of the section, and preserve in the
          section all the substance and tone of each of the contributor
          acknowledgements and/or dedications given therein.

       L. Preserve all the Invariant Sections of the Document,
          unaltered in their text and in their titles. Section numbers
          or the equivalent are not considered part of the section
          titles.

       M. Delete any section Entitled "Endorsements". Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section to be Entitled
          "Endorsements" or to conflict in title with any Invariant
          Section.

       O. Preserve any Warranty Disclaimers.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option
     designate some or all of these sections as invariant. To do this,
     add their titles to the list of Invariant Sections in the Modified
     Version's license notice.  These titles must be distinct from any
     other section titles.

     You may add a section Entitled "Endorsements", provided it contains
     nothing but endorsements of your Modified Version by various
     parties--for example, statements of peer review or that the text
     has been approved by an organization as the authoritative
     definition of a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end
     of the list of Cover Texts in the Modified Version. Only one
     passage of Front-Cover Text and one of Back-Cover Text may be
     added by (or through arrangements made by) any one entity. If the
     Document already includes a cover text for the same cover,
     previously added by you or by arrangement made by the same entity
     you are acting on behalf of, you may not add another; but you may
     replace the old one, on explicit permission from the previous
     publisher that added the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination
     all of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice, and that you preserve all
     their Warranty Disclaimers.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy. If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections Entitled
     "History" in the various original documents, forming one section
     Entitled "History"; likewise combine any sections Entitled
     "Acknowledgements", and any sections Entitled "Dedications". You
     must delete all sections Entitled "Endorsements."

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the
     documents in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow
     this License in all other respects regarding verbatim copying of
     that document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of
     a storage or distribution medium, is called an "aggregate" if the
     copyright resulting from the compilation is not used to limit the
     legal rights of the compilation's users beyond what the individual
     works permit.  When the Document is included an aggregate, this
     License does not apply to the other works in the aggregate which
     are not themselves derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one half
     of the entire aggregate, the Document's Cover Texts may be placed
     on covers that bracket the Document within the aggregate, or the
     electronic equivalent of covers if the Document is in electronic
     form.  Otherwise they must appear on printed covers that bracket
     the whole aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections. You may include a
     translation of this License, and all the license notices in the
     Document, and any Warranty Disclaimers, provided that you also
     include the original English version of this License and the
     original versions of those notices and disclaimers. In case of a
     disagreement between the translation and the original version of
     this License or a notice or disclaimer, the original version will
     prevail.

     If a section in the Document is Entitled "Acknowledgements",
     "Dedications", or "History", the requirement (section 4) to
     Preserve its Title (section 1) will typically require changing the
     actual title.

  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided for under this License. Any other
     attempt to copy, modify, sublicense or distribute the Document is
     void, and will automatically terminate your rights under this
     License. However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

 10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time. Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns. See
     `http://www.gnu.org/copyleft/'.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License "or any later version" applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation. If the
     Document does not specify a version number of this License, you
     may choose any version ever published (not as a draft) by the Free
     Software Foundation.

D.1 ADDENDUM: How to use this License for your documents
========================================================

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

       Copyright (C)  YEAR  YOUR NAME.
       Permission is granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version 1.2
       or any later version published by the Free Software Foundation;
       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
       A copy of the license is included in the section entitled ``GNU
       Free Documentation License''.

   If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:

         with the Invariant Sections being LIST THEIR TITLES, with
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
         being LIST.

   If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.

Function Index
**************

This is an alphabetical list of all Mailutils functions.

acl:                                           See 2.2.11.2.
                                                            (line  1548)
address:                                       See 4.6.1.   (line 11047)
ago in date strings:                           See B.6.     (line 12199)
allow:                                         See 2.2.8.   (line  1255)
allow-biffrc:                                  See 2.16.2.1.
                                                            (line  5800)
allow-syslog-priority:                         See 2.2.10.  (line  1382)
allow-table:                                   See 2.2.10.  (line  1376)
am in date strings:                            See B.3.     (line 12113)
auth:                                          See 2.2.15.  (line  1843)
authentication:                                See 2.2.12.  (line  1648)
authorization:                                 See 2.2.12.  (line  1614)
bulletin-db:                                   See 2.14.4.  (line  5425)
bulletin-source:                               See 2.14.4.  (line  5421)
clear-include-path:                            See 2.8.1.   (line  4052)
clear-library-path:                            See 2.8.1.   (line  4047)
concat:                                        See 2.17.1.1.
                                                            (line  6035)
config-file, --config-file option, described:  See 2.2.     (line   475)
config-file, --config-file option, introduced: See 2.1.2.   (line   423)
config-help, --config-help option, described:  See 2.2.     (line   520)
config-help, --config-help option, introduced: See 2.1.2.   (line   426)
config-lint, --config-lint option, described:  See 2.2.     (line   513)
config-lint, --config-lint option, introduced: See 2.1.2.   (line   429)
config-verbose, --config-verbose option, described:See 2.2. (line   484)
config-verbose, --config-verbose option, introduced:See 2.1.2.
                                                            (line   432)
create-home-dir:                               See 2.15.2.  (line  5589)
daemon:                                        See 2.2.10.  (line  1371)
day in date strings:                           See B.6.     (line 12191)
db:                                            See 2.2.17.  (line  1961)
debug <1>:                                     See 2.13.2.  (line  5219)
debug <2>:                                     See 2.11.2.  (line  5030)
debug <3>:                                     See 2.10.9.  (line  4844)
debug:                                         See 2.8.1.   (line  4079)
decode:                                        See 2.17.1.1.
                                                            (line  5953)
delete-expired:                                See 2.14.4.  (line  5406)
deny:                                          See 2.2.8.   (line  1258)
deny-syslog-priority:                          See 2.2.10.  (line  1385)
deny-table:                                    See 2.2.10.  (line  1379)
directory:                                     See 2.2.15.  (line  1792)
discard:                                       See 4.7.1.   (line 11436)
emacs:                                         See 2.6.1.   (line  3692)
email:                                         See 2.8.1.   (line  4090)
enable:                                        See 2.2.10.  (line  1368)
envelope:                                      See 4.6.1.   (line 11119)
ex-multiple-delivery-success <1>:              See 2.11.2.  (line  4999)
ex-multiple-delivery-success:                  See 2.10.9.  (line  4821)
ex-quota-tempfail <1>:                         See 2.11.2.  (line  5003)
ex-quota-tempfail:                             See 2.10.9.  (line  4825)
exec:                                          See 2.2.8.   (line  1319)
exists:                                        See 4.6.1.   (line 11151)
expire:                                        See 2.14.4.  (line  5402)
expire-timeout:                                See 2.2.6.   (line  1126)
external-locker:                               See 2.2.6.   (line  1130)
facility:                                      See 2.2.3.   (line   738)
false:                                         See 4.6.1.   (line 11040)
fileinto:                                      See 4.7.1.   (line 11446)
first in date strings:                         See B.1.     (line 11993)
flags:                                         See 2.2.6.   (line  1096)
folder <1>:                                    See 2.7.2.   (line  3907)
folder:                                        See 2.2.5.   (line  1059)
foreground:                                    See 2.2.11.1.
                                                            (line  1457)
form-feeds:                                    See 2.7.2.   (line  3904)
fortnight in date strings:                     See B.6.     (line 12191)
forward-file:                                  See 2.10.9.  (line  4862)
forward-file-checks:                           See 2.10.9.  (line  4865)
get_date:                                      See Appendix B.
                                                            (line 11939)
getpwnam:                                      See 2.2.15.  (line  1853)
getpwuid:                                      See 2.2.15.  (line  1877)
group:                                         See 2.10.9.  (line  4872)
guile-filter <1>:                              See 2.11.2.  (line  5026)
guile-filter:                                  See 2.10.9.  (line  4840)
header <1>:                                    See 4.6.1.   (line 11171)
header:                                        See 2.7.2.   (line  3892)
help, --help option, described:                See 2.1.2.   (line   360)
home-dir-mode:                                 See 2.15.2.  (line  5593)
host:                                          See 2.2.17.  (line  1950)
hour in date strings:                          See B.6.     (line 12191)
id-fields:                                     See 2.15.2.  (line  5653)
ident-encrypt-only:                            See 2.15.2.  (line  5650)
ident-keyfile:                                 See 2.15.2.  (line  5646)
ifexec:                                        See 2.2.8.   (line  1261)
in_reply_to:                                   See 2.17.1.1.
                                                            (line  6044)
include-path:                                  See 2.8.1.   (line  4063)
int:                                           See 3.1.9.   (line  7698)
interface:                                     See 2.2.17.  (line  1933)
isreply:                                       See 2.17.1.1.
                                                            (line  6000)
keep:                                          See 4.7.1.   (line 11431)
keep-going:                                    See 2.8.1.   (line  4069)
last DAY:                                      See B.5.     (line 12172)
last in date strings:                          See B.1.     (line 11993)
level:                                         See 2.2.4.   (line   835)
library-path:                                  See 2.8.1.   (line  4057)
line-info <1>:                                 See 2.8.1.   (line  4086)
line-info:                                     See 2.2.4.   (line   880)
list:                                          See 4.6.2.   (line 11314)
listen:                                        See 2.10.9.  (line  4875)
lmtp:                                          See 2.10.9.  (line  4869)
log:                                           See 2.2.8.   (line  1270)
login-delay:                                   See 2.14.4.  (line  5413)
login-disabled:                                See 2.15.2.  (line  5586)
mail-spool:                                    See 2.2.5.   (line   911)
mailbox-pattern:                               See 2.2.5.   (line   921)
mailbox-type:                                  See 2.2.5.   (line  1053)
max-children:                                  See 2.2.11.1.
                                                            (line  1462)
max-lines:                                     See 2.16.2.1.
                                                            (line  5797)
max-requests:                                  See 2.16.2.2.
                                                            (line  5810)
mbox-url:                                      See 2.8.1.   (line  4073)
message-id-header <1>:                         See 2.11.2.  (line  5022)
message-id-header:                             See 2.10.9.  (line  4836)
metamail:                                      See 2.13.2.  (line  5226)
midnight in date strings:                      See B.3.     (line 12113)
mimetypes:                                     See 2.13.2.  (line  5223)
minute in date strings:                        See B.6.     (line 12191)
mode:                                          See 2.2.11.1.
                                                            (line  1429)
moderator:                                     See 4.7.2.   (line 11608)
month in date strings:                         See B.6.     (line 12191)
mu-address-get-comments:                       See 3.3.1.   (line  9483)
mu-address-get-count:                          See 3.3.1.   (line  9499)
mu-address-get-domain:                         See 3.3.1.   (line  9491)
mu-address-get-email:                          See 3.3.1.   (line  9487)
mu-address-get-local:                          See 3.3.1.   (line  9495)
mu-address-get-personal:                       See 3.3.1.   (line  9479)
mu-body-read-line:                             See 3.3.3.   (line  9655)
mu-body-write:                                 See 3.3.3.   (line  9658)
mu-closelog:                                   See 3.3.5.   (line  9696)
mu-folder-directory:                           See 3.3.2.   (line  9515)
mu-logger:                                     See 3.3.5.   (line  9693)
mu-mail-directory:                             See 3.3.2.   (line  9511)
mu-mailbox-append-message:                     See 3.3.2.   (line  9553)
mu-mailbox-close:                              See 3.3.2.   (line  9532)
mu-mailbox-expunge:                            See 3.3.2.   (line  9550)
mu-mailbox-get-message:                        See 3.3.2.   (line  9544)
mu-mailbox-get-port:                           See 3.3.2.   (line  9538)
mu-mailbox-get-url:                            See 3.3.2.   (line  9535)
mu-mailbox-messages-count:                     See 3.3.2.   (line  9547)
mu-mailbox-open:                               See 3.3.2.   (line  9519)
mu-message-copy:                               See 3.3.3.   (line  9563)
mu-message-create:                             See 3.3.3.   (line  9559)
mu-message-delete:                             See 3.3.3.   (line  9603)
mu-message-destroy:                            See 3.3.3.   (line  9567)
mu-message-get-body:                           See 3.3.3.   (line  9632)
mu-message-get-flag:                           See 3.3.3.   (line  9608)
mu-message-get-header:                         See 3.3.3.   (line  9587)
mu-message-get-header-fields:                  See 3.3.3.   (line  9591)
mu-message-get-lines:                          See 3.3.3.   (line  9579)
mu-message-get-num-parts:                      See 3.3.3.   (line  9638)
mu-message-get-part:                           See 3.3.3.   (line  9642)
mu-message-get-port:                           See 3.3.3.   (line  9622)
mu-message-get-sender:                         See 3.3.3.   (line  9583)
mu-message-get-size:                           See 3.3.3.   (line  9576)
mu-message-get-uid:                            See 3.3.3.   (line  9651)
mu-message-get-user-flag:                      See 3.3.3.   (line  9615)
mu-message-multipart?:                         See 3.3.3.   (line  9635)
mu-message-send:                               See 3.3.3.   (line  9645)
mu-message-set-flag:                           See 3.3.3.   (line  9611)
mu-message-set-header:                         See 3.3.3.   (line  9570)
mu-message-set-header-fields:                  See 3.3.3.   (line  9596)
mu-message-set-user-flag:                      See 3.3.3.   (line  9618)
mu-mime-add-part:                              See 3.3.4.   (line  9679)
mu-mime-create:                                See 3.3.4.   (line  9664)
mu-mime-get-message:                           See 3.3.4.   (line  9682)
mu-mime-get-num-parts:                         See 3.3.4.   (line  9673)
mu-mime-get-part:                              See 3.3.4.   (line  9676)
mu-mime-multipart?:                            See 3.3.4.   (line  9669)
mu-openlog:                                    See 3.3.5.   (line  9689)
mu-register-format:                            See 3.3.6.   (line  9702)
mu-strerror:                                   See 3.3.6.   (line  9720)
mu-username->email:                            See 3.3.1.   (line  9503)
mu_address_aget_domain:                        See 3.1.12.  (line  8323)
mu_address_aget_email:                         See 3.1.12.  (line  8306)
mu_address_aget_local_part:                    See 3.1.12.  (line  8320)
mu_address_aget_personal:                      See 3.1.12.  (line  8326)
mu_address_contains_email:                     See 3.1.12.  (line  8379)
mu_address_create:                             See 3.1.12.  (line  8168)
mu_address_createv:                            See 3.1.12.  (line  8184)
mu_address_destroy:                            See 3.1.12.  (line  8201)
mu_address_format_string:                      See 3.1.12.  (line  8384)
mu_address_get_comments:                       See 3.1.12.  (line  8276)
mu_address_get_count:                          See 3.1.12.  (line  8361)
mu_address_get_domain:                         See 3.1.12.  (line  8239)
mu_address_get_email:                          See 3.1.12.  (line  8208)
mu_address_get_email_count:                    See 3.1.12.  (line  8373)
mu_address_get_group_count:                    See 3.1.12.  (line  8370)
mu_address_get_local_part:                     See 3.1.12.  (line  8226)
mu_address_get_nth:                            See 3.1.12.  (line  8205)
mu_address_get_personal:                       See 3.1.12.  (line  8252)
mu_address_get_route:                          See 3.1.12.  (line  8290)
mu_address_get_unix_mailbox_count:             See 3.1.12.  (line  8376)
mu_address_is_group:                           See 3.1.12.  (line  8329)
mu_address_t:                                  See 3.1.12.  (line  8161)
mu_address_to_string:                          See 3.1.12.  (line  8348)
mu_address_union:                              See 3.1.12.  (line  8381)
mu_attribute_clear_modified:                   See 3.1.8.   (line  7531)
mu_attribute_copy:                             See 3.1.8.   (line  7602)
mu_attribute_create:                           See 3.1.8.   (line  7523)
mu_attribute_destroy:                          See 3.1.8.   (line  7525)
mu_attribute_get_flags:                        See 3.1.8.   (line  7583)
mu_attribute_get_owner:                        See 3.1.8.   (line  7527)
mu_attribute_is_answered:                      See 3.1.8.   (line  7539)
mu_attribute_is_deleted:                       See 3.1.8.   (line  7543)
mu_attribute_is_draft:                         See 3.1.8.   (line  7545)
mu_attribute_is_equal:                         See 3.1.8.   (line  7599)
mu_attribute_is_flagged:                       See 3.1.8.   (line  7541)
mu_attribute_is_modified:                      See 3.1.8.   (line  7529)
mu_attribute_is_read:                          See 3.1.8.   (line  7549)
mu_attribute_is_recent:                        See 3.1.8.   (line  7547)
mu_attribute_is_seen:                          See 3.1.8.   (line  7537)
mu_attribute_is_userflag:                      See 3.1.8.   (line  7535)
mu_attribute_set_answered:                     See 3.1.8.   (line  7555)
mu_attribute_set_deleted:                      See 3.1.8.   (line  7559)
mu_attribute_set_draft:                        See 3.1.8.   (line  7561)
mu_attribute_set_flagged:                      See 3.1.8.   (line  7557)
mu_attribute_set_flags:                        See 3.1.8.   (line  7585)
mu_attribute_set_get_flags:                    See 3.1.8.   (line  7596)
mu_attribute_set_modified:                     See 3.1.8.   (line  7533)
mu_attribute_set_read:                         See 3.1.8.   (line  7565)
mu_attribute_set_recent:                       See 3.1.8.   (line  7563)
mu_attribute_set_seen:                         See 3.1.8.   (line  7553)
mu_attribute_set_set_flags:                    See 3.1.8.   (line  7590)
mu_attribute_set_unset_flags:                  See 3.1.8.   (line  7593)
mu_attribute_set_userflag:                     See 3.1.8.   (line  7551)
mu_attribute_to_string:                        See 3.1.8.   (line  7605)
mu_attribute_unset_answered:                   See 3.1.8.   (line  7571)
mu_attribute_unset_deleted:                    See 3.1.8.   (line  7575)
mu_attribute_unset_draft:                      See 3.1.8.   (line  7577)
mu_attribute_unset_flagged:                    See 3.1.8.   (line  7573)
mu_attribute_unset_flags:                      See 3.1.8.   (line  7587)
mu_attribute_unset_read:                       See 3.1.8.   (line  7581)
mu_attribute_unset_recent:                     See 3.1.8.   (line  7579)
mu_attribute_unset_seen:                       See 3.1.8.   (line  7569)
mu_attribute_unset_userflag:                   See 3.1.8.   (line  7567)
mu_auth_data:                                  See 3.2.1.   (line  9264)
mu_auth_data_alloc:                            See 3.2.3.   (line  9317)
mu_auth_data_free:                             See 3.2.3.   (line  9321)
mu_auth_fp:                                    See 3.2.1.   (line  9226)
mu_auth_init:                                  See 3.2.2.   (line  9301)
mu_auth_module:                                See 3.2.1.   (line  9283)
mu_auth_nosupport:                             See 3.2.5.   (line  9363)
MU_AUTH_REGISTER_ALL_MODULES:                  See 3.2.2.   (line  9307)
mu_auth_register_module:                       See 3.2.3.   (line  9325)
mu_auth_runlist:                               See 3.2.4.   (line  9332)
mu_authenticate:                               See 3.2.4.   (line  9355)
mu_authority_authenticate:                     See 3.1.11.  (line  8059)
mu_authority_create:                           See 3.1.11.  (line  8048)
mu_authority_create_null:                      See 3.1.11.  (line  8065)
mu_authority_destroy:                          See 3.1.11.  (line  8050)
mu_authority_get_owner:                        See 3.1.11.  (line  8052)
mu_authority_get_ticket:                       See 3.1.11.  (line  8057)
mu_authority_set_authenticate:                 See 3.1.11.  (line  8062)
mu_authority_set_ticket:                       See 3.1.11.  (line  8054)
mu_body_clear_modified:                        See 3.1.7.   (line  7497)
mu_body_create:                                See 3.1.7.   (line  7487)
mu_body_destroy:                               See 3.1.7.   (line  7490)
mu_body_get_filename:                          See 3.1.7.   (line  7505)
mu_body_get_owner:                             See 3.1.7.   (line  7493)
mu_body_get_stream:                            See 3.1.7.   (line  7499)
mu_body_is_modified:                           See 3.1.7.   (line  7495)
mu_body_lines:                                 See 3.1.7.   (line  7512)
mu_body_set_lines:                             See 3.1.7.   (line  7515)
mu_body_set_size:                              See 3.1.7.   (line  7510)
mu_body_set_stream:                            See 3.1.7.   (line  7502)
mu_body_size:                                  See 3.1.7.   (line  7507)
mu_decoder_stream_create:                      See 3.1.9.   (line  7663)
mu_encoder_stream_create:                      See 3.1.9.   (line  7660)
mu_envelope_create:                            See 3.1.5.   (line  7221)
mu_envelope_date:                              See 3.1.5.   (line  7243)
mu_envelope_destroy:                           See 3.1.5.   (line  7224)
mu_envelope_get_owner:                         See 3.1.5.   (line  7227)
mu_envelope_sender:                            See 3.1.5.   (line  7230)
mu_envelope_set_date:                          See 3.1.5.   (line  7248)
mu_envelope_set_sender:                        See 3.1.5.   (line  7236)
mu_file_stream_create:                         See 3.1.9.   (line  7648)
mu_filter_prog_stream_create:                  See 3.1.9.   (line  7674)
mu_folder_close:                               See 3.1.1.   (line  6618)
mu_folder_create:                              See 3.1.1.   (line  6612)
mu_folder_delete:                              See 3.1.1.   (line  6620)
mu_folder_destroy:                             See 3.1.1.   (line  6614)
mu_folder_get_authority:                       See 3.1.1.   (line  6650)
mu_folder_get_debug:                           See 3.1.1.   (line  6645)
mu_folder_get_observable:                      See 3.1.1.   (line  6641)
mu_folder_get_stream:                          See 3.1.1.   (line  6636)
mu_folder_get_url:                             See 3.1.1.   (line  6654)
mu_folder_has_debug:                           See 3.1.1.   (line  6643)
mu_folder_list:                                See 3.1.1.   (line  6631)
mu_folder_lsub:                                See 3.1.1.   (line  6634)
mu_folder_open:                                See 3.1.1.   (line  6616)
mu_folder_rename:                              See 3.1.1.   (line  6623)
mu_folder_set_authority:                       See 3.1.1.   (line  6652)
mu_folder_set_debug:                           See 3.1.1.   (line  6647)
mu_folder_set_stream:                          See 3.1.1.   (line  6638)
mu_folder_set_url:                             See 3.1.1.   (line  6656)
mu_folder_subscribe:                           See 3.1.1.   (line  6625)
mu_folder_unsubscribe:                         See 3.1.1.   (line  6628)
mu_get_auth_by_name:                           See 3.2.4.   (line  9346)
mu_get_auth_by_uid:                            See 3.2.4.   (line  9350)
mu_header_aget_field_name:                     See 3.1.6.   (line  7441)
mu_header_aget_field_value:                    See 3.1.6.   (line  7438)
mu_header_aget_field_value_unfold:             See 3.1.6.   (line  7453)
mu_header_aget_value:                          See 3.1.6.   (line  7416)
mu_header_aget_value_unfold:                   See 3.1.6.   (line  7447)
mu_header_clear_modified:                      See 3.1.6.   (line  7275)
mu_header_create:                              See 3.1.6.   (line  7264)
mu_header_destroy:                             See 3.1.6.   (line  7268)
mu_header_get_address:                         See 3.1.6.   (line  7420)
mu_header_get_field_count:                     See 3.1.6.   (line  7429)
mu_header_get_field_name:                      See 3.1.6.   (line  7435)
mu_header_get_field_value:                     See 3.1.6.   (line  7432)
mu_header_get_field_value_unfold:              See 3.1.6.   (line  7450)
mu_header_get_owner:                           See 3.1.6.   (line  7271)
mu_header_get_stream:                          See 3.1.6.   (line  7423)
mu_header_get_value:                           See 3.1.6.   (line  7411)
mu_header_get_value_unfold:                    See 3.1.6.   (line  7444)
mu_header_is_modified:                         See 3.1.6.   (line  7273)
mu_header_lines:                               See 3.1.6.   (line  7457)
mu_header_set_fill:                            See 3.1.6.   (line  7479)
mu_header_set_get_fvalue:                      See 3.1.6.   (line  7469)
mu_header_set_get_value:                       See 3.1.6.   (line  7465)
mu_header_set_lines:                           See 3.1.6.   (line  7475)
mu_header_set_set_value:                       See 3.1.6.   (line  7461)
mu_header_set_size:                            See 3.1.6.   (line  7472)
mu_header_set_stream:                          See 3.1.6.   (line  7426)
mu_header_set_value:                           See 3.1.6.   (line  7278)
mu_header_size:                                See 3.1.6.   (line  7455)
mu_iterator_advance:                           See 3.1.10.  (line  7987)
mu_iterator_attach:                            See 3.1.10.  (line  7981)
mu_iterator_create:                            See 3.1.10.  (line  7965)
mu_iterator_current:                           See 3.1.10.  (line  7976)
mu_iterator_destroy:                           See 3.1.10.  (line  7970)
mu_iterator_detach:                            See 3.1.10.  (line  7984)
mu_iterator_dup:                               See 3.1.10.  (line  7968)
mu_iterator_first:                             See 3.1.10.  (line  7972)
mu_iterator_is_done:                           See 3.1.10.  (line  7978)
mu_iterator_next:                              See 3.1.10.  (line  7974)
mu_iterator_set_curitem_p:                     See 3.1.10.  (line  8008)
mu_iterator_set_destroy:                       See 3.1.10.  (line  8005)
mu_iterator_set_dup:                           See 3.1.10.  (line  8002)
mu_iterator_set_finished_p:                    See 3.1.10.  (line  7999)
mu_iterator_set_first:                         See 3.1.10.  (line  7990)
mu_iterator_set_getitem:                       See 3.1.10.  (line  7996)
mu_iterator_set_next:                          See 3.1.10.  (line  7993)
mu_locker_create:                              See 3.1.13.  (line  8522)
mu_locker_destroy:                             See 3.1.13.  (line  8524)
mu_locker_get_expire_time:                     See 3.1.13.  (line  8541)
mu_locker_get_external:                        See 3.1.13.  (line  8547)
mu_locker_get_flags:                           See 3.1.13.  (line  8539)
mu_locker_get_retries:                         See 3.1.13.  (line  8543)
mu_locker_get_retry_sleep:                     See 3.1.13.  (line  8545)
mu_locker_lock:                                See 3.1.13.  (line  8549)
mu_locker_remove_lock:                         See 3.1.13.  (line  8555)
mu_locker_set_default_expire_timeout:          See 3.1.13.  (line  8515)
mu_locker_set_default_external_program:        See 3.1.13.  (line  8517)
mu_locker_set_default_flags:                   See 3.1.13.  (line  8509)
mu_locker_set_default_retry_count:             See 3.1.13.  (line  8513)
mu_locker_set_default_retry_timeout:           See 3.1.13.  (line  8511)
mu_locker_set_expire_time:                     See 3.1.13.  (line  8530)
mu_locker_set_external:                        See 3.1.13.  (line  8537)
mu_locker_set_flags:                           See 3.1.13.  (line  8528)
mu_locker_set_retries:                         See 3.1.13.  (line  8532)
mu_locker_set_retry_sleep:                     See 3.1.13.  (line  8534)
mu_locker_touchlock:                           See 3.1.13.  (line  8551)
mu_locker_unlock:                              See 3.1.13.  (line  8553)
mu_mailbox_append_message:                     See 3.1.2.   (line  6788)
mu_mailbox_close:                              See 3.1.2.   (line  6734)
mu_mailbox_create:                             See 3.1.2.   (line  6687)
mu_mailbox_create_default:                     See 3.1.2.   (line  6706)
mu_mailbox_destroy:                            See 3.1.2.   (line  6711)
mu_mailbox_expunge:                            See 3.1.2.   (line  6823)
mu_mailbox_flush:                              See 3.1.2.   (line  6742)
mu_mailbox_get_debug:                          See 3.1.2.   (line  6912)
mu_mailbox_get_folder:                         See 3.1.2.   (line  6745)
mu_mailbox_get_locker:                         See 3.1.2.   (line  6875)
mu_mailbox_get_message:                        See 3.1.2.   (line  6775)
mu_mailbox_get_observable:                     See 3.1.2.   (line  6924)
mu_mailbox_get_property:                       See 3.1.2.   (line  6893)
mu_mailbox_get_size:                           See 3.1.2.   (line  6834)
mu_mailbox_get_stream:                         See 3.1.2.   (line  6857)
mu_mailbox_get_url:                            See 3.1.2.   (line  6901)
mu_mailbox_has_debug:                          See 3.1.2.   (line  6909)
mu_mailbox_is_updated:                         See 3.1.2.   (line  6842)
mu_mailbox_lock:                               See 3.1.2.   (line  6935)
mu_mailbox_message_unseen:                     See 3.1.2.   (line  6815)
mu_mailbox_messages_count:                     See 3.1.2.   (line  6797)
mu_mailbox_messages_recent:                    See 3.1.2.   (line  6806)
mu_mailbox_open:                               See 3.1.2.   (line  6714)
mu_mailbox_save_attributes:                    See 3.1.2.   (line  6831)
mu_mailbox_scan:                               See 3.1.2.   (line  6845)
mu_mailbox_set_debug:                          See 3.1.2.   (line  6921)
mu_mailbox_set_folder:                         See 3.1.2.   (line  6754)
mu_mailbox_set_locker:                         See 3.1.2.   (line  6884)
mu_mailbox_set_stream:                         See 3.1.2.   (line  6866)
mu_mailbox_t:                                  See 3.1.2.   (line  6664)
mu_mailbox_uidnext:                            See 3.1.2.   (line  6766)
mu_mailbox_uidvalidity:                        See 3.1.2.   (line  6757)
mu_mailbox_unlock:                             See 3.1.2.   (line  6937)
mu_mailcap_create:                             See 3.1.16.  (line  9118)
mu_mailcap_destroy:                            See 3.1.16.  (line  9125)
mu_mailcap_entries_count:                      See 3.1.16.  (line  9129)
mu_mailcap_entry_copiousoutput:                See 3.1.16.  (line  9208)
mu_mailcap_entry_fields_count:                 See 3.1.16.  (line  9141)
mu_mailcap_entry_get_compose:                  See 3.1.16.  (line  9161)
mu_mailcap_entry_get_composetyped:             See 3.1.16.  (line  9165)
mu_mailcap_entry_get_description:              See 3.1.16.  (line  9189)
mu_mailcap_entry_get_edit:                     See 3.1.16.  (line  9170)
mu_mailcap_entry_get_field:                    See 3.1.16.  (line  9155)
mu_mailcap_entry_get_nametemplate:             See 3.1.16.  (line  9194)
mu_mailcap_entry_get_notes:                    See 3.1.16.  (line  9199)
mu_mailcap_entry_get_test:                     See 3.1.16.  (line  9180)
mu_mailcap_entry_get_textualnewlines:          See 3.1.16.  (line  9175)
mu_mailcap_entry_get_typefield:                See 3.1.16.  (line  9149)
mu_mailcap_entry_get_value:                    See 3.1.16.  (line  9158)
mu_mailcap_entry_get_viewcommand:              See 3.1.16.  (line  9152)
mu_mailcap_entry_get_x11bitmap:                See 3.1.16.  (line  9184)
mu_mailcap_entry_needsterminal:                See 3.1.16.  (line  9203)
mu_mailcap_get_entry:                          See 3.1.16.  (line  9137)
mu_mailcap_t:                                  See 3.1.16.  (line  9014)
mu_mailer_check_from:                          See 3.1.3.   (line  6984)
mu_mailer_check_to:                            See 3.1.3.   (line  6986)
mu_mailer_close:                               See 3.1.3.   (line  6951)
mu_mailer_create:                              See 3.1.3.   (line  6945)
mu_mailer_destroy:                             See 3.1.3.   (line  6947)
mu_mailer_get_debug:                           See 3.1.3.   (line  6976)
mu_mailer_get_observable:                      See 3.1.3.   (line  6980)
mu_mailer_get_property:                        See 3.1.3.   (line  6970)
mu_mailer_get_stream:                          See 3.1.3.   (line  6972)
mu_mailer_get_url:                             See 3.1.3.   (line  6982)
mu_mailer_open:                                See 3.1.3.   (line  6949)
mu_mailer_send_message:                        See 3.1.3.   (line  6954)
mu_mailer_set_debug:                           See 3.1.3.   (line  6978)
mu_mailer_set_stream:                          See 3.1.3.   (line  6974)
mu_mapfile_stream_create:                      See 3.1.9.   (line  7654)
mu_memory_stream_create:                       See 3.1.9.   (line  7657)
mu_message_aget_attachment_name:               See 3.1.4.   (line  7210)
mu_message_clear_modified:                     See 3.1.4.   (line  7108)
mu_message_create:                             See 3.1.4.   (line  7096)
mu_message_create_attachment:                  See 3.1.4.   (line  7195)
mu_message_create_copy:                        See 3.1.4.   (line  7102)
mu_message_destroy:                            See 3.1.4.   (line  7098)
mu_message_encapsulate:                        See 3.1.4.   (line  7201)
mu_message_get_attachment_name:                See 3.1.4.   (line  7207)
mu_message_get_attribute:                      See 3.1.4.   (line  7144)
mu_message_get_body:                           See 3.1.4.   (line  7132)
mu_message_get_envelope:                       See 3.1.4.   (line  7119)
mu_message_get_header:                         See 3.1.4.   (line  7125)
mu_message_get_mailbox:                        See 3.1.4.   (line  7111)
mu_message_get_num_parts:                      See 3.1.4.   (line  7169)
mu_message_get_observable:                     See 3.1.4.   (line  7150)
mu_message_get_owner:                          See 3.1.4.   (line  7104)
mu_message_get_part:                           See 3.1.4.   (line  7175)
mu_message_get_stream:                         See 3.1.4.   (line  7138)
mu_message_get_uid:                            See 3.1.4.   (line  7188)
mu_message_get_uidl:                           See 3.1.4.   (line  7182)
mu_message_is_modified:                        See 3.1.4.   (line  7106)
mu_message_is_multipart:                       See 3.1.4.   (line  7152)
mu_message_lines:                              See 3.1.4.   (line  7163)
mu_message_ref:                                See 3.1.4.   (line  7116)
mu_message_save_attachment:                    See 3.1.4.   (line  7198)
mu_message_save_to_mailbox:                    See 3.1.4.   (line  7213)
mu_message_set_attribute:                      See 3.1.4.   (line  7147)
mu_message_set_body:                           See 3.1.4.   (line  7135)
mu_message_set_envelope:                       See 3.1.4.   (line  7122)
mu_message_set_get_num_parts:                  See 3.1.4.   (line  7172)
mu_message_set_get_part:                       See 3.1.4.   (line  7179)
mu_message_set_header:                         See 3.1.4.   (line  7129)
mu_message_set_is_multipart:                   See 3.1.4.   (line  7156)
mu_message_set_lines:                          See 3.1.4.   (line  7166)
mu_message_set_mailbox:                        See 3.1.4.   (line  7114)
mu_message_set_size:                           See 3.1.4.   (line  7161)
mu_message_set_stream:                         See 3.1.4.   (line  7141)
mu_message_set_uid:                            See 3.1.4.   (line  7191)
mu_message_set_uidl:                           See 3.1.4.   (line  7186)
mu_message_size:                               See 3.1.4.   (line  7158)
mu_message_unencapsulate:                      See 3.1.4.   (line  7204)
mu_parse822_addr_spec:                         See 3.1.15.  (line  8938)
mu_parse822_address:                           See 3.1.15.  (line  8929)
mu_parse822_address_list:                      See 3.1.15.  (line  8920)
mu_parse822_atom:                              See 3.1.15.  (line  8902)
mu_parse822_comment:                           See 3.1.15.  (line  8899)
mu_parse822_d_text:                            See 3.1.15.  (line  8917)
mu_parse822_date:                              See 3.1.15.  (line  8974)
mu_parse822_date_time:                         See 3.1.15.  (line  8980)
mu_parse822_day:                               See 3.1.15.  (line  8971)
mu_parse822_digits:                            See 3.1.15.  (line  8893)
mu_parse822_domain:                            See 3.1.15.  (line  8947)
mu_parse822_domain_literal:                    See 3.1.15.  (line  8956)
mu_parse822_domain_ref:                        See 3.1.15.  (line  8953)
mu_parse822_field_body:                        See 3.1.15.  (line  8965)
mu_parse822_field_name:                        See 3.1.15.  (line  8968)
mu_parse822_group:                             See 3.1.15.  (line  8926)
mu_parse822_is_atom_char:                      See 3.1.15.  (line  8872)
mu_parse822_is_char:                           See 3.1.15.  (line  8858)
mu_parse822_is_ctl:                            See 3.1.15.  (line  8862)
mu_parse822_is_d_text:                         See 3.1.15.  (line  8876)
mu_parse822_is_digit:                          See 3.1.15.  (line  8860)
mu_parse822_is_htab:                           See 3.1.15.  (line  8866)
mu_parse822_is_lwsp_char:                      See 3.1.15.  (line  8868)
mu_parse822_is_q_text:                         See 3.1.15.  (line  8874)
mu_parse822_is_smtp_q:                         See 3.1.15.  (line  8878)
mu_parse822_is_space:                          See 3.1.15.  (line  8864)
mu_parse822_is_special:                        See 3.1.15.  (line  8870)
mu_parse822_local_part:                        See 3.1.15.  (line  8944)
mu_parse822_mail_box:                          See 3.1.15.  (line  8923)
mu_parse822_phrase:                            See 3.1.15.  (line  8914)
mu_parse822_quote_local_part:                  See 3.1.15.  (line  8962)
mu_parse822_quote_string:                      See 3.1.15.  (line  8959)
mu_parse822_quoted_pair:                       See 3.1.15.  (line  8905)
mu_parse822_quoted_string:                     See 3.1.15.  (line  8908)
mu_parse822_route:                             See 3.1.15.  (line  8935)
mu_parse822_route_addr:                        See 3.1.15.  (line  8932)
mu_parse822_skip_comments:                     See 3.1.15.  (line  8888)
mu_parse822_skip_crlf:                         See 3.1.15.  (line  8880)
mu_parse822_skip_lwsp:                         See 3.1.15.  (line  8885)
mu_parse822_skip_lwsp_char:                    See 3.1.15.  (line  8883)
mu_parse822_skip_nl:                           See 3.1.15.  (line  8890)
mu_parse822_special:                           See 3.1.15.  (line  8896)
mu_parse822_sub_domain:                        See 3.1.15.  (line  8950)
mu_parse822_time:                              See 3.1.15.  (line  8977)
mu_parse822_unix_mbox:                         See 3.1.15.  (line  8941)
mu_parse822_word:                              See 3.1.15.  (line  8911)
mu_prog_stream_create:                         See 3.1.9.   (line  7671)
mu_sieve_abort:                                See 3.4.3.   (line 10248)
mu_sieve_action_log_t:                         See 3.4.1.   (line  9968)
mu_sieve_action_lookup:                        See 3.4.4.   (line 10260)
mu_sieve_comparator_t:                         See 3.4.1.   (line 10009)
mu_sieve_compile:                              See 3.4.6.   (line 10326)
mu_sieve_data_type:                            See 3.4.1.   (line  9811)
mu_sieve_debug:                                See 3.4.3.   (line 10239)
mu_sieve_destructor_t:                         See 3.4.1.   (line 10025)
mu_sieve_disass:                               See 3.4.6.   (line 10339)
mu_sieve_error:                                See 3.4.3.   (line 10234)
mu_sieve_get_daemon_email:                     See 3.4.2.   (line 10133)
mu_sieve_get_data:                             See 3.4.2.   (line 10106)
mu_sieve_get_debug_level:                      See 3.4.2.   (line 10119)
mu_sieve_get_locus:                            See 3.4.2.   (line 10129)
mu_sieve_get_mailer:                           See 3.4.2.   (line 10125)
mu_sieve_get_message:                          See 3.4.2.   (line 10111)
mu_sieve_get_message_num:                      See 3.4.2.   (line 10114)
mu_sieve_get_ticket:                           See 3.4.2.   (line 10122)
mu_sieve_handler_t:                            See 3.4.1.   (line  9920)
mu_sieve_is_dry_run:                           See 3.4.2.   (line 10219)
mu_sieve_load_ext:                             See 3.4.4.   (line 10284)
mu_sieve_locus_t:                              See 3.4.1.   (line  9910)
mu_sieve_log_action:                           See 3.4.3.   (line 10244)
mu_sieve_machine_add_destructor:               See 3.4.2.   (line 10078)
mu_sieve_machine_destroy:                      See 3.4.2.   (line 10071)
mu_sieve_machine_init:                         See 3.4.2.   (line 10064)
mu_sieve_mailbox:                              See 3.4.6.   (line 10330)
mu_sieve_malloc:                               See 3.4.5.   (line 10294)
mu_sieve_message:                              See 3.4.6.   (line 10335)
mu_sieve_mfree:                                See 3.4.5.   (line 10313)
mu_sieve_mrealloc:                             See 3.4.5.   (line 10303)
mu_sieve_mstrdup:                              See 3.4.5.   (line 10298)
mu_sieve_parse_error_t:                        See 3.4.1.   (line  9954)
mu_sieve_printf_t:                             See 3.4.1.   (line  9938)
mu_sieve_register_action:                      See 3.4.4.   (line 10272)
mu_sieve_register_comparator:                  See 3.4.4.   (line 10278)
mu_sieve_register_test:                        See 3.4.4.   (line 10267)
mu_sieve_relcmp_t:                             See 3.4.1.   (line 10004)
mu_sieve_relcmpn_t:                            See 3.4.1.   (line 10005)
mu_sieve_retrieve_t:                           See 3.4.1.   (line 10018)
mu_sieve_runtime_tag_t:                        See 3.4.1.   (line  9898)
mu_sieve_set_daemon_email:                     See 3.4.2.   (line 10215)
mu_sieve_set_debug:                            See 3.4.2.   (line 10172)
mu_sieve_set_debug_level:                      See 3.4.2.   (line 10178)
mu_sieve_set_error:                            See 3.4.2.   (line 10141)
mu_sieve_set_logger:                           See 3.4.2.   (line 10200)
mu_sieve_set_mailer:                           See 3.4.2.   (line 10211)
mu_sieve_set_parse_error:                      See 3.4.2.   (line 10154)
mu_sieve_set_ticket:                           See 3.4.2.   (line 10206)
mu_sieve_tag_checker_t:                        See 3.4.1.   (line 10032)
mu_sieve_tag_def_t:                            See 3.4.1.   (line  9883)
mu_sieve_tag_lookup:                           See 3.4.4.   (line 10281)
mu_sieve_test_lookup:                          See 3.4.4.   (line 10255)
mu_sieve_type_str:                             See 3.4.2.   (line 10226)
mu_sieve_value_t:                              See 3.4.1.   (line  9840)
mu_stdio_stream_create:                        See 3.1.9.   (line  7666)
MU_STREAM_ALLOW_LINKS:                         See 3.1.9.   (line  7645)
MU_STREAM_APPEND:                              See 3.1.9.   (line  7626)
mu_stream_close:                               See 3.1.9.   (line  7680)
MU_STREAM_CREAT:                               See 3.1.9.   (line  7629)
mu_stream_create:                              See 3.1.9.   (line  7708)
mu_stream_destroy:                             See 3.1.9.   (line  7676)
mu_stream_flush:                               See 3.1.9.   (line  7705)
mu_stream_get_fd:                              See 3.1.9.   (line  7684)
mu_stream_get_fd2:                             See 3.1.9.   (line  7687)
mu_stream_get_flags:                           See 3.1.9.   (line  7715)
mu_stream_get_owner:                           See 3.1.9.   (line  7711)
mu_stream_get_property:                        See 3.1.9.   (line  7720)
mu_stream_get_state:                           See 3.1.9.   (line  7725)
mu_stream_is_seekable:                         See 3.1.9.   (line  7682)
MU_STREAM_NO_CHECK:                            See 3.1.9.   (line  7636)
MU_STREAM_NO_CLOSE:                            See 3.1.9.   (line  7641)
MU_STREAM_NONBLOCK:                            See 3.1.9.   (line  7633)
mu_stream_open:                                See 3.1.9.   (line  7678)
MU_STREAM_RDWR:                                See 3.1.9.   (line  7623)
mu_stream_read:                                See 3.1.9.   (line  7690)
MU_STREAM_READ:                                See 3.1.9.   (line  7617)
mu_stream_readline:                            See 3.1.9.   (line  7693)
mu_stream_seek:                                See 3.1.9.   (line  7781)
MU_STREAM_SEEKABLE:                            See 3.1.9.   (line  7639)
mu_stream_sequential_readline:                 See 3.1.9.   (line  7775)
mu_stream_sequential_write:                    See 3.1.9.   (line  7778)
mu_stream_set_close:                           See 3.1.9.   (line  7745)
mu_stream_set_destroy:                         See 3.1.9.   (line  7739)
mu_stream_set_fd:                              See 3.1.9.   (line  7748)
mu_stream_set_flags:                           See 3.1.9.   (line  7717)
mu_stream_set_flush:                           See 3.1.9.   (line  7769)
mu_stream_set_open:                            See 3.1.9.   (line  7742)
mu_stream_set_owner:                           See 3.1.9.   (line  7713)
mu_stream_set_property:                        See 3.1.9.   (line  7723)
mu_stream_set_read:                            See 3.1.9.   (line  7752)
mu_stream_set_readline:                        See 3.1.9.   (line  7756)
mu_stream_set_size:                            See 3.1.9.   (line  7759)
mu_stream_set_strerror:                        See 3.1.9.   (line  7772)
mu_stream_set_truncate:                        See 3.1.9.   (line  7762)
mu_stream_set_write:                           See 3.1.9.   (line  7766)
mu_stream_setbufsiz:                           See 3.1.9.   (line  7703)
mu_stream_size:                                See 3.1.9.   (line  7695)
mu_stream_strerror:                            See 3.1.9.   (line  7783)
mu_stream_write:                               See 3.1.9.   (line  7701)
MU_STREAM_WRITE:                               See 3.1.9.   (line  7620)
mu_tcp_stream_create:                          See 3.1.9.   (line  7651)
mu_ticket_create:                              See 3.1.11.  (line  8027)
mu_ticket_destroy:                             See 3.1.11.  (line  8029)
mu_ticket_get_data:                            See 3.1.11.  (line  8044)
mu_ticket_get_owner:                           See 3.1.11.  (line  8034)
mu_ticket_pop:                                 See 3.1.11.  (line  8040)
mu_ticket_set_data:                            See 3.1.11.  (line  8042)
mu_ticket_set_destroy:                         See 3.1.11.  (line  8032)
mu_ticket_set_pop:                             See 3.1.11.  (line  8037)
mu_url_create:                                 See 3.1.14.  (line  8670)
mu_url_decode:                                 See 3.1.14.  (line  8731)
mu_url_destroy:                                See 3.1.14.  (line  8673)
mu_url_get_auth:                               See 3.1.14.  (line  8704)
mu_url_get_host:                               See 3.1.14.  (line  8707)
mu_url_get_passwd:                             See 3.1.14.  (line  8701)
mu_url_get_path:                               See 3.1.14.  (line  8712)
mu_url_get_port:                               See 3.1.14.  (line  8709)
mu_url_get_query:                              See 3.1.14.  (line  8715)
mu_url_get_scheme:                             See 3.1.14.  (line  8695)
mu_url_get_user:                               See 3.1.14.  (line  8698)
mu_url_is_same_host:                           See 3.1.14.  (line  8727)
mu_url_is_same_path:                           See 3.1.14.  (line  8725)
mu_url_is_same_port:                           See 3.1.14.  (line  8729)
mu_url_is_same_scheme:                         See 3.1.14.  (line  8721)
mu_url_is_same_user:                           See 3.1.14.  (line  8723)
mu_url_is_scheme:                              See 3.1.14.  (line  8719)
mu_url_is_ticket:                              See 3.1.14.  (line  8736)
mu_url_parse:                                  See 3.1.14.  (line  8676)
mu_url_to_string:                              See 3.1.14.  (line  8717)
mu_wicket_create:                              See 3.1.11.  (line  8068)
mu_wicket_destroy:                             See 3.1.11.  (line  8070)
mu_wicket_get_filename:                        See 3.1.11.  (line  8075)
mu_wicket_get_ticket:                          See 3.1.11.  (line  8081)
mu_wicket_set_filename:                        See 3.1.11.  (line  8072)
mu_wicket_set_ticket:                          See 3.1.11.  (line  8078)
next DAY:                                      See B.5.     (line 12172)
next in date strings:                          See B.1.     (line 11993)
no-header:                                     See 2.7.2.   (line  3901)
no-site-config, --no-site-config option, described:See 2.2. (line   462)
no-site-config, --no-site-config option, introduced:See 2.1.2.
                                                            (line   435)
no-user-config, --no-user-config option, described:See 2.2. (line   472)
no-user-config, --no-user-config option, introduced:See 2.1.2.
                                                            (line   438)
noon in date strings:                          See B.3.     (line 12113)
now in date strings:                           See B.6.     (line 12209)
numaddr:                                       See 4.6.2.   (line 11221)
other-mailbox-mode:                            See 2.15.2.  (line  5582)
other-namespace:                               See 2.15.2.  (line  5574)
overflow-control-interval:                     See 2.16.2.2.
                                                            (line  5821)
overflow-delay-time:                           See 2.16.2.2.
                                                            (line  5817)
package:                                       See 2.17.1.1.
                                                            (line  5966)
package_string:                                See 2.17.1.1.
                                                            (line  5969)
passwd:                                        See 2.2.17.  (line  1967)
passwd-dir:                                    See 2.2.14.  (line  1734)
pidfile:                                       See 2.2.11.1.
                                                            (line  1470)
pipe:                                          See 4.7.2.   (line 11662)
pm in date strings:                            See B.3.     (line 12113)
port <1>:                                      See 2.2.17.  (line  1956)
port:                                          See 2.2.11.1.
                                                            (line  1477)
preauth:                                       See 2.15.2.  (line  5603)
preauth-only:                                  See 2.15.2.  (line  5642)
preserve:                                      See 2.6.1.   (line  3686)
printhdr:                                      See 2.17.1.1.
                                                            (line  6038)
quota-db <1>:                                  See 2.11.2.  (line  5007)
quota-db:                                      See 2.10.9.  (line  4829)
rcpt:                                          See 2.17.1.1.
                                                            (line  6023)
redirect:                                      See 4.7.1.   (line 11582)
references:                                    See 2.17.1.1.
                                                            (line  6048)
reject:                                        See 4.7.1.   (line 11504)
reply_regex:                                   See 2.17.1.1.
                                                            (line  5982)
request-control-interval:                      See 2.16.2.2.
                                                            (line  5814)
retry-count:                                   See 2.2.6.   (line  1118)
retry-timeout:                                 See 2.2.6.   (line  1122)
reuse-address:                                 See 2.10.9.  (line  4880)
reverse:                                       See 2.6.1.   (line  3689)
service:                                       See 2.2.13.  (line  1702)
shared-mailbox-mode:                           See 2.15.2.  (line  5578)
shared-namespace:                              See 2.15.2.  (line  5570)
show-all-match:                                See 2.7.2.   (line  3910)
show-config-options, --show-config-options option, described:See 2.1.2.
                                                            (line   412)
sieve:                                         See 2.8.1.   (line  4038)
sieve-filter <1>:                              See 2.11.2.  (line  5010)
sieve-filter:                                  See 2.10.9.  (line  4832)
sieve_machine_t:                               See 3.4.1.   (line  9802)
single-process:                                See 2.2.11.2.
                                                            (line  1530)
size:                                          See 4.6.1.   (line 11089)
spamd:                                         See 4.6.2.   (line 11255)
stat-file:                                     See 2.14.4.  (line  5417)
stderr:                                        See 2.10.9.  (line  4859)
stop:                                          See 4.7.1.   (line 11427)
string_to_flags:                               See 3.1.8.   (line  7607)
tag:                                           See 2.2.3.   (line   743)
this in date strings:                          See B.6.     (line 12209)
ticket:                                        See 2.8.1.   (line  4076)
timeout <1>:                                   See 2.2.11.2.
                                                            (line  1544)
timeout:                                       See 2.2.11.1.
                                                            (line  1484)
timestamp:                                     See 4.6.2.   (line 11354)
tls-required <1>:                              See 2.15.2.  (line  5599)
tls-required:                                  See 2.14.4.  (line  5410)
today in date strings:                         See B.6.     (line 12209)
tomorrow in date strings:                      See B.6.     (line 12205)
transcript:                                    See 2.2.11.2.
                                                            (line  1535)
true:                                          See 4.6.1.   (line 11043)
undelete:                                      See 2.14.4.  (line  5399)
unre:                                          See 2.17.1.1.
                                                            (line  5975)
url:                                           See 2.2.7.   (line  1153)
usage, --usage option, described:              See 2.1.2.   (line   397)
user:                                          See 2.2.17.  (line  1964)
vacation:                                      See 4.7.2.   (line 11695)
verbose:                                       See 2.8.1.   (line  4083)
version:                                       See 2.17.1.1.
                                                            (line  5972)
version, --version option, described:          See 2.1.2.   (line   408)
weedlist:                                      See 2.7.2.   (line  3895)
week in date strings:                          See B.6.     (line 12191)
year in date strings:                          See B.6.     (line 12191)
yesterday in date strings:                     See B.6.     (line 12205)
Variable Index
**************

appenddeadletter, mail variable:               See 2.4.6.   (line  3142)
ARGP_HELP_FMT, environment variable:           See Appendix C.
                                                            (line 12363)
askbcc, mail variable:                         See 2.4.6.   (line  3150)
askcc, mail variable:                          See 2.4.6.   (line  3157)
asksub, mail variable:                         See 2.4.6.   (line  3164)
autoinc, mail variable:                        See 2.4.6.   (line  3171)
autoprint, mail variable:                      See 2.4.6.   (line  3177)
bang, mail variable:                           See 2.4.6.   (line  3184)
charset, mail variable:                        See 2.4.6.   (line  3201)
cmd, mail variable:                            See 2.4.6.   (line  3212)
columns, mail variable:                        See 2.4.6.   (line  3219)
crt, mail variable:                            See 2.4.6.   (line  3225)
datefield, mail variable:                      See 2.4.6.   (line  3191)
decode-fallback, mail variable:                See 2.4.6.   (line  3237)
doc-opt-col:                                   See Appendix C.
                                                            (line 12436)
dot, mail variable:                            See 2.4.6.   (line  3256)
dup-args:                                      See Appendix C.
                                                            (line 12393)
dup-args-note:                                 See Appendix C.
                                                            (line 12410)
editheaders, mail variable:                    See 2.4.6.   (line  3271)
emptystart, mail variable:                     See 2.4.6.   (line  3263)
escape, mail variable:                         See 2.4.6.   (line  3279)
flipr, mail variable:                          See 2.4.6.   (line  3286)
folder, mail variable:                         See 2.4.6.   (line  3293)
header, mail variable:                         See 2.4.6.   (line  3300)
header-col:                                    See Appendix C.
                                                            (line 12472)
hold, mail variable:                           See 2.4.6.   (line  3307)
ignore, mail variable:                         See 2.4.6.   (line  3316)
ignoreeof, mail variable:                      See 2.4.6.   (line  3324)
indentprefix, mail variable:                   See 2.4.6.   (line  3331)
keepsave, mail variable:                       See 2.4.6.   (line  3346)
LD_LIBRARY_PATH:                               See 4.4.     (line 10885)
long-opt-col:                                  See Appendix C.
                                                            (line 12428)
LTDL_LIBRARY_PATH:                             See 4.4.     (line 10885)
mailx, mail variable:                          See 2.4.6.   (line  3354)
metamail, mail variable:                       See 2.4.6.   (line  3369)
metoo, mail variable:                          See 2.4.6.   (line  3404)
mimenoask, mail variable:                      See 2.4.6.   (line  3388)
mode, mail variable:                           See 2.4.6.   (line  3412)
mu_auth_generic_module:                        See 3.2.5.   (line  9371)
mu_auth_pam_module:                            See 3.2.5.   (line  9379)
mu_auth_sql_module:                            See 3.2.5.   (line  9383)
mu_auth_system_module:                         See 3.2.5.   (line  9366)
mu_auth_virtual_module:                        See 3.2.5.   (line  9393)
MU_DEFAULT_SCHEME:                             See 2.2.5.   (line  1053)
nullbody, mail variable:                       See 2.4.6.   (line  3419)
nullbodymsg:                                   See 2.4.6.   (line  3438)
opt-doc-col:                                   See Appendix C.
                                                            (line 12458)
outfolder, mail variable:                      See 2.4.6.   (line  3448)
page, mail variable:                           See 2.4.6.   (line  3456)
prompt, mail variable:                         See 2.4.6.   (line  3463)
quit, mail variable:                           See 2.4.6.   (line  3469)
rc, mail variable:                             See 2.4.6.   (line  3475)
record, mail variable:                         See 2.4.6.   (line  3483)
regex, mail variable:                          See 2.4.6.   (line  3495)
replyprefix, mail variable:                    See 2.4.6.   (line  3502)
replyregex, mail variable:                     See 2.4.6.   (line  3509)
rmargin:                                       See Appendix C.
                                                            (line 12488)
save, mail variable:                           See 2.4.6.   (line  3526)
screen, mail variable:                         See 2.4.6.   (line  3534)
sendmail, mail variable:                       See 2.4.6.   (line  3540)
short-opt-col:                                 See Appendix C.
                                                            (line 12420)
showto, mail variable:                         See 2.4.6.   (line  3562)
sign, mail variable:                           See 2.4.6.   (line  3554)
Sign, mail variable:                           See 2.4.6.   (line  3546)
string:                                        See 2.17.1.2.
                                                            (line  6054)
subject, mail variable:                        See 2.4.6.   (line  3570)
toplines, mail variable:                       See 2.4.6.   (line  3577)
TZ:                                            See B.9.     (line 12292)
usage-indent:                                  See Appendix C.
                                                            (line 12484)
verbose, mail variable:                        See 2.4.6.   (line  3583)
xmailer, mail variable:                        See 2.4.6.   (line  3590)
Keyword Index
*************

!, mail command:                               See 2.4.4.   (line  3022)
#include, sieve:                               See 4.3.     (line 10782)
#searchpath, sieve:                            See 4.3.     (line 10799)
:all, sieve:                                   See 4.6.     (line 11010)
:comparator, sieve:                            See 4.6.     (line 10991)
:contains, sieve:                              See 4.6.     (line 10943)
:count, sieve:                                 See 4.6.     (line 10984)
:domain, sieve:                                See 4.6.     (line 11016)
:is, sieve:                                    See 4.6.     (line 10936)
:localpart, sieve:                             See 4.6.     (line 11013)
:matches, sieve:                               See 4.6.     (line 10950)
:mime:                                         See 4.6.1.   (line 11182)
:over <1>:                                     See 4.6.2.   (line 11244)
:over:                                         See 4.6.1.   (line 11105)
:regex, sieve:                                 See 4.6.     (line 10958)
:under <1>:                                    See 4.6.2.   (line 11247)
:under:                                        See 4.6.1.   (line 11108)
:value, sieve:                                 See 4.6.     (line 10962)
=, mail command:                               See 2.4.4.   (line  2666)
?, mail command:                               See 2.4.4.   (line  2579)
acl:                                           See 2.2.8.   (line  1204)
alias, mail command:                           See 2.4.4.   (line  2868)
all, sieve:                                    See 4.6.     (line 11010)
allof:                                         See 4.2.4.   (line 10757)
alternates, mail command:                      See 2.4.4.   (line  2868)
and, sieve:                                    See 4.2.4.   (line 10757)
any:                                           See 2.2.8.   (line  1248)
anyof:                                         See 4.2.4.   (line 10757)
auth:                                          See 2.2.12.  (line  1557)
chdir, mail command:                           See 2.4.4.   (line  2620)
comparator, sieve:                             See 4.6.     (line 10991)
contains, sieve:                               See 4.6.     (line 10943)
Copy, mail command:                            See 2.4.4.   (line  2797)
copy, mail command:                            See 2.4.4.   (line  2797)
count, sieve:                                  See 4.6.     (line 10984)
debug:                                         See 2.2.4.   (line   749)
decode, mail command:                          See 2.4.4.   (line  2708)
delete, mail command:                          See 2.4.4.   (line  2777)
discard, mail command:                         See 2.4.4.   (line  2641)
domain, sieve:                                 See 4.6.     (line 11016)
dp, mail command:                              See 2.4.4.   (line  2777)
dt, mail command:                              See 2.4.4.   (line  2777)
echo, mail command:                            See 2.4.5.   (line  3041)
edit, mail command:                            See 2.4.4.   (line  2850)
else, mail command:                            See 2.4.5.   (line  3099)
endif, mail command:                           See 2.4.5.   (line  3099)
file, mail command:                            See 2.4.4.   (line  2620)
folder, mail command:                          See 2.4.4.   (line  2620)
folders, mail command:                         See 2.4.4.   (line  2666)
Followup, mail command:                        See 2.4.4.   (line  2894)
followup, mail command:                        See 2.4.4.   (line  2894)
forward-file:                                  See 2.10.6.  (line  4676)
forward-file-checks:                           See 2.10.6.  (line  4683)
from, mail command:                            See 2.4.4.   (line  2666)
GNU-MU-Dir:                                    See 2.2.15.  (line  1802)
GNU-MU-GECOS:                                  See 2.2.15.  (line  1801)
GNU-MU-GID:                                    See 2.2.15.  (line  1800)
GNU-MU-Mailbox:                                See 2.2.15.  (line  1804)
GNU-MU-Quota:                                  See 2.2.15.  (line  1805)
GNU-MU-Shell:                                  See 2.2.15.  (line  1803)
GNU-MU-UID:                                    See 2.2.15.  (line  1799)
GNU-MU-User-Name:                              See 2.2.15.  (line  1797)
group, mail command:                           See 2.4.4.   (line  2868)
gsasl:                                         See 2.2.20.  (line  2024)
guile-filter:                                  See 2.10.5.2.
                                                            (line  4657)
headers, mail command:                         See 2.4.4.   (line  2666)
help, mail command:                            See 2.4.4.   (line  2579)
hold, mail command:                            See 2.4.4.   (line  2756)
if, mail command:                              See 2.4.5.   (line  3099)
if, sieve:                                     See 4.2.3.   (line 10692)
ignore, mail command:                          See 2.4.4.   (line  2641)
include:                                       See 2.2.2.   (line   697)
incorporate, mail command:                     See 2.4.4.   (line  3015)
is, sieve:                                     See 4.6.     (line 10936)
ldap:                                          See 2.2.18.  (line  1974)
list, mail command:                            See 2.4.4.   (line  2579)
localpart, sieve:                              See 4.6.     (line 11013)
locking:                                       See 2.2.6.   (line  1070)
logging:                                       See 2.2.3.   (line   718)
mail, mail command:                            See 2.4.4.   (line  2894)
mailbox:                                       See 2.2.5.   (line   887)
mailer:                                        See 2.2.7.   (line  1136)
matches, sieve:                                See 4.6.     (line 10950)
mbox, mail command:                            See 2.4.4.   (line  2797)
next, mail command:                            See 2.4.4.   (line  2603)
nosender, mail command:                        See 2.4.4.   (line  2976)
not, sieve:                                    See 4.2.4.   (line 10753)
or, sieve:                                     See 4.2.4.   (line 10757)
pam:                                           See 2.2.13.  (line  1687)
param:                                         See 2.2.5.   (line  1008)
pipe, mail command:                            See 2.4.4.   (line  2708)
preserve, mail command:                        See 2.4.4.   (line  2756)
prev, mail command:                            See 2.4.4.   (line  2603)
Print, mail command:                           See 2.4.4.   (line  2708)
print, mail command:                           See 2.4.4.   (line  2708)
radius:                                        See 2.2.15.  (line  1764)
regex, sieve:                                  See 4.6.     (line 10958)
Reply, mail command:                           See 2.4.4.   (line  2894)
reply, mail command:                           See 2.4.4.   (line  2894)
require, sieve:                                See 4.4.     (line 10807)
Respond, mail command:                         See 2.4.4.   (line  2894)
respond, mail command:                         See 2.4.4.   (line  2894)
retain, mail command:                          See 2.4.4.   (line  2641)
Save, mail command:                            See 2.4.4.   (line  2797)
save, mail command:                            See 2.4.4.   (line  2797)
sender, mail command:                          See 2.4.4.   (line  2976)
server:                                        See 2.2.11.2.
                                                            (line  1490)
set, mail command:                             See 2.4.5.   (line  3052)
shell, mail command:                           See 2.4.4.   (line  3022)
sieve-filter:                                  See 2.10.5.1.
                                                            (line  4626)
size, mail command:                            See 2.4.4.   (line  2666)
source, mail command:                          See 2.4.5.   (line  3046)
sql:                                           See 2.2.16.  (line  1893)
summary, mail command:                         See 2.4.4.   (line  2666)
tag, mail command:                             See 2.4.4.   (line  2756)
tcp-wrappers:                                  See 2.2.9.   (line  1326)
text::                                         See 4.1.     (line 10552)
tls:                                           See 2.2.19.  (line  2005)
top, mail command:                             See 2.4.4.   (line  2708)
touch, mail command:                           See 2.4.4.   (line  2797)
type:                                          See 2.2.5.   (line  1003)
Type, mail command:                            See 2.4.4.   (line  2708)
type, mail command:                            See 2.4.4.   (line  2708)
unalias, mail command:                         See 2.4.4.   (line  2868)
undelete, mail command:                        See 2.4.4.   (line  2777)
unset, mail command:                           See 2.4.5.   (line  3052)
user:                                          See 2.2.5.   (line  1011)
value, sieve:                                  See 4.6.     (line 10962)
version, mail command:                         See 2.4.4.   (line  2579)
virtdomain:                                    See 2.2.14.  (line  1711)
visual, mail command:                          See 2.4.4.   (line  2850)
warranty, mail command:                        See 2.4.4.   (line  2579)
Write, mail command:                           See 2.4.4.   (line  2797)
write, mail command:                           See 2.4.4.   (line  2797)
z, mail command:                               See 2.4.4.   (line  2666)
|, mail command:                               See 2.4.4.   (line  2708)
~!, mail escape:                               See 2.4.3.   (line  2515)
~-, mail escape:                               See 2.4.3.   (line  2498)
~., mail escape:                               See 2.4.3.   (line  2378)
~:, mail escape:                               See 2.4.3.   (line  2498)
~?, mail escape:                               See 2.4.3.   (line  2399)
~A, mail escape:                               See 2.4.3.   (line  2472)
~a, mail escape:                               See 2.4.3.   (line  2472)
~e, mail escape:                               See 2.4.3.   (line  2406)
~F, mail escape:                               See 2.4.3.   (line  2482)
~f, mail escape:                               See 2.4.3.   (line  2482)
~i, mail escape:                               See 2.4.3.   (line  2492)
~M, mail escape:                               See 2.4.3.   (line  2438)
~m, mail escape:                               See 2.4.3.   (line  2438)
~p, mail escape:                               See 2.4.3.   (line  2465)
~v, mail escape:                               See 2.4.3.   (line  2406)
~w, mail escape:                               See 2.4.3.   (line  2465)
~x, mail escape:                               See 2.4.3.   (line  2378)
~|, mail escape:                               See 2.4.3.   (line  2515)
Program Index
*************

comsatd:                                       See 2.16.    (line  5738)
frm:                                           See 2.3.     (line  2059)
from:                                          See 2.3.     (line  2116)
guimb:                                         See 2.9.     (line  4242)
imap4d:                                        See 2.15.    (line  5461)
maidag:                                        See 2.10.    (line  4396)
mail:                                          See 2.4.     (line  2147)
mail.local:                                    See 2.11.    (line  4885)
mail.remote:                                   See 2.12.    (line  5047)
mailutils-config:                              See 2.18.    (line  6227)
messages:                                      See 2.5.     (line  3618)
mimeview:                                      See 2.13.    (line  5086)
movemail:                                      See 2.6.     (line  3661)
pop3d:                                         See 2.14.    (line  5231)
readmsg:                                       See 2.7.     (line  3831)
sieve:                                         See 2.8.     (line  3923)
Concept Index
*************

This is a general index of all issues discussed in this manual

abbreviations for months:                      See B.2.     (line 12076)
action, sieve:                                 See 4.2.2.   (line 10677)
Address:                                       See 3.1.12.  (line  8117)
Attribute:                                     See 3.1.8.   (line  7519)
authentication:                                See 2.2.12.  (line  1557)
Authentication Library:                        See 3.2.     (line  9214)
Authenticator:                                 See 3.1.11.  (line  8012)
authorization:                                 See 2.2.12.  (line  1557)
authors of get_date:                           See B.10.    (line 12336)
beginning of time, for POSIX:                  See B.8.     (line 12270)
Bellovin, Steven M.:                           See B.10.    (line 12336)
Berets, Jim:                                   See B.10.    (line 12336)
Berry, K.:                                     See B.10.    (line 12344)
block statement, configuration file:           See 2.2.1.3. (line   681)
Body:                                          See 3.1.7.   (line  7483)
boolean value:                                 See 2.2.1.2. (line   579)
calendar date item:                            See B.2.     (line 12044)
case, ignored in dates:                        See B.1.     (line 12031)
comments, configuration file:                  See 2.2.1.1. (line   541)
comments, in dates:                            See B.1.     (line 12031)
comments, multi-line:                          See 2.2.1.1. (line   549)
comments, single-line:                         See 2.2.1.1. (line   541)
comparator, sieve:                             See 4.5.     (line 10912)
condition, sieve:                              See 4.2.4.   (line 10750)
configuration file statements:                 See 2.2.1.2. (line   559)
configuring servers:                           See 2.2.11.  (line  1390)
daemon, server mode:                           See 2.2.11.1.
                                                            (line  1432)
date format, ISO 8601:                         See B.2.     (line 12068)
date input formats:                            See Appendix B.
                                                            (line 11939)
day of week item:                              See B.5.     (line 12163)
direct indexing:                               See 2.2.5.   (line   958)
directory indexing:                            See 2.2.5.   (line   943)
displacement of dates:                         See B.6.     (line 12182)
Eggert, Paul:                                  See B.10.    (line 12336)
Envelope:                                      See 3.1.5.   (line  7217)
epoch, for POSIX:                              See B.8.     (line 12270)
escape sequence:                               See 2.2.1.2. (line   587)
Exim:                                          See 2.10.2.  (line  4445)
FDL, GNU Free Documentation License:           See Appendix D.
                                                            (line 12493)
Folder:                                        See 3.1.1.   (line  6582)
forward:                                       See 2.10.6.  (line  4667)
Framework:                                     See 3.1.     (line  6453)
general date syntax:                           See B.1.     (line 11973)
hashed indexing:                               See 2.2.5.   (line   984)
Headers:                                       See 3.1.6.   (line  7256)
here-document:                                 See 2.2.1.2. (line   625)
IMAP4 namespace:                               See 2.15.1.  (line  5468)
include statement, configuration file:         See 2.2.2.   (line   697)
indexing, direct:                              See 2.2.5.   (line   958)
indexing, hashed:                              See 2.2.5.   (line   984)
indexing, reverse:                             See 2.2.5.   (line   978)
inetd, server mode:                            See 2.2.11.1.
                                                            (line  1444)
ISO 8601 date format:                          See B.2.     (line 12068)
items in date strings:                         See B.1.     (line 11973)
Iterator:                                      See 3.1.10.  (line  7960)
language, in dates:                            See B.1.     (line 12007)
libmu_scm:                                     See 3.3.     (line  9469)
libmuauth:                                     See 3.2.     (line  9214)
libmuauth modules:                             See 3.2.5.   (line  9361)
libmuauth, data types:                         See 3.2.1.   (line  9225)
libmuauth, linking with:                       See 3.2.6.   (line  9400)
libmuauth, obtaining authorization information:See 3.2.4.   (line  9330)
Libraries:                                     See 3.       (line  6450)
libsieve:                                      See 3.4.     (line  9766)
Linking with libmuauth:                        See 3.2.6.   (line  9400)
list:                                          See 2.2.1.2. (line   667)
LMTP:                                          See 2.10.3.  (line  4465)
Locker:                                        See 3.1.13.  (line  8504)
MacKenzie, David:                              See B.10.    (line 12336)
Mailbox:                                       See 3.1.2.   (line  6660)
Mailer:                                        See 3.1.3.   (line  6941)
mailman:                                       See 4.7.2.   (line 11617)
Mailutils configuration file:                  See 2.2.     (line   444)
mailutils.dict:                                See 2.2.15.  (line  1808)
mailutils.rc:                                  See 2.2.     (line   444)
Message:                                       See 3.1.4.   (line  7074)
MeTA1:                                         See 2.10.3.  (line  4465)
Meyering, Jim:                                 See B.10.    (line 12336)
minutes, time zone correction by:              See B.3.     (line 12121)
month names in date strings:                   See B.2.     (line 12076)
months, written-out:                           See B.1.     (line 12003)
multi-line comments:                           See 2.2.1.1. (line   549)
multiline strings, sieve:                      See 4.1.     (line 10552)