Published by the Free Software Foundation, 31 Milk Street, Boston, MA
02196, USA

   Copyright (C) 1999-2025 Free Software Foundation, Inc.

   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, and no Back-Cover texts.  A copy of
the license is included in the section entitled "GNU Free Documentation
License".

3.16.4 Pop3d Configuration
--------------------------

The following configuration file statements affect the behavior of
'pop3d'.

Statement              Reference
-------------------------------------------------------------------
debug                  debug statement.
tls                    tls statement.
tls-file-checks        tls-file-checks statement.
mailbox                mailbox statement.
locking                locking statement.
logging                logging statement.
pam                    pam statement.
sql                    sql statement.
virtdomain             virtdomain statement.
radius                 radius statement.
ldap                   ldap statement.
auth                   auth statement.
server                 Server Settings.
acl                    acl statement.
tcp-wrappers           tcp-wrappers statement.

 -- Pop3d Conf: tls-mode MODE
     Configure the use of TLS encryption for inetd mode.

     In daemon mode, this statement sets the type of TLS encryption to
     use in all server blocks that lack the 'tls-mode' statement (see
     Server Statement).

     Allowed values for MODE are:

     no
          TLS is not used.  The 'STLS' command won't be available even
          if the TLS configuration is otherwise complete.

     ondemand
          TLS is initiated when the user issues the appropriate command.
          This is the default when TLS is configured.

     required
          Same as above, but the use of TLS is mandatory.  The
          authentication state is entered only after TLS negotiation has
          succeeded.

     connection
          TLS is always forced when the connection is established (POP3S
          protocol).

 -- Pop3d Conf: undelete BOOL
     On startup, clear deletion marks from all the messages.

 -- Pop3d Conf: expire N
     Automatically expire read messages after N days.  See
     Auto-expire, for a detailed description.

 -- Pop3d Conf: delete-expired BOOL
     Delete expired messages upon closing the mailbox.  See
     Auto-expire, for a detailed description.

 -- Pop3d Conf: login-delay DURATION
     Set the minimal allowed delay between two successive logins.  See
     Login delay, for more information.

 -- Pop3d Conf: stat-file FILE
     Set the name of login statistics file for the 'login-delay'
     facility.  See Login delay, for more information.

 -- Pop3d Conf: bulletin-source FILE
     Get bulletins from the specified mailbox.  See Bulletins, for a
     detailed description.

 -- Pop3d Conf: bulletin-db FILE
     Set bulletin database file name.  See Bulletins, for a detailed
     description.

3.16.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.

'--foreground'
     Remain in foreground.

   The Mailutils common options are also understood.  See Common Options.

3.17 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.

3.17.1 Namespace
----------------

GNU 'imap4d' supports a notion of "namespaces" defined in RFC 2342.  A
namespace can be regarded as a list of entities, defining locations to
which the user has certain access rights.  Each entity includes the
"prefix", under which the mailboxes can be found, "hierarchy delimiter",
a character used to delimit parts of a path to a mailbox, and a
"directory" on the file system on the server, which actually holds the
mailboxes.  Among these three values, only first two are visible to the
client using the IMAP 'NAMESPACE' command.

   There are three namespaces:

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.

     By default, this namespace contains a single prefix:

          prefix: ""
          delimiter: /
          directory: home directory of the user

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.

     By default, this namespace is empty.

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, this namespace is empty.

   The default values ensure that each user is able to see or otherwise
access mailboxes residing in the directories other than his own home.

   These defaults can be changed using the 'namespace' block statement:

     namespace NAME {
         mailbox-mode MODE;
         prefix PFX {
           directory PATH;
           delimiter CHR;
           mailbox-type TYPE;
         }
     }

   The NAME argument to the 'namespace' statement declares which
namespace is being configured.  Allowed values are: 'personal', 'other',
and 'shared'.

   The 'mailbox-mode' statement configures the file mode for the
mailboxes created within that namespace (provided that the directory
permissions allow the user to create mailboxes).  The MODE argument is a
comma-delimited list of symbolic mode settings, similar to that used by
'chmod'.  Each setting 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:

     mailbox-mode g=rw;

   The 'prefix' statement configures available prefixes and determines
their mappings to the server's file system.  The PFX argument defines
the prefix which will be visible to the IMAP client.

   The 'directory' statement defines the directory in the file system to
which PFX is mapped.  Exactly one 'directory' statement must be present
in each 'prefix' block.  The inerpretation of its argument depends on
the namespace in which it occurs.

   When used in the 'namespace shared' block, the argument to this
statement is interpreted verbatim, as an absolute pathname.

   When used in 'namespace personal' the argument to 'directory'
statement can contain references to the following variables (see
Variables):

user
     Login name of the user.

home
     Home directory of the user.

   For example, the following statement maps the default personal
namespace to the directory 'imap' in the user's home directory:

     namespace personal {
       prefix "";
       directory "$home/imap";
     }

   If the 'directory' statement is used within the 'namespace other'
block, its value can contain the '$user' and '$home' variables as well,
but their meaning is different.  For the 'other' namespace, the '$user'
variable is expanded to the part of the actual reference contained
between the prefix and first hierarchy delimiter (or the end of the
reference, if no delimiter occurs to the right of the prefix).
Correspondingly, '$home' expands to the home directory of that user.
Consider, for example, the following statement:

     namespace other {
       prefix "~";
       directory "/var/imap/$user";
     }

   If the client issues the following statement:

     1 LIST "~smith" "%"

then '$user' will expand to the string 'smith' and the server will look
for all mailboxes in the directory '/var/imap/smith'.

   The 'delimiter' statement defines the folder hierarchy delimiter for
that prefix.  It is optional, the default value being '"/"'.

   The 'mailbox-type' statement declares the type of the mailboxes
within that prefix.  If present, its argument must be a valid mailbox
type (e.g.  'mailbox', 'maildir', or 'mh').  The IMAP 'LIST' command
will display only mailboxes of that type.  The 'CREATE' command will
create mailboxes of that type.

   In the absence of the 'mailbox-type' statement, the IMAP 'LIST'
command will display mailboxes of any type supported by Mailutils.  The
type of newly-created mailboxes is then determined by the 'mailbox-type'
statement (see mailbox-type).

   Any number of 'prefix' blocks can be present.

   Consider, for example, the following configuration:

     namespace personal {
        prefix "" {
           directory "$home/mailfolder";
        }
        prefix "#MH:" {
           directory "$home/Mail";
           delimiter "/";
           mailbox-type "mh";
        }
     }

   It defines the personal namespace containing two prefixes.  The empty
prefix is mapped to the directory 'mailfolder' in the home directory of
the currently authenticated user.  Any type of mailboxes is supported
within that prefix.

   The prefix '#MH:' is mapped to the directory 'Mail' in the home
directory of the user, and is limited to contain only mailboxes in MH
format.

   Note that if the prefixes '""' is not defined in the personal
namespace, the following default will be automatically created:

     prefix "" {
       directory "$home";
     }

3.17.2 Configuration of 'imap4d'.
---------------------------------

The behavior of 'imap4d' is altered by the following configuration
statements:

Statement              Reference
-------------------------------------------------------------------
debug                  debug statement.
tls                    tls statement.
tls-file-checks        tls-file-checks statement.
mailbox                mailbox statement.
locking                locking statement.
logging                logging statement.
pam                    pam statement.
sql                    sql statement.
virtdomain             virtdomain statement.
radius                 radius statement.
ldap                   ldap statement.
auth                   auth statement.
server                 Server Settings.
acl                    acl statement.
tcp-wrappers           tcp-wrappers statement.

 -- Imap4d Conf: namespace NAME { ... }
     Configures namespace.  The argument is one of: 'personal', 'other',
     'shared'.  The following statements (described below) are allowed
     within curly braces: 'mailbox-mode' and 'prefix'.

     See Namespace.

 -- Imap4d namespace: mailbox-mode MODE
     Configures the file mode for the mailboxes created within that
     namespace.  The syntax for MODE is:

          g(+|=)[wr]+,o(+|=)[wr]+

     See mailbox-mode.

 -- Imap4d namespace: prefix PFX { ... }
     Configures a prefix and determines its mapping to the server's file
     system.  The PFX argument is the prefix which will be visible to
     the IMAP client.  Available sub-statements are: 'directory',
     'delimiter', and 'mailbox-type'.

     See prefix.

 -- Imap4d namespace.prefix: directory PATH
     Defines the directory in the file system to which the prefix is
     mapped.

     See directory.

 -- Imap4d namespace.prefix: delimiter CHR
     Defines the folder hierarchy delimiter for the prefix.  Argument
     must be a single character.

     See delimiter.

 -- Imap4d namespace.prefix: mailbox-type TYPE
     Defines the type of the mailboxes inside that prefix.

     See mailbox-type.

 -- 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: 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 ('3.20').

     vendor
          Vendor name ('GNU').

     support-url
          The string 'http://www.gnu.org/software/mailutils'

     address
          The string '31 Milk Street, Boston, MA 02196 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.

3.17.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.

'-i'
'--inetd'
     Run in inetd mode.

'--foreground'
     Run in foreground.

'--preauth'
     Start in preauth mode

'--test'
     Run in test mode.

   See also Common Options.

3.18 Comsat Daemon
==================

Comsatd is the server which receives reports of incoming mail and
notifies users about it.  By default, it prints subject, sender name and
email, followed by first five lines of each newly arrived message to the
tty of the recipient user.  Users can customize this behavior.

3.18.1 Starting '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[FILE]'
'--test[=FILE]'
     Test mode.  In this mode, 'comsatd' takes two arguments: URL of a
     mailbox and QID of the message from that mailbox and prints the
     notification to the current user tty ('/dev/tty'), or FILE, if it
     is supplied.  If the '~/.biffrc' file exists, it will be used.  For
     example:

          $ comsatd --test /var/mail/root 34589

     Notice, that FILE is an optional argument.  When supplied, it
     should follow the short option form immediately, or the long option
     form after the equals sign, e.g.:

          $ comsatd --test=logfile /var/mail/root 34589

     or

          $ comsatd -tlogfile /var/mail/root 34589

'--foreground'
     Don't detach from the controlling terminal, remain in foreground.

   See also Common Options.

3.18.2 Configuring 'comsatd'
----------------------------

Following configuration statements affect the behavior of 'comsatd':

Statement              Reference
-------------------------------------------------------------------
debug                  debug statement.
logging                logging statement.
mailbox                mailbox statement.
locking                locking statement.
acl                    acl statement.

3.18.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.

3.18.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.

3.18.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 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"

3.19 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.

3.19.1 Major differences between Mailutils MH and other MH implementations
--------------------------------------------------------------------------

  1. Sequence numbers increase monotonically;

     Message sequence numbers are used as UIDs and thus increase
     monotonically.  This means, in particular, that if your inbox has
     messages in the range 'X--Y' and you delete all messages and then
     incorporate new mail, the first incorporated message will be
     assigned sequence number 'Y + 1' (other MH implementations will
     assign '1').  If this behavior bugs you, add the following setting
     to your '.mh_profile':

          Volatile-uidnext: true

     You can always renumber your messages starting from '1' by running

          folder -pack=1

  2. UUCP addresses are not supported;

  3. Mailutils supports a set of new format specifications (see Format String Diffs);

  4. Mailutils provides a set of new profile variables (see Profile Variable Diffs);

  5. All programs recognize '--help' and '--version' options

     These options are recognized only if no other arguments are present
     in the command line.  Abbreviations are not recognized.  This makes
     Mailutils MH implementation compatible with the standard usage for
     GNU tools.

  6. Several programs behave differently (see Program Diffs);

3.19.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' (see 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' (see Reply-Regex variable) and 'isreply'
     (see 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' (see 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.

3.19.1.2 New MH Profile Variables
.................................

 -- Variable: MH Variable string Charset

     Controls the character set in which the components decoded via the
     'decode' (see 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 reply_regex function.

3.19.1.3 Differences in MH Program Behavior
...........................................

'anno'

     The prompt in interactive mode is 'Component name:', instead of
     'Enter component name:' displayed by the RAND 'anno'.

     If a '-component field' is not specified and standard input is not
     connected to a terminal, 'anno' does not display the prompt before
     reading the component from the standard input.  RAND 'anno'
     displays the prompt anyway.

'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.

'inc'
        * The '-moveto' option.  The '-moveto' option instructs 'inc' to
          move messages into another folder after incorporating them.
          This option has effect only if the '-truncate' option has also
          been specified and the underlying mailbox supports the 'move'
          operation.  Currently only 'imap' and 'imaps' mailboxes
          support it.  For example, the following command moves
          incorporated messages into the 'archive' folder:

               inc -file imaps://imap.gmail.com -moveto=archive

          The 'moveto' URL parameter can be used instead of this option,
          e.g.:

               inc -file 'imaps://imap.gmail.com;moveto=archive'

        * Multiple sources Mailutils 'inc' is able to incorporate
          messages from several source mailboxes.  These are specified
          via multiple '-file' options, e.g.:

               inc  -truncate \
                    -file 'imaps://imap.gmail.com;moveto=archived' \
                    -file pops://mail.gnu.org \
                    -file /var/mail/root

        * URL parameters The following additional parameters can be used
          in the mailbox URLs supplied with the '-file' option:

          'moveto=FOLDER'
               Moves incorporated messages into another folder.  This
               was discussed above.

          'nomoveto'
               Disables the previous '-moveto' option.

          'truncate[=BOOL]'
               Controls source mailbox truncation.  If BOOL is not given
               or it is 'yes', the mailbox will be truncated after
               successful processing.  If BOOL is 'no', the source
               mailbox will not be truncated.

'mhl'

     The 'ignores' keyword can be used in variable list.  In that case,
     if its value contains more than one component name it must be
     enclosed in double-quotes, e.g.:

          leftadjust,compwidth=9,"ignores=msgid,message-id,received"

     The above is equivalent to the following traditional notation:

          leftadjust,compwidth=9
          ignores=msgid,message-id,received

     The 'MessageName' component is not yet implemented.

     Interactive prompting is not yet implemented.

     The following format variables are silently ignored: 'center',
     'split', 'datefield'.

'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.

'pick'

     New command line option '-cflags' allows to control the type of
     regular expressions used.  The option must occur right before
     '--COMPONENT PATTERN' or equivalent construct (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...

'prompter'
       1. Prompter attempts to use GNU Readline library, if it is
          installed.  Consequently, arguments to '-erase' and '-kill'
          option must follow GNU style key sequence notation (see
          keyseq (readline)).

          If 'prompter' is built without 'readline', it accepts the
          following character notations:

          \NNNN
               Here, N stands for a single octal digit.

          ^CHR
               This notation is translated to the ASCII code 'CHR +
               0100'.

       2. Component continuation lines are not required to begin with a
          whitespace.  If leading whitespace is not present, 'prompter'
          will add it automatically.

'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.

'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 preceding the non-existent
          one.

       2. The 'rmm' utility will unlink messages, if the 'rmmproc'
          profile component has empty value, e.g.:

               rmmproc:

'scan'

     The '-file' option is not supported.  This option is present in the
     'nmh' implementation of 'scan'.

'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.

3.20 mailutils
==============

The 'mailutils' utility is a multi-purpose tool shipped with Mailutils.
It can be used for various mail and database-related tasks, as well as
an auxiliary tool for compiling and linking programs with Mailutils.

3.20.1 Invocation Syntax
------------------------

'Mailutils' is a command line tool.  Its invocation syntax is:

     mailutils [OPTIONS] COMMAND [ARGS]

   where OPTIONS are options that affect the behavior of 'mailutils' as
a whole, COMMAND instructs it what it is to do and ARGS are any
arguments the COMMAND needs in order to be executed.

   The commands are:

2047
     Decodes or encodes email message headers.
acl
     Tests Mailutils access control lists.
cflags
     Shows compiler options needed to compile with Mailutils.
dbm
     Invokes a DBM management tool.
;filter
     Applies a chain of filters to the input.
help
     Displays a terse help summary.
imap
     Invokes an IMAP4 client shell (in development).
info
     Displays information about Mailutils compile-time configuration.
ldflags
     Constructs a 'ld'(1) command line for linking a program with
     Mailutils.
logger
     Logs information using Mailutils log facility.
pop
     Invokes a POP3 client shell.
query
     Queries configuration values.
wicket
     Scans wicket for matching URLs

3.20.2 mailutils help
---------------------

The 'mailutils help' command lists all available options and command
names along with short descriptions of what each of them does.  It is
similar to the 'mailutils --help' option.

   A command name can be supplied as an argument to 'help', in which
case it will display a help page for that particular command, e.g.:

     mailutils help ldflags

   will output help for the 'ldflags' command.  It is synonymous to the
'--help' option used with that particular command, e.g.: 'mailutils
ldflags --help'.

3.20.3 mailutils info
---------------------

The 'mailutils info' command displays information about Mailutils
compile-time configuration.  In normal form its output lists a single
configuration flag per line, e.g.:

     $ mailutils info
     VERSION=2.99.93
     SYSCONFDIR=/etc
     MAILSPOOLDIR=/var/mail/
     SCHEME=mbox
     LOG_FACILITY=mail
     IPV6
     USE_LIBPAM
     HAVE_LIBLTDL
     WITH_GDBM
     WITH_GNUTLS
     WITH_GSASL

   A configuration flag can consist either of a single word, indicating
that a particular capability has been enabled at compile time, or of a
keyword/value pair delimited by an equal sign, which indicates a
particular value used by default for that feature.  For example, 'IPV6'
means that Mailutils was compiled with support for IPv6, whereas
'SYSCONFDIR=/etc' means that the default place for configuration files
is in '/etc' directory.

   Such short output is convenient for using 'mailutils info' in scripts
to decide whether it is possible to use a given feature.  To assist
human users, the '--verbose' ('-v') option is provided.  It prints a
short description next to each flag:

     $ mailutils info --verbose
     VERSION=2.99.93           - Version of this package
     SYSCONFDIR=/etc           - System configuration directory
     MAILSPOOLDIR=/var/mail/   - Default mail spool directory
     SCHEME=mbox               - Default mailbox type
     LOG_FACILITY=mail         - Default syslog facility
     IPV6                      - IPv6 support
     USE_LIBPAM                - PAM support
     HAVE_LIBLTDL              - a portable `dlopen' wrapper library
     WITH_GDBM                 - GNU DBM
     WITH_GNUTLS               - TLS support using GNU TLS
     WITH_GSASL                - SASL support using GNU SASL

3.20.4 mailutils cflags
-----------------------

The 'mailutils cflags' command shows compiler options needed to compile
a C source with Mailutils.  It is intended for use in configuration
scripts and Makefiles, e.g.:

     CFLAGS=-g -O2 `mailutils cflags`

3.20.5 mailutils ldflags
------------------------

The 'mailutils ldflags' command is a counterpart of 'cflags' which is
used for linking.  It constructs a 'ld' command line for linking a
program with Mailutils.

   When used without arguments, it outputs 'ld' arguments which would
link only with the core Mailutils library 'libmailutils', e.g.:

     $ mailutils ldflags
     -L/usr/local/lib -lmailutils

   This command accepts a number of keywords which allow to select a
particular subset of Mailutils libraries to link with.  In particular,
the argument 'all' instructs it to link in all available libraries:

     $ mailutils ldflags all
     -L/usr/local/lib -lmu_mbox -lmu_mh -lmu_maildir -lmu_imap -lmu_pop \
     -lmu_mailer -lmu_compat -lmailutils -lmu_auth -lgsasl -lgnutls -lgcrypt \
     -lldap -lgnuradius -lpam -ldl

   Other available keywords are:

mbox
     Link in the UNIX mbox format support.
mh
     Link in the MH format support.
maildir
     Link in the Maildir format support.
imap
     Link in the IMAP protocol support.
pop
     Link in the POP protocol support.
mailer
     Enable support for mailers.
sieve
     Link in the support for Sieve mail filtering language.
dbm
     Link in the support for DBM databases (libmu_dbm library).
auth
     Link in the Mailutils authentication library.
guile
     Provide Guile language bindings.
python
     Provide Python language bindings.

3.20.6 mailutils stat
---------------------

The command 'mailutils stat' shows status of a mailbox.  The name or URL
of the mailbox to operate upon is supplied in the first argument.  If
not given, the command will display status of the invoking user system
mailbox.

     $ mailutils stat
     type: maildir
     path: /var/mail/smith
     URL: /var/mail/smith
     size: 3498
     messages: 24
     recent messages: 3
     first unseen: 20
     uidvalidity: 1338543026
     next uid: 87
     access: 2016-12-15 09:15:08 +0200

   The output format is controlled by the '--format' ('-c') option.  Its
argument is the desired format string, composed of ordinary characters,
which are reporduced on standard output verbatim, backslash sequences,
and format specifiers, beginning with '%'.

   "Backslash sequences" are interpreted as in C.

   A "format specifier" consists of a leading '%' followed by a letter.
Optional ':' may occur between '%' and the letter.  Its presense
instructs the program to print the description of the corresponding
value before the value itself.

   The following format sequences are understood:

%f
     Name of the mailbox as supplied in the command line.  If 'mailutils
     stat' was used without explicit mailbox argument, '%f' is
     equivalent to '%U'.
%t
     Type of the mailbox ('mbox', 'maildir', etc.).  The description
     string is 'type'.
%p
     Path to the mailbox.  In case of remote mailboxes, it is the path
     part of the mailbox URL. Description string: 'path'.
%U
     URL of the mailbox.  Description string: 'URL'.
%s
     Size of the mailbox in octets.  Description string: 'size'.
%c
     Number of messages in the mailbox.  Description string: 'messages'.
%r
     Number of recent (unread) messages in the mailbox.  Description
     string: 'recent messages'.
%u
     Index of the first unseen message.  Description string: 'first
     unseen'.
%v
     The UIDVALIDITY value.  Description string: 'uidvalidity'.
%n
     The UID value which will be assigned to the new message to be
     incorporated into the mailbox.  Description string: 'next uid'.
%a
     Access time of the mailbox, as a number of seconds since the epoch.
%A
     Access time of the mailbox in human-readable format.

3.20.7 mailutils query
----------------------

The 'mailutils query' command queries values from Mailutils
configuration files.  It takes one or more configuration paths (see
Paths) as its arguments.  On output, it displays the values it found,
each value on a separate line.  If the requested value is a block
statement it is displayed in full.  For example, if main configuration
file contained:

     logging {
        syslog yes;
        facility mail;
     }

   Then:

     $ mailutils query .logging.syslog
     syslog yes;
     $ mailutils query .logging.syslog .logging.facility
     syslog yes;
     facility mail;
     $ mailutils query .logging
     logging {
       syslog yes;
       facility mail;
     };

   Several command line options allow to modify output format.  The
'--value' option instructs the command to output only values:

     $ mailutils query --value .logging.syslog
     yes

   The '--path' option instructs it to print full pathnames for each
value:

     $ mailutils query --path .logging.syslog
     logging.syslog: yes

   The '--program' option instructs 'mailutils' to behave as if it was
called under another program name.  For example, the following command:

     $ mailutils query --program=pop3d .server.transcript

   will return the value of the '.server.transcript' statement which the
'pop3d' utility would see.

   By default, 'mailutils query' operates on the main configuration
file.  Another configuration file can be supplied using the '--file'
('-f') option:

     $ mailutils query --file /usr/local/etc/file.conf .pidfile

3.20.8 mailutils 2047
---------------------

The 'mailutils 2047' command is a filter for decoding or encoding email
message headers formatted in accordance with RFC 2047 (see
<http://www.faqs.org/rfcs/rfc2047.html>.  By default, it operates in
encode mode and assumes the 'iso-8859-1' encoding.  If arguments are
supplied in the command line, they are treated as the text to operate
upon.  Otherwise the command acts as a UNIX filter, reading lines from
the standard input and printing results on the standard output.

   For example:

     $ mailutils 2047 'Keld Jørn Simonsen <keld@dkuug.dk>'
     =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>

   The decode mode can be requested via the '--decode' ('-d') option:

     $ mailutils 2047 --decode '=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= \
      <keld@dkuug.dk>'
     Keld Jørn Simonsen <keld@dkuug.dk>

   The '--charset' ('-c') option changes the default character set.  It
is meaningful both in decode and in encode modes.  In decode mode it
instructs the utility to convert the output to the given character set.
In encode mode it indicates the encoding of the input data, which will
be reflected in the resulting string:

     $ mailutils 2047 --charset=utf-8 'Keld Jørn Simonsen <keld@dkuug.dk>'
     =?utf-8?Q?Keld J=C3=B8rn Simonsen <keld@dkuug.dk>?=

   The '--encoding' ('-E') option can be used in encode mode to change
the output encoding.  Valid arguments for this option are:
'quoted-printable' (the default) or 'base64'.

   The '--newline' ('-n') option prints an additional newline character
after each line of output.

3.20.9 mailutils filter
-----------------------

The 'mailutils filter' command applies a chain of filters to the input.
The filters to apply and their arguments are given in the command line.
The full invocation syntax is:

      mailutils filter [OPTION] FILTER-CHAIN

   The syntax for FILTER-CHAIN in Backus-Naur form follows:

     <filter-chain> ::= <filter> | <filter-chain> "+" <filter>
     <filter> ::= <filter-spec> <ARG>*
     <filter-spec> ::= <WORD> | "~" <WORD>

where <WORD> stands for the filter name and <ARG> represents filter
arguments.  To obtain a list of known filter names, run:

     mailutils filter --list

   Filters are applied in the order of their appearance, from left to
right and operate in encode mode.  The plus sign has the same meaning as
pipe in shell.  The default mode can be changed using the '--decode'
('-d') and '--encode' ('-e') options.  Whatever the default mode is, a
'~' character before filter name reverts the mode for that filter alone.

   For example, to encode the contents of file 'file.txt' in Base64 run:

     mailutils filter base64 < file.txt

   To convert it to base64 and use CRLF as line delimiters, run:

     mailutils filter base64 + crlf < file.txt

   The following command will decode the produced output:

     mailutils filter --decode crlf + base64

   It can also be written as

     mailutils filter ~crlf + ~base64

   The following example converts the input from ISO-8859-2 to UTF-8,
quotes eventual 'From' occurring at the beginning of a line, encodes the
result in Base64 and changes line delimiters to CRLF:

     mailutils filter iconv iso-8859-2 utf-8 + from + base64 + crlf

   This final example removes UNIX-style comments from the input and
joins continuation lines:

     mailutils filter --decode inline-comment -S '#' + linecon

   Such invocation can be useful in shell scripts to facilitate
configuration file processing.

3.20.10 mailutils acl
---------------------

The 'mailutils acl' command tests Mailutils Access Control Lists.  By
default it reads ACL from the Mailutils configuration file section
'acl'.  The command takes a list of IP addresses as its arguments,
applies the ACL to each of them in turn and prints the result.

   To select the ACL to test, two options are provided.  The '--file'
('-f') option supplies the name of configuration file to read instead of
the default one.  The '--path' ('-p' option supplies the pathname (see
Paths) of the ACL section to use instead of the default '.acl'.  For
example, to test ACL in section 'server 213.130.1.232' of file
'/etc/pop3d.conf' use:

     mailutils acl --file=/etc/pop3d.conf \
            --path=/server="213.130.1.232"/acl ADDRESS

   As an example of its use, consider file 'test.conf' with the
following contents:

     acl {
             deny from 10.10.10.1;
             deny from 10.10.1.0/24;
             log from any "Connect from ${address}";
             allow from 10.0.0.0/8;
             allow from 192.168.1.0/24;
             deny from any;
     }

   Then, running 'mailutils acl --file=test.conf 127.0.0.1' you will
get:

     Testing 127.0.0.1:
     mailutils: Connect from 127.0.0.1
     127.0.0.1: deny

   More examples:

     $ mailutils acl --file=test.conf 127.0.0.1 10.10.10.1 \
              10.10.1.3 10.5.3.1 192.168.1.0 192.168.2.0
     Testing 127.0.0.1:
     mailutils: Connect from 127.0.0.1
     127.0.0.1: deny
     Testing 10.10.10.1:
     10.10.10.1: deny
     Testing 10.10.1.3:
     10.10.1.3: deny
     Testing 10.5.3.1:
     mailutils: Connect from 10.5.3.1
     10.5.3.1: accept
     Testing 192.168.1.0:
     mailutils: Connect from 192.168.1.0
     192.168.1.0: accept
     Testing 192.168.2.0:
     mailutils: Connect from 192.168.2.0
     192.168.2.0: accept

   The 'mailutils' option '--debug-level' will give you a deeper insight
into the address matching algorithm:

     $ mailutils --debug-level=acl.trace9 acl --file test.conf 127.0.0.1
     Testing 127.0.0.1:
     mailutils: Checking sockaddr 127.0.0.1
     mailutils: 1:deny: Does 10.10.10.1/255.255.255.255 match 127.0.0.1? no;
     mailutils: 2:deny: Does 10.10.1.0/255.255.255.0 match 127.0.0.1? no;
     mailutils: 3:log: Does any match 127.0.0.1? yes;
     mailutils: Expanding "Connect from ${address}";
     mailutils: Expansion: "Connect from 127.0.0.1";.
     mailutils: Connect from 127.0.0.1
     mailutils: 4:accept: Does 10.0.0.0/255.0.0.0 match 127.0.0.1? no;
     mailutils: 5:accept: Does 192.168.0.0/255.255.0.0 match 127.0.0.1? no;
     mailutils: 6:deny: Does any match 127.0.0.1? yes;
     127.0.0.1: deny

   See acl.

3.20.11 mailutils wicket
------------------------

The 'mailutils wicket' command looks up matching URLs in the Mailutils
ticket file (by default, '~/.mu-tickets') and prints them.  The URLs to
look for are supplied in the command line.

   Consider the following ticket file as an example:

     smtp://foo:bar@*
     smtp://bar:baz@gnu.org
     *://baz:qux@*
     *://quux:bar@gnu.org

   Now, running 'mailutils wicket smtp://bar@gnu.org' will show:

     smtp://bar@gnu.org: /home/USER/.mailutils-tickets:2

(where USER is your login name).  This means that this URL matches the
line 2 in your '.mailutils-tickets' file.  The 'wicket' command does not
show the actual matching line to avoid revealing eventual
security-sensitive information.  You can instruct it to do so using the
'--verbose' ('-v') option:

     $ mailutils wicket -v smtp://bar@gnu.org
     smtp://bar@gnu.org: /home/USER/.mu-tickets:2: smtp://bar:***@gnu.org

   As you see, even in that case the tool hides the actual password part
by replacing it with three asterisks.  If you are working in a secure
environment, you can tell 'mu wicket' to show passwords as well, by
supplying the '-v' option twice.

   A counterpart of '--verbose' is the '--quite' ('-q') option, which
instructs 'wicket' to suppress any output, excepting error messages.
This can be used in scripts, which analyze the 'mailutils wicket' exit
code to alter the control flow.

   The 'mailutils wicket' tool exits with code 0 if all URLs were
matched and with code 1 if some of them were not matched in the ticket
file.  If an error occurred, the code 2 is returned.

3.20.12 mailutils dbm
---------------------

The 'mailutils dbm' tool manages DBM files using 'libmu_dbm' The
invocation syntax is:

     mailutils dbm SUBCOMMAND [OPTIONS] FILE [KEYS]
or
     mailutils dbm [OPTIONS] SUBCOMMAND FILE [KEYS]

where SUBCOMMAND selects the operation mode, OPTIONS modify the tool
behavior and FILE specifies the DBM file to operate upon.  Some COMMANDs
allow for optional KEYS to be specified.

   The FILE argument can be either a DBM file name or a Database URL.

3.20.12.1 Create a Database
...........................

The 'create' subcommand and its synonym 'load' instruct the tool to
create a new database:

     mailutils dbm create file.db

   If the argument file already exists, it will be truncated prior to
adding new records to it.

   The data to populate the database with are read from the standard
input.  The 'mailutils dbm' command supports several formats for these
data, which are discussed later.  In the simplest case (a so called
'format 0.0') each input line must consist of two fields separated by
any amount of whitespace.  The first field is treated as a key and the
second one as the corresponding value.

   The usual way to read data from a file is, of course, by redirecting
the file to the standard input as in:

     mailutils dbm create file.db < input.txt

   There is also a special option for that purpose: '--file' ('-f').
Thus, the following command is equivalent to the one above:

     mailutils dbm create --file input.txt file.db

   The '--file' option has the advantage that it allows, in conjunction
with another options, for copying input file metadata (owner UID, GID
and file mode) to the created database.  For example, the following
command ensures that the created database file will have the same
metadata as the input file:

     mailutils dbm create --file input.txt --copy-permissions file.db

   The '--copy-permissions' ('-P') option is the one that does the job.

   There are also other ways to control mode and ownership of the
created database, which are described below.

   More advanced dump formats (e.g.  'version 1.0' format) carry
additional information about the file, including its original name,
ownership and mode.  If input is in one of these formats, the file name
argument becomes optional.  If it is not supplied, the name stored in
the input stream will be used.  For example, supposing that the file
'users.dump' is in format 1.0, the following command suffices to restore
the original filename, ownership, mode and, of course, data:

     mailutils dbm create --file users.dump

3.20.12.2 Add Records to a Database
...................................

The 'add' subcommand adds records to a database.  Records are read from
the standard input and must be formatted as for 'create':

     mailutils dbm add file.db

   If the argument file does not exist, it will be created.

   Adding a record with a key which is already present in the database
produces an error.  To replace existing records, use the 'replace'
subcommand instead.

   The same options that affect the behavior of 'create' apply to 'add'
and 'replace' as well, e.g.:

     mailutils dbm replace --file input.txt --copy-permissions file.db

3.20.12.3 Delete Records
........................

To delete records, use the 'delete' subcommand.  It reads a list of keys
to delete to be specified as arguments in the command line:

     mailutils dbm delete file.db foo bar

   The command above will delete from 'file.db' records with keys 'foo'
and 'bar'.

   It is not an error to attempt to delete a key that does not exist in
the database, although such use will produce a warning message.

   By default, keys are matched literally.  It is also possible to use
various pattern matching techniques, depending on the option specified.

   The '--glob' ('-G') option instructs the tool to use UNIX globbing
pattern matching.  For example, the command below will delete all keys
starting with 'foo' and ending with a decimal digit:

     mailutils dbm delete file.db 'foo*[0-9]'

(note the quoting necessary to prevent shell from interpreting the
metacharacters itself).

   Another option, '--regex' ('-R') instructs 'mailutils' to treat
supplied keys as extended regular expressions:

     mailutils dbm delete --regex file.db 'foo.*[0-9]{1,3}'

   Both options are affected by the '--ignore-case' ('-i') option, which
turns on case-insensitive matching.

   Using pattern matching to delete records can be a risky operation as
selecting a wrong pattern will lead to removing wrong records.  It is
recommended to first use the list mode described below to verify that
the patterns match the right keys.

3.20.12.4 List the Database
...........................

The 'list' command lists the content of the database:

     mailutils dbm list file.db

   By default, entire content is listed on the standard output.

   If supplied more than one command line argument, this mode treats the
rest of arguments after the database file name as the keys to look for
and lists only records with these keys:

     $ mailutils dbm list file.db foo bar
     foo 1
     bar 56

   The '--glob' and '--regex' options instruct the tool to use UNIX
globbing or extended regular expression matching, correspondingly.
These were described in detail above.

3.20.12.5 Dump the Database
...........................

The 'dump' subcommand dumps the database to the standard output in a
format suitable for backup or sending over the network (a version 1.0
format).

     mailutils dbm dump file.db > file.dump

   The produced file is suitable for input to the 'create' ('load')
command.  Among other uses, it provides an easy way to convert databases
between various formats supported by Mailutils.  For example this is how
to convert the database file 'file.db' to the GDBM database 'new.db':

     mailutils dbm dump file.db | mailutils dbm create gdbm://new.db

   Both 'list' and 'dump' subcommands share the same set of options.  In
fact, they are pretty similar, except that use different defaults.  The
'list' subcommand is designed to produce a human-readable output,
whereas the dump subcommand is oriented towards backup purposes.

3.20.12.6 Dump Formats
......................

As of version 3.20, 'mailutils dbm' supports two formats for dumping DBM
databases.  Both formats are line-oriented.  Comments are introduced
with a sharp ('#') sign in the column 0 of a line, followed by at least
one white space character (space or tab).  Sharp sign followed by a
colon ('#:') introduces a "pragmatic comment", which carries some
additional information to the loader.

   The "version 0.0" format is suitable for databases whose records
contain only ASCII data.  In this format, each record occupies a
separate line, which consists of the key and value separated by a single
TAB character.  Empty lines are ignored.  For example:

     $ mailutils list /etc/mail/users.db
     root    guessme
     smith   pAssword
     qed     fooBar

   The output in version 0.0 format is human readable and can be used as
input to the popauth utility (see popauth.  However, version 0.0 has
serious drawbacks.  First of all, it is not suitable for databases that
contain binary data.  Secondly, it cannot properly handle keys beginning
with a sharp sign or containing TAB.  The version 1.0 format is free
from these drawbacks.

   The "version 1.0" dump format begins with a "header" containing
important information about the file, such as its file name, ownership
and file mode.  This information is stored in pragmatic comments and
allows 'mailutils dbm load' to easily recreate an exact copy of the
file.  The following comments are defined:

#:version=1.0
     Indicates that the data that follow are in version 1.0 format.
#:filename=S
     Original database file name, without directory parts.
#:uid=N
     Owner UID.
#:user=S
     Owner name.
#:gid=N
     Owner GID
#:group=S
     Owner group name.
#:mode=O
     File mode in octal

   Following this header are actual data.  Each record is output in two
parts: key and value.  Each part begins with a '#:len=N' construct on a
line by itself, where N is the length of the data in decimal.  This line
is followed by one or more lines of the actual data, encoded in base64.
The data are formatted so that each line does not exceed 76 bytes in
length (not counting the terminating newline).  An example of this
format follows:

     # Database dump file created by GNU Mailutils 2.99.93 on
     # Tue Nov  1 13:28:03 2011
     #:version=1.0
     #:file=users.db
     #:uid=0,user=root,gid=25,group=mail,mode=640
     #:len=6
     c21pdGgA
     #:len=9
     cEFzc3dvcmQA
     #:len=5
     cm9vdAA=
     #:len=8
     Z3Vlc3NtZQA=
     #:len=4
     cWVkAA==
     #:len=7
     Zm9vQmFyAA==

3.20.12.7 Dbm Exit Codes
........................

The table below summarizes exit codes used by 'mailutils dbm':

Code           Symbolic name          Meaning
---------------------------------------------------------------------------
0              EX_OK                  Successful termination
64             EX_USAGE               Command line usage error
65             EX_DATAERR             Error in user-supplied data: the
                                      input file is badly formatted, or
                                      some of the data supplied in the
                                      command line are invalid (e.g.
                                      user name, uid or the like), etc.
66             EX_NOINPUT             Cannot open input file
67             EX_NOUSER              No such user or UID when trying to
                                      set output file ownership
69             EX_UNAVAILABLE         Operation cannot be performed due
                                      to some kind of problem (e.g.
                                      access to the file denied, etc.)
70             EX_SOFTWARE            Internal software error
74             EX_IOERR               Input/output error

3.20.13 mailutils logger
------------------------

The 'mailutils logger' tool logs information using Mailutils log
facility.

   Syntax:

     mailutils logger [OPTIONS] [MESSAGE]

   The MESSAGE argument, if supplied, gives the text to log.  If not
supplied, the utility reads lines of text from standard input or a file
(if the '--file' option is given) and sends them to log:

     # Send text to log
     $ mailutils logger I am here
     # Log each line from file.txt
     $ mailutils logger --file file.txt
     # Read stdin and log it:
     $ mailutils logger

   The default logging channel is bound to standard error.  To bind it
to syslog, use the '--syslog' command line option.  In that case
'mailutils' uses facility 'user' and priority 'err'.  You can change
this by using the '--priority' ('-p') option.  Its argument is either a
syslog facility name or facility and severity names separated by a dot.
For example, the following invocation will use facility 'auth', severity
'info':

     mailutils logger --priority auth.info

   The syslog tag can be set using the '--tag' ('-t') option:

     mailutils logger --tag myprog

   The default tag is 'mu-logger'.

   The '--severity' ('-s') option sets the Mailutils severity level.
Its argument can be any of the following: 'debug', 'info', 'notice',
'warning', 'error', 'crit', 'alert', 'emerg'.

   Finally, the '--locus' ('-l') option binds log messages to a location
in a file.  Its argument has the following syntax:

     FILE:LINE[:COL]

where FILE is the file name, LINE is the line number and optional COL is
the column number in that file.

   For example, the following invocation:

     mailutils logger --locus mailutils.conf:34 Suspicious statement

   will send the following to the log:

     mu-logger: mailutils.conf:34: Suspicious statement

3.20.14 mailutils pop
---------------------

The 'mailutils pop' command invokes an interactive POP3 client shell.
It reads commands from the standard input, executes them and displays
the results on the standard output.  If the standard input is connected
to a terminal, the readline and history facilities are enabled (provided
that Mailutils is configured with GNU Readline).

   The 'mailutils pop' commands form two major groups.  POP3 protocol
commands interact with the remote POP3 server and display responses
obtained from it.  These commands are named after their POP3
equivalents.  Another group, "internal commands", are used to configure
the shell itself.

POP protocol commands
.....................

connect [-tls] HOSTNAME [PORT]
     Open connection to HOSTNAME.  If the '-tls' option is given, TLS
     encryption (also known as POPS protocol) will be used.  If PORT
     argument is not given, the command uses port 110 for a plain POP
     connection or 995 for POPS (if '-tls' is given).

stls
     Start TLS negotiation.  This command is valid only after successful
     unencrypted connection has been initiated (using 'connect' without
     '-tls' argument).

user NAME
     Send user name to the server.  The 'pass' command must follow.

pass [PASSWORD]
     Send password.  This command is valid only after 'user'.  If the
     PASSWORD argument is omitted, the shell will ask you to enter it.
     While entering, both echoing and history recording will be
     disabled.  Use this to avoid compromising your password.

apop USER [PASSWORD]
     Authenticate with APOP. If the PASSWORD argument is omitted, you
     will be asked to supply it.  While entering, both echoing and
     history recording will be disabled.

capa [-reread] [NAME...]
     List server capabilities.  Any number of arguments is accepted.  If
     given, the shell will display only the named capabilities,
     otherwise it displays entire list.  By default 'capa' reuses the
     response of its previous invocation (if there was any), instead of
     resending the 'CAPA' command to the server.  To force it do so, use
     the '-reread' option.

noop
     Send a 'NOOP' ("no operation") command to the server.

stat
     Get the mailbox size and number of messages in it.

uidl [NUMBER]
     Shows unique message identifiers.  Without arguments, shows
     identifiers for each message in the mailbox.  If NUMBER is given,
     the command returns the UIDL of that particular message only.

list [NUMBER]
     Lists messages.  See above for the meaning of NUMBER.  Each line of
     the produced listing contains describes a single message and
     contains at least the message number and size in bytes.  Depending
     on the POP3 server implementation, additional fields may be
     present.  For example, Mailutils 'pop3d' can also output number of
     lines in the message in the additional third field.

retr NUMBER
     Retrieve a message.

top MSGNO [NUMBER]
     Display message headers and first NUMBER (default 5) of lines of
     its body.

dele NUMBER
     Mark message for deletion.

rset
     Remove deletion marks.

quit
     Quit pop3 session.

disconnect
     Close existing connection.

Internal commands
.................

verbose [on|off|mask|unmask] [secure [payload]]
     Control output verbosity.  Without arguments the 'verbose' command
     shows current settings.

     The argument 'off' (the default) turns off all additional output.
     The 'verbose on' command enables POP3 protocol tracing output.
     Additional arguments can be used to provide more verbosity.  The
     'secure' argument enables display of user passwords in the trace
     output and the 'payload' argument enables showing payload data
     (e.g.  response body sent in the reply to 'RETR' command, etc.)
     Thus, the full diagnostics output is obtained by

          verbose on secure payload

     The 'mask' and 'unmask' arguments allow to disable and enable such
     additional verbosity.  For example, supposing the command above is
     in action, the following command will suppress the display of user
     passwords in the traces:

          verbose mask secure

     Similarly, 'verbose unmask secure' will turn it back again.

prompt STRING
     Set command prompt.  The argument can contain "variable references"
     in any of the following forms:

          $NAME
          ${NAME}

     where NAME is the variable name.  Such references are expanded to
     the actual value of the variable at the time of expansion.  The
     following variables are defined:

     Variable                      Expansion
     --------------------------------------------------------------------------
     user                          Login name of the authenticated POP3
                                   user.  If the session is not
                                   authenticated yet, expands to '[nouser]'.
     host                          Name of the remote host, or '[nohost]' if
                                   no connection is established.
     program-name                  Name of the program, as typed on the
                                   command line to invoke it.
     canonical-program-name        'mailutils'
     package                       'Mailutils'
     version                       Mailutils version number (3.20)
     status                        Session status.  One of: 'disconnected',
                                   'connected' or 'logged in'.

     For example:

          prompt "[${user}@$host "

     Notice the use of quotes to include the space character in the
     prompt.

exit
     Exit the program.

help [COMMAND]
? [COMMAND]
     Without arguments displays a list of commands with possible
     arguments and short descriptions.

     With one argument, displays a terse description for the given
     COMMAND.

history
     Shows command history.

3.20.15 mailutils imap
----------------------

The 'mailutils imap' command invokes an interactive IMAP4 client shell.
It reads commands from the standard input, executes them and displays
the results on the standard output.  The shell is similar to the
'mailutils pop' (see mailutils pop) shell.

IMAP protocol commands
......................

Most commands in this group correspond (with minor differences) to IMAP
commands described in RFC 3501(1).

 -- imap command: connect [-tls] HOST [PORT]
     Opens connection to the server HOST.  If the '-tls' option is
     given, TLS encryption (also known as IMAPS protocol) will be used.
     If PORT argument is not supplied, the command uses port 143 for a
     plain IMAP connection or 993 for IMAPS (if '-tls' is given).

 -- imap command: capability [-reread] [NAME...]
     Lists server capabilities.  Any number of NAMEs is accepted.  If at
     least one is given, the shell will display only the named
     capabilities, otherwise it displays the entire list.  By default,
     'capability' reuses the response of its previous invocation (if
     there was any), instead of resending the CAPABILITY command to the
     server.  To force it do so, use the '-reread' option.

 -- imap command: starttls
     Starts TLS negotiation.  This command is valid only after
     unencrypted connection has been successfully initiated using
     connect without the '-tls' option.

 -- imap command: login USER [PASSWORD]
     Logs in to the server as USER with optional PASSWORD.  If the pass
     argument is omitted, the shell will ask you to enter it.  While
     entering, both echoing and history recording will be disabled.  Use
     this to avoid compromising your password.

 -- imap command: logout
 -- imap command: quit
     Quits the imap session.

 -- imap command: id [-test KW] [ARG...]
     Sends IMAP ID command.  See RFC 2971(2), for a discussion of
     arguments.  By default, this command outputs entire ID list.  If,
     however, the '-test' option is given, it will check whether the
     keyword KW is defined and display its value if so.

 -- imap command: check
     Requests a server checkpoint.

 -- imap command: select [MBOX]
     Selects the named mailbox.  Without argument, selects 'INBOX'.

 -- imap command: examine [MBOX]
     Examines the named mailbox, i.e.  selects it in read-only mode.  If
     MBOX is not given, 'INBOX' is assumed.

 -- imap command: status MBOX KW [KW...]
     Gets mailbox status.  Valid keywords (KW arguments) are:
     'MESSAGES', 'RECENT', 'UIDNEXT', 'UIDVALIDITY', and 'UNSEEN'.
     Keywords are case-insensitive.

 -- imap command: fetch MSGSET ITEMS
     Fetches message data.  See RFC 3501, section 6.4.5(3), for a
     discussion of its arguments.

 -- imap command: store MSGSET ITEMS
     Alters mailbox data.  See RFC 3501, section 6.4.6(4), for a
     discussion of its arguments.

 -- imap command: close
     Closes the currently selected mailbox (with expunge).

 -- imap command: unselect
     Closes the currently selected mailbox (without expunge).

 -- imap command: delete MBOX
     Deletes the mailbox MBOX.

 -- imap command: rename OLD-NAME NEW-NAME
     Renames existing mailbox OLD-NAME to NEW-NAME.

 -- imap command: expunge
     Permanently removes messages marked for deletion.

 -- imap command: create NAME
     Creates new mailbox with the given NAME.

 -- imap command: append [-time DATETIME] [-flag FLAG] MAILBOX FILE
     Reads an RFC-822 message from FILE and appends it to the MAILBOX.
     Use the '-time' option to supply envelope date for the message.
     Use the '-flag' option to supply message flags.  For example:

          append -time "25-Aug-2002 18:00:00 +0200" -flag \Seen INBOX input.msg

 -- imap command: list REF MBOX
     Lists matching mailboxes.  See RFC 3501, section 6.3.8(5), for a
     discussion of its arguments.

 -- imap command: lsub REF MBOX
     Lists subscribed mailboxes (RFC 3501, section 6.3.9(6)).

 -- imap command: subscribe MBOX
     Subscribes to a mailbox.

 -- imap command: unsubscribe MBOX
     Removes mailbox MBOX from the subscription list.

 -- imap command: noop
     Sends a "no operation" command.

 -- imap command: disconnect
     Closes existing connection.

Internal commands
.................

The 'imap' shell implements the same set of internal commands as 'pop'
shell: Internal commands.  There is only one
imap-specific internal command:

 -- imap command: uid [on|off]
     Controls the UID mode.  When the UID mode is on, the commands
     'fetch' and 'store' operate on and return message UIDs instead of
     their sequence numbers.

     To examine the current state of the UID mode, issue the 'uid'
     command without arguments.

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

   (1) See <http://www.faqs.org/rfcs/rfc3501.html>.

   (2) <http://www.faqs.org/rfcs/rfc2971.html>

   (3) <http://tools.ietf.org/html/rfc3501#section-6.4.5>

   (4) <http://tools.ietf.org/html/rfc3501#section-6.4.6>

   (5) <http://tools.ietf.org/html/rfc3501#section-6.3.8>

   (6) <http://tools.ietf.org/html/rfc3501#section-6.3.9>

3.20.16 mailutils send
----------------------

Reads an RFC-822 message from a file and sends it over to a specified
SMTP server.  The syntax is:

     mailutils send [OPTIONS] HOST FILE

where HOST defines the SMTP server through which to send the message,
and FILE is the name of the input file containing the message.  For
example, to send a message from file 'input.msg' using SMTP service at
localhost, one would write:

     $ mailutils send localhost input.msg

   The HOST argument can be an IP address, hostname, or a valid SMTP
URL.

   The following command line options are understood:

'-F ADDRESS'
'--from=ADDRESS'
     Supplies envelope sender address.

'-T ADDRESS'
'--rcpt=ADDRESS'
     Supplies envelope recipient address.  It can be specified multiple
     times.

'-t'
'--read-recipients'
     Instructs the program to read recipient email addresses from the
     message 'To:', 'Cc:', and 'Bcc:' headers.

3.20.17 mailutils smtp
----------------------

The 'mailutils smtp' command invokes an interactive SMTP client shell.
It reads commands from the standard input, executes them and displays
the results on the standard output.  If the standard input is connected
to a terminal, the readline and history facilities are enabled (provided
that Mailutils is configured with GNU Readline).

Initializing connection
.......................

 -- smtp command: connect [-tls] HOST [PORT]
     Connects to SMTP server at HOST (IP address or host name).  If the
     '-tls' option is given, TLS encryption (also known as SMTPS
     protocol) will be used.  The default port number is 25 for plain
     SMTP and 465 for SMTPS. Explicit PORT argument overrides the
     default value.

Connection parameters
.....................

A number of parameters is associated with an open connection:

domain
     Domain name used in EHLO statement.  Defaults to the current host
     name.

   The following parameters are used for ESMTP authentication:

username
     User name.
password
     User password.
service
     GSASL service name.
realm
     Realm name.
host
     Host name.
url
     SMTP URL. It can contain all of the above.  Default is smtp://

   These parameters are manipulated using the following statements:

 -- smtp command: set PARAM VALUE [PARAM VALUE...]
     Sets parameter PARAM to VALUE.  Several parameters can be set with
     one 'set' statement.

 -- smtp command: clear [PARAM...]
     Unset the supplied connection parameters.  If used without
     arguments, unsets all parameters.

 -- smtp command: list [PARAM...]
     Lists the values of the connection parameters.  If used without
     arguments, lists all parameters.

SMTP commands
.............

 -- smtp command: ehlo [DOMAIN]
     Sends the ESMTP greeting.  Unless DOMAIN is supplied, the
     connection parameter 'domain' is used.

 -- smtp command: capa [NAME...]
     Lists the server capabilities.

 -- smtp command: starttls
     Initiates encrypted connection.  This command is disabled if the
     connection is opened with the '-tls' option.

 -- smtp command: auth MECH [MECH...]
     Authenticate using the supplied mechanisms.

 -- smtp command: rset
     Reset the session state.

 -- smtp command: from [EMAIL]
     Sets sender email address.  If used without arguments, prints the
     sender email address.

 -- smtp command: to [EMAIL]
     Sets recipient email address.  If used without arguments, prints
     all recepient names collected so far.

 -- smtp command: smtp COMMAND [ARGS...]
     Sends the COMMAND with its arguments verbatim.

 -- smtp command: quit
     Quits the SMTP session.

 -- smtp command: send [FILE]
     Reads the message from FILE and sends it.  If FILE is not supplied,
     the action depends on whether a 'send' command was used prevously
     within the same session.  If so, 'mailutils' will first ask whether
     to reuse the already supplied message.  If not, it will start an
     editor, allowing you to enter the new message.  When you exit from
     the editor, you will be prompted what to do with the message: send,
     edit, or quit (discard) it.

Internal commands
.................

Internal commands are the same as in 'pop' shell: Internal commands.

3.20.18 mailutils maildir_fixup
-------------------------------

This command fixes attributes and UID assignments in 'maildir' mailboxes
created by mailutils versions prior to 3.10.90.

   Attribute flags used in 'maildir' mailboxes by these versions of
mailutils were a bit different from those described in the original
description of the 'maildir' format(1) and those used by another
implementations.  The discrepancy has been reported in the Mailutils bug
tracker(2) and was fixed in version 3.10.90.  Along with this fix,
measures has been taken to ensure persistence of UID assignments between
different sessions.  Starting from version 3.10.90, whenever 'mailutils'
library opens a maildir mailbox, it determines the version that created
it.  If the mailbox is writable and the library determines that the
mailbox is affected by the two problems described above, it fixes the
mailbox on the fly.  This process is completely transparent to the user.

   If you operate a site with a large number of mailboxes in 'maildir'
formats, you may choose to fix up all of them at once.  That's what the
'maildir_fixup' command is for.  It takes one or more directory names as
its arguments and recursively scans these directories in search for
'maildir' mailboxes.  Each mailbox found is analyzed and a fix-up is
performed, if necessary.  If a mailbox is already in the new format, it
remains untouched.

   The following options modify the program's behavior:

'-v'
'--verbose'
     List each maildir name before processing it.

'-n'
'--dry-run'
     Don't touch maildirs, just print their names,

   The 'maildir_fixup' tool reads main mailutils configuration file by
default.  It looks for program-specific settings in the section 'program
maildir_fixup'.  If the 'include' statement is present that has a
directory name as its argument, the file 'maildir_fixup' is looked up in
that directory and parsed, if present.

   The program uses the following configuration statements:

Statement              Reference
-------------------------------------------------------------------
debug                  debug statement.
locking                locking statement.
mandatory-locking      See mandatory-locking statement.

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

   (1) <http://cr.yp.to/proto/maildir.html>

   (2) <http://savannah.gnu.org/bugs/?56428>

3.21 dotlock
============

A stand-alone mailbox-locking utility.  It is the default program used
by 'mailutils' if the 'locking.type' configuration statement is set to
'external' (see external locking type).

   The program usage syntax is:

     # To lock MBOX:
     dotlock OPTIONS MBOX
     # To unlock it:
     dotlock -u OPTIONS MBOX

   By default the program implements the 'dotlock' locking (see
dotlock locking type).  This can be changed either in the
configuration file, or via the command line options.

   The following common configuration statements affect the behavior of
'dotlock':

Statement              Reference
-------------------------------------------------------------------
debug                  Debug Statement.
locking                Locking Statement.

   The program understands the following command line options:

'-d'
'--debug'
     Print details of failure reasons to stderr.

'-f[N]'
'--force[=N]'
     If a lock file exists and is more than N minutes old, forcibly
     remove it and re-lock the mailbox.  Default N is 10 minutes.

'-p'
'--pid-check'
     Check if the PID of lock owner is still active.  If not, break the
     lock.

'-r N'
'--retry=N'
     Number of times to retry acquiring the lock, if it is held by
     another process.  The default is 10 times.

'-t N'
'--delay=N'
     Sets delay in seconds between two successive locking attempts.  The
     default is 1 second.

'-u'
'--unlock'
     Unlock the mailbox.

4 Mailutils Libraries
*********************

  ==================================================================
                           *Editor's note:*
     This node is to be written.
  ==================================================================

5 Sieve Language
****************

The input language understood by the GNU Sieve Library is a superset of
the Sieve language as described in RFC 3028.

5.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
     (see 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 libmu_sieve 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"];

5.2 Syntax
==========

Being designed for the sole purpose of filtering mail, Sieve has a very
simple syntax.

5.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" (see
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.

5.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 the user to extend this set using loadable actions.  See
Actions, for detailed discussion of actions.

5.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 executes 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 selects 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.

5.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 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;
       }

5.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'.

5.3.1 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.

5.3.2 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 (see library-path).

5.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 libmu_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. 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, 'libmu_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, 'libmu_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.  'libmu_sieve' then issues the
     following diagnostic message:

          source for the required action NAME is not available

5.5 Comparators
===============

GNU libmu_sieve 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.

5.6 Tests
=========

This section describes the built-in tests supported by GNU libmu_sieve.
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 (see Require Statement).

5.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

5.6.2 External Tests
--------------------

 -- 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
     matches 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: 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: pipe [:envelope] [:header] [:body] [:exit CODE(number)]
          [:signal CODE(number)] COMMAND(string)

     Synopsis:
          require "test-pipe";

          if pipe COMMAND
            {
              ...
            }

     Description: The 'pipe' test executes a shell command specified by
     its argument and pipes the entire message (including envelope) to
     its standard input.  When given, tags ':envelope', ':header', and
     ':body' control what parts of the message to pipe to the command.

     In the absence of the ':exit' tag, the test returns true if the
     command exits with code 0.  If ':exit' is given, the test returns
     true if the command exits with code equal to its argument.

     The ':signal' tag determines the result of the test in case if the
     program exits on signal.  By default, the test returns false.  If
     ':signal' is given and the number of signal which caused the
     program to terminate matches its argument, the test returns true.

 -- 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' selects 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: 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.  See 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;
            }

 -- Test: uidnew [ :db DBNAME(string) ] [ :mailbox MBNAME(string) ]

     Synopsis:
          if uidnew
            {
               ...
            }

     Description: This test evaluates to true if the current message has
     never been processed before.  It is designed for use in cases where
     the processed messages are retained in the mailbox (see keep).

     For each processed mailbox, the test keeps its "state", which
     consists of the mailbox "uidvalidity" and last processed UID. The
     states are stored in the GDBM database '.uidnew.db' in the user
     home directory.  The name and type of the database file can be
     changed using the ':db' tagged argument.  Its value is either the
     pathname to the database file, or its URL. The tilde ('~')
     character followed by the slash appearing at the start of the
     pathname expands to the user home directory.  A tilde followed by
     the username and a slash, expands to the home directory of that
     user.  For example:

          if uidnew :db gdbm://~/uidstate.db
            {
               fileinto "store";
               keep;
            }

     The ':mailbox' agrument supplies the key value under which the
     mailbox state is stored.  By default, full URL of the current
     mailbox is used.  This argument can be useful when the mailbox name
     is not available, e.g.  if processing a single message ('sieve -f
     -').

5.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
(see Require Statement).

5.7.1 Built-in Actions
----------------------

The GNU libmu_sieve 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.

5.7.2 External Actions
----------------------

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 (see Require Statement).

 -- Action: moderator [:keep] [:address ADDRESS(string)] [:source
          SIEVE-FILE(string)] [:program SIEVE-TEXT(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.

     If the ':source' tag is given, its argument specifies a Sieve
     source file to be used on the message.  Otherwise, if ':program' is
     given, its argument supplies a Sieve program to be used on this
     message.  At most one of these tags may be specified.  Supplying
     them both, or supplying several instances of the same tag, is an
     error.  The behavior of the action in this case is undefined.

     If neither ':program' nor ':source' is given, 'moderator' will
     create a copy of the existing Sieve machine and use it on the
     message.

     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] [:header] [:body] COMMAND(string)

     Synopsis:
          require "pipe";

          pipe COMMAND

     Description: The 'pipe' action executes a shell command specified
     by its argument and pipes the entire message (including envelope)
     to its standard input.  When given, tags ':envelope', ':header',
     and ':body' control what parts of the message to pipe to the
     command.

     Example: The example below uses the 'putmail' utility (see
     putmail) to forward the message to user 'gray' on the machine
     'mail.gnu.org'.

          require "pipe";

          pipe "/usr/bin/putmail smtp://gray@mail.gnu.org"

 -- Action: vacation [:days NDAYS(number)] [:subject SUBJECT(string)]
          [:aliases ADDRLIST(string-list)] [:noreply
          NOREPLY-ADDRESS(string-list)] [:reply_regex EXPR(string)]
          [:reply_prefix PREFIX(string)] [:sender EMAIL(string)]
          [:database PATH(string)] [:return_address EMAIL(string)]
          [:header HEADERS(string-list)] [:mime] [:always_reply]
          [:rfc2822] [:file] TEXT(string)

     Syntax:
          require "vacation";
          vacation ARGS;

     Description: The 'vacation' action returns a message with TEXT to
     the sender.  It is intended to inform the sender that the recipient
     is not currently reading his mail.

     If the ':file' tag is present, TEXT is treated as the name of the
     file to read the body of the reply message from.  When used
     together with tag ':rfc2822', the file should be formatted as a
     valid RFC 2822 message, i.e.  headers followed by empty line and
     body.  Headers may not contain 'To', 'From', and 'Subject', as
     these will be generated automatically.

     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 the 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: *'.

     Another headers can be added using the ':header' tag.  Its argument
     is a list of header strings, each one having the form
     '"NAME:VALUE"'.  Additional whitespace is allowed on both sides of
     the colon.

     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 ':noreply' 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 file '.vacation' stored in the user's home
     directory.  The file name can be changed using the ':database' tag.

     The tag ':always_reply' instructs vacation to respond to the
     message regardless of whether the user email is listed as a
     recipient for the message.

5.8 Extensions
==============

The following extensions are implemented

5.8.1 The encoded-character extension
-------------------------------------

The 'encoded-character' extension complies with 'RFC 5228', part
2.4.2.4.  It provides a way of incorporating multibyte sequences in a
Sieve script using only ASCII characters.  This is a built-in extension.
It is enabled using the following statement:

     require "encoded-character";

   When this extension is enabled, the sequences '${hex: ...}', and
'${unicode: ...}' can appear inside of quoted strings.

   The sequence

     ${hex: XX}

where XX is a sequence of one or two-digit hex numbers separated by any
amount of whitespace, is replaced with the octets with the hexadecimal
values given by each hex number.  For example,

     "${hex: 24 24}" => "$$"

   Thus, the following script will discard any message containing three
contiguous dollar signs in its 'Subject' header:

     require "encoded-character";

     if header :contains "Subject" "$${hex:24 24}" {
          discard;
     }

   The 'hex:' keyword is case-insensitive.  If XX contains invalid hex
numbers, the entire sequence is left verbatim.  This is illustrated by
the following example:

     "$${hex:40}"         => "$@"
     "${hex: 40 }"        => "@"
     "${HEX: 40}"         => "@"
     "${hex:40"             => "${hex:40"
     "${hex:400}"         => "${hex:400}"
     "${hex:4${hex:30}}"  => "${hex:40}"

   The sequence

     ${unicode: HEXNUM}

where HEXNUM is a list of hexadecimal numbers separated with whitespace,
will be replaced by the UTF-8 encoding of the specified Unicode
characters, which are identified by the hexadecimal value of HEXNUM.
For example, the following string represents a single '@' sign:

     "${UNICODE:40}"

   Similarly to 'hex:', the 'unicode:' indicator is case insensitive.
The following examples demonstrate the handling of several valid and
invalid encodings:

     "${unicode:40}"      => "@"
     "${ unicode:40}"     => "${ unicode:40}"
     "${UNICODE:40}"      => "@"
     "${UnICoDE:0000040}" => "@"
     "${Unicode:40}"      => "@"
     "${Unicode:Cool}"    => "${Unicode:Cool}"
     "${unicode:200000}"  => error
     "${Unicode:DF01}     => error

5.8.2 The relational extension
------------------------------

The 'relational' extension complies with 'RFC 3431'.  It is a built-in
extension.  When enabled, the two new match types become available:
':count' and ':value'.  Both keywords take a single argument defining
the relational operator to use:

'"gt"'         greater than ('>')
'"ge"'         greater than or equal ('>=')
'"lt"'         less than ('<')
'"le"'         less than or equal ('<=')
'"eq"'         equal to ('==')
'"ne"'         not equal to ('!=')

   The ':value' keyword requires a relational comparison between
strings.  The left side of the relation is formed by the value from the
message.  The right side of the relation is the value from the test
expression.  If there are multiple values on either side or both sides,
the test is considered true if any pair is true.  For example,

     require ["relational", "fileinto"];

     if header :value "gt" :comparator "i;ascii-numeric"
                     ["x-spam-level] ["5"]
     {
       fileinto "spam";
     }

   The ':count' keyword counts the specified entities in the message and
compares their number with the value given in the test expression.  The
latter must be a list of one element.  This match type can only be used
with numeric comparators.  For example, the following script will
discard any message with 10 or more recipient addresses in the 'To' and
'Cc' headers:

     require "relational";

     if address :count "ge" :comparator "i;ascii-numeric"
                           ["to", "cc"] ["10"]
     {
         discard;
     }

5.8.3 The variables extension
-----------------------------

The 'variables' extension is defined in 'RFC 5229'.  It is a built-in
extension.  It introduces support for variables in Sieve scripts.

   There are two kind of variables: user-defined and match variables.

   A "user-defined" variable is initialized using the 'set' action:

 -- Action: set [MODIFIERS] NAME(string) VALUE(string)
     Stores the specified VALUE in the variable identified by NAME.
     Optional MODIFIERS are applied on VALUE before it is stored in the
     variable.

     The following modifiers are available:

     ':lower'
          Convert value to lower case letters.
     ':upper'
          Convert value to upper case letters.

     ':lowerfirst'
          Convert the first character in value to lower case.

     ':upperfirst'
          Convert the first character in value to upper case.

     ':quotewildcard'
          Quote wildcard characters ('*', '?', '\') by prefixing each
          occurrence with a backslash ('\').  This can be used to ensure
          that the variable will only match a literal occurrence if used
          as a parameter to ':matches'.

     ':length'
          The value is the decimal number of characters in the
          expansion, converted to a string.

     When several modifiers are present, they are applied in the
     following order of precedence (largest value first):

     precedence     modifiers
     --------------------------------------------------------------------------
     40             ':lower' or ':upper'
     30             ':lowerfirst' or ':upperfirst'
     20             ':quotewildcard'
     10             ':length'

     Modifiers having the same precedence (i.e.  listed on the same row
     in the above table) cannot be used together.

   Variables are referenced within text strings using the construct
'${NAME}', where NAME is the name of the variable as it appeared in the
first parameter to the 'set' statement.  For example:

     require "variables";

     set "sender" "root
     ":

     if envelope :matches "${sender}"
     {
        ...
     }

   "Match variables" refer to parts of the most recently evaluated
successful match of type ':matches' or ':regex'.  They have names
consisting entirely of decimal digits.  The variable '${0}' refers to
the entire matched expression.  The variable '${1}' refers to the
substring matching the first occurrence of the wildcard ('?' and '*'),
'${2}' refers to the second occurrence and so on.  The wildcards match
as little as possible (non-greedy matching).  For example:

     require ["variables", "fileinto"];

     if header :matches "List-ID" "*<*
     " {
        fileinto "INBOX.lists.${2}";
        stop;
     }

   If ':regex' match is used, the match variables starting from '${1}'
refer to the substrings of the argument value matching subsequent
parenthesized groups of the regular expression.

 -- Test: string [COMPARATOR] [MATCH-TYPE] SOURCE(string-list)
          KEYS(string-list)
     The 'string' test compares two strings according to the selected
     comparator and match type.  The test evaluates to 'true' if any two
     strings from SOURCE and KEYS match.

     The ':count' match used in 'string' counts each empty string as 0,
     and each non-empty one as 1.  The count of a string list is the sum
     of the counts of the member strings.

5.8.4 environment
-----------------

The 'environment' extension complies with 'RFC 5183'.  It is a built-in
extension.  It introduces the following test:

 -- Test: environment [COMPARATOR] [MATCH-TYPE] NAME(string)
          KEYS(string-list)
     The 'environment' test evaluates to 'true' if the value of the
     environment items NAME matches any string from KEYS.

   The following environment items are defined:

domain
     The primary DNS domain of the machine where the Sieve script is
     executing.

host
     The fully-qualified domain name of the host where the Sieve script
     is executing.

location
     Type of service that is evaluating the script.  Depending on the
     utility that is evaluating the script it is:

     Utility                                     Location
     --------------------------------------------------------------------------
     sieve                                       '"MUA"', or set with the
                                                 '--environment' option.
     maidag                                      '"MDA"'
     inc                                         '"MUA"'

name
     The string 'GNU Mailutils'

phase
     The point relative to final delivery where the Sieve script is
     being evaluated.  Depending on the utility that is evaluating the
     script it is:

     Utility                                     Location
     --------------------------------------------------------------------------
     sieve                                       'post' unless set with the
                                                 '--environment' option.
     mda                                         '"during"'
     inc                                         '"post"'

version
     Mailutils version string (e.g.  '3.20').

5.8.5 The numaddr extension
---------------------------

This is an example loadable extension.  See numaddr.

5.8.6 The editheader extension
------------------------------

The 'editheader' extension complies with 'RFC 5293'.  It provides the
following actions:

 -- Action: addheader [:last] FIELD-NAME(string) VALUE(string)
     Adds a header field to the existing message header.  By default the
     header is inserted at the beginning of the header list.  If the tag
     ':last' is specified, it is appended at the end.

 -- Action: deleteheader" [:index FIELDNO(number) :last] [COMPARATOR]
          [MATCH-TYPE] FIELD-NAME(string) [VALUE-PATTERNS(string-list)]

     Deletes occurrences of the header field matching the criteria.

     The VALUE-PATTERNS, if specified, determines which occurrences of
     the header fielde to delete.  If not supplied, COMPARATOR and
     MATCH-TYPE are silently ignored.

     If ':index FIELDNO' is specified, only the numbered occurrence of
     the named header field will be matched (header numbering begins at
     1), If ':last' is specified, the count is backwards; 1 denotes the
     last named header field, 2 the second to last, and so on.  The
     counting happens before the VALUE-PATTERNS match, if any.  Thus,
     e.g.  the action

          deleteheader :index 1 :contains "Delivered-To" "bob@example.com";

     would delete the first 'Delivered-To' header field if it contains
     the string 'bob@example.com'.

5.8.7 The list extension
------------------------

See list.

5.8.8 The moderator extension
-----------------------------

A loadable extension implementing a moderator robot for Mailman-driven
mail archives.  See moderator.

5.8.9 The pipe extension
------------------------

A loadable extension for external command execution.  It provides the
'pipe' action (see pipe) and test (see pipe).

5.8.10 The spamd extension
--------------------------

Implements a test which interfaces to SpamAssassin filter.  This is a
loadable extension.  See spamd.

5.8.11 The timestamp extension
------------------------------

The loadable extension 'timestamp' implements a test for comparing the
value of a structured date header field with the given date.

   Note: this extension will probably phase away in favor of the 'date'
Sieve extension ('RFC 5260').

5.8.12 The vacation extension
-----------------------------

The loadable extension 'vacation' provides the action intended to inform
the sender that the recipient is not currently reading his mail.

   See vacation.

5.9 GNU Extensions
==================

This section summarizes the GNU extensions to the sieve language

  1. Multiline strings syntax

     GNU libmu_sieve 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 for interspersing the 'require' and other
          statements.  The only requirement is that 'require' must occur
          before a statement that is using the required capability
          (see 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

     In case the optional argument (:over|:under) is omitted, 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

     It is possible to specify permissions on the mailbox, in case it
     will be created (see 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.

6 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>.

7 Getting News About GNU Mailutils
**********************************

The two places to look for any news regarding GNU Mailutils are the
Mailutils homepage at <http://mailutils.org> or
<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://mailutils.org/manual>.  See also Mailutils Wiki
(http://mailutils.org/wiki) for the latest updates.

8 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>,
   * François Pinard <pinard@IRO.UMontreal.CA>.
   * Jordi Mallach <jordi@sindominio.net>
   * Wojciech Polak <polak@gnu.org>

Appendix A References
*********************

  ==================================================================
                           *Editor's note:*
     This node is to be written.
  ==================================================================

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
(see 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 (see 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.  See Specifying the Time Zone with 'TZ' (libc).

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 François Pinard
(<pinard@iro.umontreal.ca>) from the 'getdate.y' source code, and then
edited by K. Berry (<kb@cs.umb.edu>).

Appendix C Date/time Format String
**********************************

This appendix documents the format specifications for outputting
date/time values.  It is used, in particular, by the 'mail' utility
(see headline).

   Essentially, it is a reproduction of the man page for GNU 'strftime'
function.  Some of the conversion specifiers might not be available on
all systems, due to differences in 'strftime' between systems.  If
unsure, please consult strftime (strftime(3).

   Ordinary characters placed in the format string are reproduced
without conversion.  Conversion specifiers are introduced by a '%'
character, and are replaced as follows:

%a             The abbreviated weekday name according to the
               current locale.

%A             The full weekday name according to the current
               locale.

%b             The abbreviated month name according to the
               current locale.

%B             The full month name according to the current
               locale.

%c             The preferred date and time representation for
               the current locale.

%C             The century number (year/100) as a 2-digit
               integer.

%d             The day of the month as a decimal number (range
               01 to 31).

%D             Equivalent to '%m/%d/%y'.

%e             Like '%d', the day of the month as a decimal
               number, but a leading zero is replaced by a
               space.

%E             Modifier: use alternative format, see below
               (see conversion specs).

%F             Equivalent to '%Y-%m-%d' (the ISO 8601 date
               format).

%G             The ISO 8601 year with century as a decimal
               number.  The 4-digit year corresponding to the
               ISO week number (see '%V').  This has the same
               format and value as '%y', except that if the ISO
               week number belongs to the previous or next
               year, that year is used instead.

%g             Like '%G', but without century, i.e., with a
               2-digit year (00-99).

%h             Equivalent to '%b'.

%H             The hour as a decimal number using a 24-hour
               clock (range 00 to 23).

%I             The hour as a decimal number using a 12-hour
               clock (range 01 to 12).

%j             The day of the year as a decimal number (range
               001 to 366).

%k             The hour (24-hour clock) as a decimal number
               (range 0 to 23); single digits are preceded by a
               blank.  (See also '%H'.)

%l             The hour (12-hour clock) as a decimal number
               (range 1 to 12); single digits are preceded by a
               blank.  (See also '%I'.)

%m             The month as a decimal number (range 01 to 12).

%M             The minute as a decimal number (range 00 to 59).

%n             A newline character.

%O             Modifier: use alternative format, see below
               (see conversion specs).

%p             Either 'AM' or 'PM' according to the given time
               value, or the corresponding strings for the
               current locale.  Noon is treated as 'pm' and
               midnight as 'am'.

%P             Like '%p' but in lowercase: 'am' or 'pm' or a
               corresponding string for the current locale.

%r             The time in 'a.m.' or 'p.m.' notation.  In the
               POSIX locale this is equivalent to '%I:%M:%S
               %p'.

%R             The time in 24-hour notation ('%H:%M').  For a
               version including the seconds, see '%T' below.

%s             The number of seconds since the Epoch, i.e.,
               since 1970-01-01 00:00:00 UTC.

%S             The second as a decimal number (range 00 to 61).

%t             A tab character.

%T             The time in 24-hour notation ('%H:%M:%S').

%u             The day of the week as a decimal, range 1 to 7,
               Monday being 1.  See also '%w'.

%U             The week number of the current year as a decimal
               number, range 00 to 53, starting with the first
               Sunday as the first day of week 01.  See also
               '%V' and '%W'.

%V             The ISO 8601:1988 week number of the current
               year as a decimal number, range 01 to 53, where
               week 1 is the first week that has at least 4
               days in the current year, and with Monday as the
               first day of the week.  See also '%U' and '%W'.

%w             The day of the week as a decimal, range 0 to 6,
               Sunday being 0.  See also '%u'.

%W             The week number of the current year as a decimal
               number, range 00 to 53, starting with the first
               Monday as the first day of week 01.

%x             The preferred date representation for the
               current locale without the time.

%X             The preferred time representation for the
               current locale without the date.

%y             The year as a decimal number without a century
               (range 00 to 99).

%Y             The year as a decimal number including the
               century.

%z             The time-zone as hour offset from GMT.  Required
               to emit RFC822-conformant dates (using '%a, %d
               %b %Y %H:%M:%S %z')

%Z             The time zone or name or abbreviation.

%+             The date and time in 'date(1)' format.

%%             A literal '%' character.

   Some conversion specifiers can be modified by preceding them by the
'E' or 'O' modifier to indicate that an alternative format should be
used.  If the alternative format or specification does not exist for the
current locale, the behaviour will be as if the unmodified conversion
specification were used.  The Single Unix Specification mentions '%Ec',
'%EC', '%Ex', '%EX', '%Ry', '%EY', '%Od', '%Oe', '%OH', '%OI', '%Om',
'%OM', '%OS', '%Ou', '%OU', '%OV', '%Ow', '%OW', '%Oy', where the effect
of the 'O' modifier is to use alternative numeric symbols (say, roman
numerals), and that of the 'E' modifier is to use a locale-dependent
alternative representation.

Appendix D Configuring Help Summary
***********************************

Running 'PROG --help' displays the short usage summary for PROG utility
(see 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 E GNU Free Documentation License
*****************************************

                      Version 1.2, November 2002

     Copyright (C) 2000-2025 Free Software Foundation, Inc.
     31 Milk Street, Boston, MA  02196, 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.

E.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.

Concept Index
*************

This is a general index of all issues discussed in this manual