GNU Mailutils Manual

Short Contents

Table of Contents


Next: , Up: (dir)

GNU Mailutils

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

Appendices

Indices

--- The Detailed Node Listing ---

Introduction

Mailutils Programs

Command Line

Mailutils Configuration File

Configuration File Syntax

Server Settings

mail --- Send and Receive Mail

Composing Mail

Reading Mail

movemail --- Moves Mail from the User Maildrop to the Local File

readmsg --- Extract Messages from a Folder

sieve

A Sieve Interpreter

guimb --- A Mailbox Scanning and Processing Language

maidag

Mailbox Quotas

Maidag Scripting

mail.local --- Deliver Mail to the Local UNIX Mailbox

mimeview

POP3 Daemon

IMAP4 Daemon

Comsat Daemon

Configuring comsatd

MH --- The MH Message Handling System

Major differences between Mailutils MH and other MH implementations

mailutils-config --- Get the Information about the Mailutils Build

Mailutils Libraries

Framework

Authentication Library

Mailutils to Scheme Interface

Using libmu_scm

Sieve Library

Sieve Language

Syntax

Preprocessor

Tests

Actions

Date Input Formats


Next: , Previous: Top, Up: Top

1 Introduction

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

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

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


Next: , Up: Introduction

1.1 What this Book Contains

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

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

Subsequent parts address programmers.

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

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

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


Previous: Book Contents, Up: Introduction

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

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

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


Next: , Previous: Introduction, Up: Top

2 Mailutils Programs

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

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

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

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


Next: , Up: Programs

2.1 Command Line


Next: , Up: command line

2.1.1 Basic Notions About Command Line Options

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

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

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

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

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

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

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

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


Previous: Option Basics, Up: command line

2.1.2 Options That are Common for All Utilities.

All GNU Mailutils programs understand a common subset of options.

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

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

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

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

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

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

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

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

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


--usage
Display a short summary of options. In the contrast to the --help option, only option names and arguments are printed, without any textual description. For example:
          Usage: sieve [-cv?V] [--compile-only] [--debug[=FLAGS]]
                       [--email=ADDRESS] SCRIPT

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

--version
-V
Print program version and exit.


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

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

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


--config-help
Show configuration file summary.


--config-lint
Check configuration file syntax and exit


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


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


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


Next: , Previous: command line, Up: Programs

2.2 Mailutils Configuration File

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

  1. Main site-wide configuration file.

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

              $ mailutils-config --info sysconfdir
    

    or

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

    where prog stands for any GNU Mailutils utility.

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

  2. Per-user configuration file.

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

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

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

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

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

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

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

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

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

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

     $ imap4d --config-help > imap4d.rc

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


Next: , Up: configuration

2.2.1 Configuration File Syntax

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


Next: , Up: conf-syntax
2.2.1.1 Comments

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

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

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

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


Next: , Previous: Comments, Up: conf-syntax
2.2.1.2 Statements

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

Examples of simple statements:

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

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

A value can be one of the following:

number
A number is a sequence of decimal digits.


boolean
A boolean value is one of the following: ‘yes’, ‘true’, ‘t’ or ‘1’, meaning true, and ‘no’, ‘false’, ‘nil’, ‘0’ meaning false.
unquoted string
An unquoted string may contain letters, digits, and any of the following characters: ‘_’, ‘-’, ‘.’, ‘/’, ‘:’.
quoted string
A quoted string is any sequence of characters enclosed in double-quotes (‘"’). A backslash appearing within a quoted string introduces an escape sequence, which is replaced with a single character according to the following rules:

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

Table 2.1: Backslash escapes

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

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

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

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

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


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

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

          <<EOT
          A multiline
          string
          EOT

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

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

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

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

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

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


list
A list is a comma-separated list of values. Lists are enclosed in parentheses. The following example shows a statement whose value is a list of strings:
          shared-namespace ("/home", "/var/spool/common");

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


Previous: Statements, Up: conf-syntax
2.2.1.3 Block Statements

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

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

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


Next: , Previous: conf-syntax, Up: configuration

2.2.2 Include Statement

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

     include file;

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

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

     include /etc/mailutils.d;

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


Next: , Previous: Include, Up: configuration

2.2.3 Logging Statement

Syntax

     logging {
       # Set syslog facility.
       facility name;
       # Tag syslog messages with this string.
       tag text;
     }

Description

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

     $ mailutils-config --info log_facility

— Configuration: facility name

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

— Configuration: tag text

Tag syslog messages with text. By default, program name is used as syslog tag.


Next: , Previous: Logging Statement, Up: configuration

2.2.4 Debug Statement

Syntax

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

Description

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

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

error
Display only error messages.
trace0 through trace7
Eight levels of verbosity, ‘trace0’ producing less output, ‘trace7’ producing maximum possible output.
prot
Display network protocol interactions, where appropriate.

Table 2.2: Debugging levels

The most important debugging modules are:

acl
Debug access control lists. .
config
Debug configuration parser and/or lexical analyzer. The following levels are supported:
trace0
Minimal information about configuration statements.
trace2
Trace lexical structure of the configuration files.
trace7
Trace execution of the configuration parser.

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

          #debug=level

is understood as a request to set debugging level of module ‘config’ to level.

ip_server
IP based servers, such as imap4d and pop3d. This module supports ‘trace0’ and ‘error’ levels. See Server Settings, for more information about servers.
udp_server
UDP based servers, such as comsatd. This module supports ‘trace0’ and ‘error’ levels. See Server Settings, for more information about servers.
mailbox
Operations over mailboxes. This module supports the following levels: ‘error’, ‘trace0’, ‘trace1’, and ‘proto’. The latter is used by remote mailbox support libraries.
sieve
Debug Sieve parser and run-time evaluator. Currently supported levels are ‘error’, ‘trace1’ and ‘trace7’.
— Configuration: level spec

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

            module[[:]=level]

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

!
All levels except this one. E.g. ‘config=!trace7’ means set all debugging levels, except ‘trace7’ for the ‘config’ module.
<
All levels up to and including this. The words ‘up to’ refer to the position of levels in Table 2.2 table, so that, e.g. ‘<trace2’ means levels ‘error’, ‘trace0’, ‘trace1’ and ‘trace2’.

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

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

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

             mailbox=<trace2,!<trace4

which means “levels trace3 and trace4”.

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

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

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

— Configuration: line-info bool

If bool is ‘true’ (see boolean value), each debugging message will be preceded by a corresponding source file location, i.e. the file name and line number where this message was generated.


Next: , Previous: Debug Statement, Up: configuration

2.2.5 Mailbox Statement

Syntax

     mailbox {
       # Use specified url as a mailspool.
       mail-spool url;
       # Create mailbox url using pattern.
       mailbox-pattern pattern;
       # Default mailbox type.
       mailbox-type type;
       # Default user mail folder.
       folder dir;
     }

Description

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

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

— Configuration: mail-spool path

The mail-spool statement specifies directory that holds user mailboxes. Once this statement is given, the libmailutils library will assume that the mailbox of user login is kept in file path/login.

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

— Configuration: mailbox-pattern pattern

The mailbox-pattern statement is a modern way of configuring mailbox locations. It supersedes mail-spool statement.

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

            [type://]path[;args]

where:

type
Specifies the mailbox type. It must be one of mailbox types, supported by Mailutils. . By default, ‘local’ is assumed. .
path
The path pattern.
args
A semicolon-separated list of optional arguments, configuring indexed directory structure.

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

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

GNU Mailutils supports three types of indexed directories: ‘direct’, ‘reverse’, and ‘hashed’.

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

  1. Take the first letter of the user name.
  2. Map it to a lower-case letter using index mapping table. The result gives sub-directory name.
  3. Descend into this directory.

For example, using this algorithm, the mailbox of the user ‘smith’ is stored in file path/s/smith.

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

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

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

  1. Take next letter from the user name
  2. Add its ASCII value to the hash sum.
  3. Continue (1-2) until level letters are processed, or all letters from the file name are used, whichever occurs first.
  4. Convert the computed sum modulo 256 to a hex code.

Indexed directory structures are configured using the following arguments:

type=value
Specifies type of indexing. Valid values are ‘index’, for direct indexed structure, ‘rev-index’ for reverse indexing, and ‘hash’ for hashed structure.


param=number
Specifies indexing level.


user=string
Specifies indexing key. The only meaningful value, as of Mailutils version 2.0 is ‘user=${user}’.

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

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

It is entirely equivalent to specifying ‘mail-spool "/var/mail"’.

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

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

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

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

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

  1. If environment variable FOLDER its value is used.
  2. Otherwise, if environment variable MAIL is set, its value is used.
  3. If neither of these is set, the mailbox name is constructed by concatenating the built-in mail spool directory name, a directory separator, and the user name.

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

— Configuration: mailbox-type type

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

— Configuration: folder dir

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

The dir argument can contain mailbox type prefix, e.g ‘mh://Mail’.

The default folder name is ‘Mail/’.


Next: , Previous: Mailbox Statement, Up: configuration

2.2.6 Locking Statement

Syntax

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

Description

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

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

— Configuration: flags string

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

E
Use an external program to manage locks. The program is given by external-locker statement (see below).
R
If the locking attempt failed, retry it. This is the default. The number of retries, and time interval between the two successive attempts is given by retry-count and retry-timeout statements, correspondingly.
T
If a lock file exists, check its modification time and, if it is older than a predefined amount of time, remove the lock. The amount of time is specified by expire-timeout statement.
P
Store the PID of the locking process in a lock file.

— Configuration: retry-count number

Number of locking attempts. The ‘P’ flag must be set for this to take effect.

— Configuration: retry-timeout seconds

Time interval, in seconds, between the two successive locking attempts. The ‘P’ flag must be set for this to take effect.

— Configuration: expire-timeout seconds

Remove existing lock file, if it is created more than this number of seconds ago. The ‘T’ flag must be set for this to take effect.

— Configuration: external-locker string

Set command line of an external locker program. The ‘E’ flag must be set for this to take effect.


Next: , Previous: Locking Statement, Up: configuration

2.2.7 Mailer Statement

Syntax

     mailer {
       url url;
     }

Description

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

The mailer statement contains a single sub-statement:

— Configuration: url str

Set the mailer URL.

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

smtp://host[:port]
Use an SMTP server host to send messages. Optional port specifies port number or symbolic name (as defined in /etc/services). It defaults to 25. The host can be specified as either an IP address in dotted-quad notation or as a symbolic host name. In the latter case, DNS system will be used to resolve it.
sendmail://progname
Use sendmail-compatible program progname. Sendmail-compatible means that the program must support following command line options:
-oi
Do not treat ‘.’ as message terminator.
-f addr
Use addr as the sender address.
-t
Get recipient addresses from the message.

sendmail:
This is a special form of the ‘sendmail’ mailer. It uses the sendmail binary from the _PATH_SENDMAIL macro in your /usr/include/paths.h. It is the default mailer.
prog://progname?query
A prog mailer. This is a generalization of ‘sendmail’ mailer that allows to use arbitrary external programs as mailers.

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

The query part is a list of arguments, separated by ‘&’ signs. Arguments may contain the following macro-substitutions:

${sender}
Expands to the sender email address.
${rcpt}
Expands to the recipient email addresses.


Next: , Previous: Mailer Statement, Up: configuration

2.2.8 ACL Statement

Syntax

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

Description

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

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

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

The following controls are understood:

— Configuration: allow [from] cidr

Allow connections from IP addresses matching this cidr block.

— Configuration: deny [from] cidr

Deny connections from IP addresses matching this cidr block.

— Configuration: ifexec [from] cidr program

When a connection from the cidr block is requested, execute the program program. If its exit code is ‘0’, then allow connection. Otherwise, deny it.

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

— Configuration: log [from] cidr [string]

Log connections from addresses in this cidr. The MU_DIAG_INFO channel is used. If the logging goes to syslog, it is translated to the LOG_INFO priority.

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

{AF_INET ip:port}
For inet IPv4 connections. The variables ip and port are replaced by the remote IP address and port number, correspondingly.
{AF_UNIX}
For connections over UNIX sockets. The socket name, if available, may be printed before the closing curly brace.

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

aclno
Ordinal number of the control in the ACL. Numbers begin from ‘0’.
family
Connection family. Mailutils version 2.0 supports two families: ‘AF_INET’ and ‘AF_UNIX’.
address
Remote IP address (for ‘AF_INET’) or socket name (for ‘AF_UNIX’). Notice that most Unixes return empty string instead of the ‘AF_UNIX’ socket name, so do not rely on it.
port
Remote port number (for ‘AF_INET’).

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

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

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

— Configuration: exec [from] cidr program

If a connection from the cidr block is requested, execute the given program. Do not wait for it to terminate, and ignore its exit code.


Next: , Previous: ACL Statement, Up: configuration

2.2.9 Tcp-wrappers Statement

Syntax

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

2.2.10 Description

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

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

Description of a TCP wrapper table format lies outside the scope of this document. Please, see ACCESS CONTROL FILES, for details.

— Configuration: enable bool

Enable access control using TCP wrappers. It is on by default.

— Configuration: daemon name

Set daemon name for TCP wrapper lookups. By default, the name of the utility is used. E.g. imap4d uses ‘imap4d’ as the daemon name.

— Configuration: allow-table file

Use file as allow table. By default, /etc/hosts.allow is used.

— Configuration: deny-table file

Use file as negative table. By default, /etc/hosts.deny is used.

— Configuration: allow-syslog-priority prio;

Log allowed accesses using syslog priority prio.

— Configuration: deny-syslog-priority prio;

Log denied accesses using syslog priority prio.


Next: , Previous: Tcp-wrappers Statement, Up: configuration

2.2.11 Server Settings

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

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


Next: , Up: Server Settings
2.2.11.1 General Server Configuration

Syntax
     # Set daemon mode.
     mode ‘inetd|daemon’;
     # Run in foreground.
     foreground bool;
     # Maximum number of children processes to run simultaneously.
     max-children number;
     # Store PID of the master process in file.
     pidfile file;
     # Default port number.
     port portspec;
     # Set idle timeout.
     timeout time;
Description

These statements configure general server-related issues.

— Configuration: mode string;

Set operation mode of the server. Two operation modes are supported:

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

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


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

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

— Configuration: foreground bool;


[daemon mode only]
Do not disconnect from the controlling terminal and remain in the foreground.

— Configuration: max-children number;


[daemon mode only]
Set maximum number of child processes allowed to run simultaneously. This equals the number of clients that can use the server simultaneously.

The default is 20 clients.

— Configuration: pidfile file;

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

— Configuration: port portspec;


[daemon mode only]
Set default port to listen to. The portspec argument is either a port number in decimal, or a symbolic service name, as listed in /etc/services (see Internet network services list).

— Configuration: timeout time;

Set maximum idle time out in seconds. If a client does not send any requests during time seconds, the child process terminates.


Previous: General Server Configuration, Up: Server Settings
2.2.11.2 Server Statement

Syntax
     server ipaddr[:port] {
       # Run this server as a single process.
       single-process bool;
       # Log the session transcript.
       transcript bool;
       # Set idle timeout.
       timeout time;
       # Set server specific ACLs.
       acl { /* See ACL Statement. */ };
     }
Description

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

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

Statements within the server block statement configure this particular server.

— Configuration: single-process bool;

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

— Configuration: transcript bool;

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

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

— Configuration: timeout time;

Set idle timeout for this server. This overrides global timeout settings (see timeout).

— Configuration: acl

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


Next: , Previous: Server Settings, Up: configuration

2.2.12 Auth Statement

Syntax

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

Description

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

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

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

For example, the authorization list

       (system, sql, virtdomains)

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

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

The auth statement configures authentication and authorization.

— Configuration: authorization module-list

Define a sequence of modules to use for authorization. Modules will be tried in the same order as listed in module-list.

The modules available for use in authorization list are:

system
User credentials are retrieved from the system user database (/etc/password).
sql
User credentials are retrieved from a SQL database. A separate configuration statement, sql, is used to configure it (see SQL Statement).
virtdomain
User credentials are retrieved from a “virtual domain” user database. Virtual domains are configured using virtdomain statement (see Virtdomain Statement).
radius
User credentials are retrieved using RADIUS. See Radius Statement, for a detailed description on how to configure it.
ldap
User credentials are retrieved from an LDAP database. See LDAP Statement, for an information on how to configure it.

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

            (system, sql, virtdomains)
— Configuration: authentication module-list

Define a sequence of modules to use for authentication. Modules will be tried in the same order as listed in module-list.

The following table lists modules available for use in module-list:

generic
The generic authentication type. User password is hashed and compared against the hash value returned in authorization stage.
system
The hashed value of the user password is retrieved from /etc/shadow file on systems that support it.
sql
The hashed value of the user password is retrieved from a SQL database using query supplied by getpass statement (see getpass).
pam
The user is authenticated via pluggable authentication module (PAM). The PAM service name to be used is configured in pam statement (see PAM Statement).
radius
The user is authenticated on a remote RADIUS server. See Radius Statement.
ldap
The user is authenticated using LDAP. See LDAP Statement.

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

            (generic, system, pam, sql)


Next: , Previous: Auth Statement, Up: configuration

2.2.13 PAM Statement

Syntax

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

Description

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

— Configuration: service text

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

This statement takes effect only if ‘pam’ is listed in authentication statement (see Auth Statement).


Next: , Previous: PAM Statement, Up: configuration

2.2.14 Virtdomain Statement

Syntax

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

Description

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

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

— Configuration: passwd-dir dir

Set virtual domain password directory.

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

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

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

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

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


Next: , Previous: Virtdomain Statement, Up: configuration

2.2.15 Radius Statement

Syntax

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

Description

The radius block statement configures RADIUS authentication and authorization.

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

— Configuration: directory dir

Set full path name to the GNU Radius configuration directory.

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

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

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

     $INCLUDE dict/mailutils.dict

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

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

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

user
The actual user name (for auth and getpwnam), or user ID (for getpwuid). For example:
          User-Name = ${user}

passwd
User password. For examples:
          User-Password = ${passwd}
— Configuration: auth pairlist

Specifies the request to be sent to authenticate the user. For example:

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

The user is authenticated only if this request returns Access-Accept (see Access-Accept). Any returned attribute-value pairs are ignored.

— Configuration: getpwnam pairlist

Specifies the request that returns user information for the given user name. For example:

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

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

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

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

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

— Configuration: getpwuid pairlist

Specifies the request that returns user information for the given user ID. In pairlist, the ‘user’ macro-variable is expanded to the numeric value of ID. For example:

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

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


Next: , Previous: Radius Statement, Up: configuration

2.2.16 SQL Statement

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

Syntax

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

2.2.17 Description

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

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

— Configuration: interface type

Configures type of DBMS interface. Allowed values for type are:

mysql
Interface with a MySQL server (http://www.mysql.org).
odbc
Use ODBC interface. See http://www.unixodbc.org, for a detailed description of ODBC configuration.
postgres
Interface with a PostgreSQL server (http://www.postgres.org).

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

— Configuration: host arg

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

— Configuration: port arg

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

— Configuration: db arg;

Name of the database.

— Configuration: user arg

SQL user name.

— Configuration: passwd arg;

Password to access the database.


Next: , Previous: SQL Statement, Up: configuration

2.2.18 LDAP Statement

This node is to be written.

Syntax

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


Next: , Previous: LDAP Statement, Up: configuration

2.2.19 TLS Statement

This node is to be written.

Syntax

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


Previous: TLS Statement, Up: configuration

2.2.20 GSASL Statement

This node is to be written.

Syntax

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


Next: , Previous: configuration, Up: Programs

2.3 frm and from — List Headers from a Mailbox

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

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

Statement Reference
debug See Debug Statement.
tls See TLS Statement.
mailbox See Mailbox Statement.
locking See Locking Statement.

frm

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

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

-d
--debug
Enable debugging output.
-f string
--field string
Display the header named by string instead of From Subject pair.
-l
--to
Include the contents of To header to the output. The output field order is then: To From Subject.
-n
--number
Prefix each line with corresponding message number.
-Q
--Quiet
Be very quiet. Nothing is output except error messages. This is useful in shell scripts where only the return status of the program is important.
-q
--query
Print a message only if there are unread messages in the mailbox.
-S
--summary
Print a summary line.
-s attr
--status attr
Only display headers from messages with the given status. Attr may be one of the following: ‘new’, ‘read’, ‘unread’. It is sufficient to specify only first letter of an attr. Multiple -s options are allowed.
-t
--align
Tidy mode. In this mode frm tries to preserve the alignment of the output fields. It also enables the use of BIDI algorithm for displaying subject lines that contain text in right-to-left orientation (such as Arabic or Hebrew).

from

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

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

The full list of options, supported by from follows:

-c
--count
Prints only a count of messages in the mailbox and exit.
-d
--debug
Prints additional debugging output.
-s string
--sender=string
Prints only mail whose ‘From:’ headers contain the supplied string.
-f url
--file=url
Examine mailbox from the given url.


Next: , Previous: frm and from, Up: Programs

2.4 mail — Send and Receive Mail

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

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

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


Next: , Up: mail

2.4.1 Invoking mail

General usage of mail program is:

           mail [option...] [address...]

If [address...] part is present, mail switches to mail sending mode, otherwise it operates in mail reading mode.

The program uses following option groups: .

Mail understands following command line options:

-e
--exist
Return true if the mailbox contains some messages. Return false otherwise. This is useful for writing shell scripts.
-E command
--exec=command
Execute command before opening the mailbox. Any number of --exec options can be given. The commands will be executed after sourcing configuration files (see Mail Configuration Files), but before opening the mailbox.
--exec
-f[file]
--file[=file]
Operate on mailbox file. If this option is not specified, the default is user's system mailbox. If it is specified without argument, the default is $HOME/mbox. Please note, that there should be no whitespace between the short variant of the option (-f), and its parameter. Similarly, when using long option (--file), its argument must be preceded by equal sign.
-F
--byname
Save messages according to sender. Currently this option is not implemented.
-H
--headers
Print header summary to stdout and exit.
-i
--ignore
Ignore interrupts.
-m path
--mail-spool=path
Set path to the mailspool directory
-n
--norc
Do not read the system-wide mailrc file. See Mail Configuration Files.
-N
--nosum
Do not display initial header summary.
-p
--print
-r
--read
Print all mail to standard output. It is equivalent to issuing following commands after starting ‘mail -N’:
          print *
          quit

-q
--quit
Cause interrupts to terminate program.
-s subj
--subject=subj
Send a message with a Subject of subj. Valid only in sending mode.
-t
--to
Switch to sending mode.
-u user
--user=user
Operate on user's mailbox. This is equivalent to:
          mail -f/spool_path/user

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

-?
--help
Display a help message.
--usage
Display a short usage summary.
-V
--version
Print program version and exit.


Next: , Previous: Invoking Mail, Up: mail

2.4.2 How to Specify Message Sets

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

The message list in its simplest form is one of:

.
Selects current message. It is equivalent to empty message list.
*
Selects all messages in the mailbox.
^
Selects first non-deleted message.
$
Selects last non-deleted message.

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

Message Number
This specifier addresses the message with the given ordinal number in the mailbox.
Message range
Message range is specified as two message numbers separated by a dash. It selects all messages with the number lying within that range.
Attribute specifier
An Attribute specifier is a colon followed by a single letter. The Attribute specifier addresses all messages in the mailbox that have the given attribute. These are the valid attribute specifiers:
:d
Selects all deleted messages.
:n
Selects all recent messages, i.e. the messages that have not been neither read not seen so far.
:o
Selects all messages that have been seen.
:r
Selects all messages that have been read.
:u
Selects all messages that have not been read.
:t
Selects all tagged messages.
:T
Selects all untagged messages.

Header match
The header match is a string in the form:
          [header:]/string/

It selects all messages that contain header field header matching given regexp. If the variable regexp is set, the string is assumed to be a POSIX regexp. Otherwise, a header is considered to match string if the latter constitutes a substring of the former (comparison is case-insensitive).

If header: part is omitted, it is assumed to be ‘Subject:’.

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

It selects all messages whose body matches the string. The matching rules are the same as described under “Header match”.

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

The following are the examples of valid message lists:


Next: , Previous: Specifying Messages, Up: mail

2.4.3 Composing Mail

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


Next: , Up: Composing Mail
Quitting Compose Mode

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

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

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

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

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


Next: , Previous: Quitting Compose Mode, Up: Composing Mail
Getting Help on Compose Escapes: ~?

The ‘~?’ escape prints on screen a brief summary of the available compose escapes. Please note, that ‘~h’ escape prompts for changing the header values, and does not give help.


Next: , Previous: Getting Help on Compose Escapes, Up: Composing Mail
Editing the Message: ~e and ~v

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

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


Next: , Previous: Editing the Message, Up: Composing Mail
Modifying the Headers: ~h, ~t, ~c, ~b, ~s

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

     ~t name1@domain.net name2

To add addresses to Cc or Bcc, use ‘~c’ or ‘~b’ escapes respectively.

To change the Subject header, use ‘~s’ escape, e.g.:

     ~s "Re: your message"

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


Next: , Previous: Modifying the Headers, Up: Composing Mail
Enclosing Another Message: ~m and ~M

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

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

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


Next: , Previous: Enclosing Another Message, Up: Composing Mail
Adding a File to the Message: ~r and ~d

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

     ~r filename

or

     ~< filename

The ‘~d’ escape is a shorthand for

     ~r dead.letter


Next: , Previous: Adding a File to the Message, Up: Composing Mail
Printing And Saving the Message

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


Next: , Previous: Printing And Saving the Message, Up: Composing Mail
Signing the Message: ~a and ~A

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


Next: , Previous: Signing the Message, Up: Composing Mail
Printing Another Message: ~f and ~F

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


Next: , Previous: Printing Another Message, Up: Composing Mail
Inserting Value of a Mail Variable: ~i

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


Next: , Previous: Inserting Value of a Mail Variable, Up: Composing Mail
Executing Other Mail Commands: ~: and ~-

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

     ~: from :t

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


Previous: Executing Other Mail Commands, Up: Composing Mail
Executing Shell Commands: ~! and ~|

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


Next: , Previous: Composing Mail, Up: mail

2.4.4 Reading Mail

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

mail
To read messages from your system mailbox.
mail --file
To read messages from your mailbox ($HOME/mbox).
mail --file=path_to_mailbox
To read messages from the specified mailbox.
mail --user=user
To read messages from the system mailbox belonging to user.

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

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


Next: , Up: Reading Mail
Quitting the Program

Following commands quit the program:

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

Typing EOF (‘C-D’) alone is equivalent to ‘quit’.


Next: , Previous: Quitting the Program, Up: Reading Mail
Obtaining Online Help

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

help [command]
hel [command]
? [command]
Display detailed command synopsis. If no command is given, help for all available commands is displayed.
list
*
Print a list of available commands.
version
ve
Display program version.
warranty
wa
Display program warranty statement.


Next: , Previous: Obtaining Online Help, Up: Reading Mail
Moving Within a Mailbox

^
Move to the first undeleted message.
$
Move to the last undeleted message.
next
n
Move to the next message.
previous
prev
Move to the previous message.


Next: , Previous: Moving Within a Mailbox, Up: Reading Mail
Changing Mailbox/Directory

cd [dir]
chdir [dir]
ch [dir]
Change to the specified directory. If dir is omitted, $HOME is assumed.
file [mailbox]
fi [mailbox]
folder [mailbox]
fold [mailbox]
Read in the contents of the specified mailbox. The current mailbox is updated as if quit command has been issued. If mailbox is omitted, the command prints the current mailbox name followed by the summary information regarding it, e.g.:
          

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


Next: , Previous: Changing mailbox/directory, Up: Reading Mail
Controlling Header Display

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

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

discard [header-field-list]
di [header-field-list]
ignore [header-field-list]
ig [header-field-list]
Add header-field-list to the ignored list. When used without arguments, this command prints the contents of ignored list.
retain [header-field-list]
ret [header-field-list]
Add header-field-list to the retained list. When used without arguments, this command prints the contents of retained list.


Next: , Previous: Controlling Header Display, Up: Reading Mail
Displaying Information

=
Displays the current message number.
headers [msglist]
h [msglist]
Lists the current pageful of headers.
from [msglist]
f [msglist]
Lists the contents of ‘From’ headers for a given set of messages.
z [arg]
Presents message headers in pagefuls as described for headers command. When arg is ‘.’, it is generally equivalent to headers. When arg is omitted or is ‘+’, the next pageful of headers is displayed. If arg is ‘-’, the previous pageful of headers is displayed. The latter two forms of z command may also take a numerical argument meaning the number of pages to skip before displaying the headers. For example:
          & z +2

will skip two pages of messages before displaying the header summary.

size [msglist]
si [msglist]
Lists the message number and message size in bytes for each message in msglist.
folders
Displays the value of folder variable.
summary
su
Displays current mailbox summary. E.g.:
          

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


Next: , Previous: Displaying Information, Up: Reading Mail
Displaying Messages

print [msglist]
p [msglist]
type [msglist]
t [msglist]
Prints out the messages from msglist. The variable crt determines the minimum number of lines the body of the message must contain in order to be piped through pager command specified by environment variable PAGER. If crt is set to a numeric value, this value is taken as the minimum number of lines. Otherwise, if crt is set without a value then the height of the terminal screen is used to compute the threshold. The number of lines on screen is controlled by screen variable.
Print [msglist]
P [msglist]
Type [msglist]
T [msglist]
Like print but also prints out ignored header fields.
decode [msglist]
dec [msglist]
Print a multipart message. The decode command decodes and prints out specified message parts. E.g.
          

& decode 15[2] +--------------------------------------- | Message=15[2] | Type=message/delivery-status | encoding=7bit +--------------------------------------- Content-Type: message/delivery-status ...


top [msglist]
to [msglist]
Prints the top few lines of each message in msglist. The number of lines printed is controlled by the variable toplines and defaults to five.
pipe [msglist] [shell-command]
| [msglist] [shell-command]
Pipe the contents of specified messages through shell-command. If shell-command is empty but the string variable cmd is set, the value of this variable is used as a command name.


Next: , Previous: Displaying Messages, Up: Reading Mail
Marking Messages

tag [msglist]
ta [msglist]
Tag messages. The tagged messages can be referred to in message list using ‘:t’ notation.
untag [msglist]
unt [msglist]
Clear tags from specified messages. To untag all messages tagged so far type
          & untag :t

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


Next: , Previous: Marking Messages, Up: Reading Mail
Disposing of Messages

delete [msglist]
d [msglist]
Mark messages as deleted. Upon exiting with quit command these messages will be deleted from the mailbox. Until the end of current session the deleted messages can be referred to in message lists using :d notation.
undelete [msglist]
u [msglist]
Clear delete mark from the specified messages.
dp [msglist]
dt [msglist]
Deletes the current message and prints the next message. If msglist is specified, deletes all messages from the list and prints the message, immediately following last deleted one.


Next: , Previous: Disposing of Messages, Up: Reading Mail
Saving Messages

save [[msglist] file]
s [[msglist] file]
Takes a message list and a file name and appends each message in turn to the end of the file. The name of file and number of characters appended to it is echoed on the terminal. Each saved message is marked for deletion as if with delete command, unless the variable keepsave is set.
Save [msglist]
S [msglist]
Like save, but the file to append messages to is named after the sender of the first message in msglist. For example:
          

& from 14 15 U 14 smith@noldor.org Fri Jun 30 18:11 14/358 The Save c U 15 gray@noldor.org Fri Jun 30 18:30 8/245 Re: The Sa & Save 14 15 "smith" 22/603

i.e., 22 lines (603 characters) have been appended to the file “smith”. If the file does not exist, it is created.

write [[msglist] file]
w [[msglist] file]
Similar to save, except that only message body (without the header) is saved.
Write [msglist]
W [msglist]
Similar to Save, except that only message body (without the header) is saved.
mbox [msglist]
mb [msglist]
touch [msglist]
tou [msglist]
Mark list of messages to be saved in the user's mailbox ($HOME/mbox) upon exiting via quit command. This is the default action for all read messages, unless you have variable hold set.
copy [[msglist] file]
c [[msglist] file]
Similar to save, except that saved messages are not marked for deletion.
Copy [msglist]
C [msglist]
Similar to Save, except that saved messages are not marked for deletion.


Next: , Previous: Saving Messages, Up: Reading Mail
Editing Messages

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

edit [msglist]
e [msglist]
Edits each message in msglist with the editor, specified in EDITOR environment variable.
visual [msglist]
v [msglist]
Edits each message in msglist with the editor, specified in VISUAL environment variable.


Next: , Previous: Editing Messages, Up: Reading Mail
Aliasing

alias [alias [address...]]
a [alias [address...]]
group [alias [address...]]
g [alias [address...]]
With no arguments, prints out all currently-defined aliases. With one argument, prints out that alias. With more than one argument, creates a new alias or changes an old one.
unalias [alias...]
una [alias...]
Takes a list of names defined by alias commands and discards the remembered groups of users. The alias names no longer have any significance.
alternates name...
alt name...
The alternates command is useful if you have accounts on several machines. It can be used to inform mail that the listed addresses are really you. When you reply to messages, mail will not send a copy of the message to any of the addresses listed on the alternates list. If the alternates command is given with no argument, the current set of alternate names is displayed.


Next: , Previous: Aliasing, Up: Reading Mail
Replying

mail [address...]
m [address...]
Switches to compose mode. After composing the message, sends messages to the specified addresses.
reply [msglist]
respond [msglist]
r [msglist]
For each message in msglist, switches to compose mode and sends the composed message to the sender and all recipients of the message.
Reply [msglist]
Respond [msglist]
R [msglist]
Like reply, except that the composed message is sent only to originators of the specified messages.

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

followup [msglist]
fo [msglist]
Switches to compose mode. After composing, sends the message to the originators and recipients of all messages in msglist.
Followup [msglist]
F [msglist]
Similar to followup, but reply message is sent only to originators of messages in msglist.

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

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

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

     

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

Now, you issue the following commands:

     

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

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

Now, let's try the following command sequence:

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

Now, the From address will be taken:

     

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


Next: , Previous: Replying, Up: Reading Mail
Controlling Sender Fields

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

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

     

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

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

     

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

When used without arguments, this command clears the list:

     

& nosender Sender address is obtained from the envelope


Next: , Previous: Controlling Sender Fields, Up: Reading Mail
Incorporating New Mail

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


Previous: Incorporating New Mail, Up: Reading Mail
Shell Escapes

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


Next: , Previous: Reading Mail, Up: mail

2.4.5 Scripting

Comments

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

Displaying Arbitrary Text

The ‘echo’ (‘ec’) command prints its arguments to stdout.

Sourcing External Command Files

The command ‘source filename’ reads commands from the named file. Its minimal abbreviation is ‘so’.

Setting and Unsetting the Variables

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

name=string
Assign a string value to the variable. If string contains whitespace characters it must be enclosed in a pair of double-quote characters (‘"’)
name=number
Assign a numeric value to the variable.
name
Assign boolean True value.
noname
Assign boolean False value.

Example:

     & set askcc nocrt indentprefix="> "

This statement sets askcc to True, crt to False, and indentprefix to “> ”.

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

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

     & unset askcc crt indentprefix
Setting and Unsetting Shell Environment Variables

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

name=value
If variable name does not already exist in the environment, then it is added to the environment with the value value. If name does exist, then its value in the environment is changed to value.
name
Delete the variable name from the environment (“unset” it).
Conditional Statements

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

     if cond
     ...
     else
     ...
     endif

where ‘...’ represents the set of commands to be executed in each branch of the statement. cond can be one of the following:

s
True if mail is operating in mail sending mode.
r
True if mail is operating in mail reading mode.
t
True if stdout is a terminal device (as opposed to a regular file).

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

Example:

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


Next: , Previous: Scripting, Up: mail

2.4.6 How to Alter the Behavior of mail

Following variables control the behavior of GNU mail:

appenddeadletter

Type: Boolean.
Default: False. If this variable is True, the contents of canceled letter is appended to the user's dead.letter file. Otherwise it overwrites its contents.
askbcc

Type: Boolean.
Default: False. When set to True the user will be prompted to enter Bcc field before composing the message.
askcc

Type: Boolean.
Default: True. When set to True the user will be prompted to enter Cc field before composing the message.
asksub

Type: Boolean.
Default: True in interactive mode, False otherwise. When set to True the user will be prompted to enter Subject field before composing the message.
autoinc

Type: Boolean.
Default: True. Automatically incorporate newly arrived messages.
autoprint

Type: Boolean.
Default: False. Causes the delete command to behave like dp - thus, after deleting a message, the next one will be typed automatically.
bang

Type: Boolean.
Default: False. When set, every occurrence of ! in arguments to ! command is replaced with the last executed command.
datefield

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

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

Type: String.
Default: Unset. Contains default shell command for pipe.
columns

Type: Numeric.
Default: Detected at startup by querying the terminal device. If this fails, the value of environment variable COLUMNS is used. This variable contains the number of columns on terminal screen.
crt

Type: Boolean or Numeric
Default: True in interactive mode, False otherwise. The variable crt determines the minimum number of lines the body of the message must contain in order to be piped through pager command specified by environment variable PAGER. If crt is set to a numeric value, this value is taken as the threshold. Otherwise, if crt is set without a value, then the height of the terminal screen is used to compute the threshold. The number of lines on screen is controlled by screen variable.
decode-fallback

Type: String.
Default: ‘none’. This variable controls the way to represent characters that cannot be rendered using current character set. It can have three values:
none
Such characters are not printed at all. The conversion process stops at the first character that cannot be rendered.
copy-pass
The characters are displayed ‘as is’. Notice, that depending on your setup, this may screw-up your terminal settings.
copy-octal
Unprintable characters are represented by their octal codes. Printable ones are printed ‘as is’.

dot

Type: Boolean.
Default: False. If True, causes mail to interpret a period alone on a line as the terminator of a message you are sending.
emptystart

Type: Boolean.
Default: False. If the mailbox is empty, mail normally prints ‘No mail for user’ and exits immediately. If this option is set, mail will start no matter is the mailbox empty or not.
editheaders

Type: Boolean.
Default: False. When set, mail will include message headers in the text to be the ~e and ~v escapes, thus allowing you to customize the headers.
escape

Type: String.
Default: ~ If defined, the first character of this option gives the character to denoting escapes.
flipr

Type: Boolean
Default: Unset The variable flipr if set swaps the meanings of reply and Reply commands (see Replying).
folder

Type: String.
Default: Unset. The name of the directory to use for storing folders of messages. If unset, $HOME is assumed.
header

Type: Boolean.
Default: True, unless started with --nosum (-N) option. Whether to run headers command automatically after entering interactive mode.
hold

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

Type: Boolean.
Default: False. When set to True, mail will ignore keyboard interrupts when composing messages. Otherwise an interrupt will be taken as a signal to abort composing.
ignoreeof

Type: Boolean.
Default: False. Controls whether typing EOF character terminates the letter being composed.
indentprefix

Type: String.
Default: "\t" (a tab character). String used by the ~m tilde escape for indenting quoted messages.
inplacealiases

Type: Boolean
Default: False

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

keepsave

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

Type: Boolean.
Default: False. When set, enables mailx compatibility mode. This mode has the following effects:
metamail

Type: Boolean or String.
Default: True. This variable controls operation of decode command. If it is unset, decode will not attempt any interpretation of the content of message parts. Otherwise, if metamail is set to true, decode will use internal metamail support to interpret message parts. Finally, if metamail is assigned a string, this string is treated as command line of the external metamail command which will be used to display parts of a multipart message. For example:
          # Disable MIME interpretation:
          set nometamail
          # Enable built-in MIME support:
          set metamail
          # Use external program to display MIME parts:
          set metamail="metamail -m mail -p"

mimenoask

Type: String
Default: Empty By default mail asks for confirmation before running interpreter to view a part of the multi-part message. If this variable is set, its value is treated as a comma-separated list of MIME types for which no confirmation is needed. Elements of this list may include shell-style globbing patterns, e.g. setting
          set mimenoask=text/*,image/jpeg

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

metoo

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

Type: String.
Default: The name of current operation mode. Setting this variable does not affect the operation mode of the program.
nullbody

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

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

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

nullbodymsg

Type: String
Default: Null message body; hope that's ok Keeps the text of the warning, displayed by mail before sending an empty message. When available, the translation of this text, in accordance with the current locale, is displayed.

Unsetting this variable disables the warning.

outfolder

Type: String.
Default: Unset. Contains the directory in which files created by save, write, etc. commands will be stored. When unset, current directory is assumed.
page

Type: Boolean.
Default: False. If set to True, the pipe command will emit a linefeed character after printing each message.
prompt

Type: String.
Default: "? " Contains the command prompt sequence.
quit

Type: Boolean.
Default: False, unless started with --quit (-q) option. When set, causes keyboard interrupts to terminate the program.
rc

Type: Boolean.
Default: True, unless started with --norc (-N) option. When this variable is set, mail will read the system-wide configuration file upon startup. See Mail Configuration Files.
record

Type: String.
Default: Unset. When set, any outgoing message will be saved to the named file.
recursivealiases

Type: Boolean
Default: True

When set, mail will expand aliases recursively.

regex

Type: Boolean.
Default: True. Setting this to True enables use of regular expressions in ‘/.../’ message specifications.
replyprefix

Type: String
Default: ‘Re: Sets the prefix that will be used when constructing the subject line of a reply message.
replyregex

Type: String
Default: ‘^re: * Sets the regular expression used to recognize subjects of reply messages. If the Subject header of the message matches this expression, the value of replyprefix will not be prepended to it before replying. The expression should be a POSIX extended regular expression. The comparison is case-insensitive.

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

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

(Notice the quoting of backslash characters).

save

Type: Boolean.
Default: True. When set, the aborted messages will be stored in the user's dead.file. See also appenddeadletter.
screen

Type: Numeric.
Default: Detected at startup by querying the terminal device. If this fails, the value of environment variable LINES is used. This variable contains the number of lines on terminal screen.
sendmail

Type: String.
Default: sendmail:/usr/lib/sendmail Contains the URL of mail transport agent.
Sign

Type: String.
Default: Unset. Contains the filename holding users signature. The contents of this file is appended to the end of a message being composed by ~A escape.
sign

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

Type: Boolean
Default: unset If this variable is set, mail will show To: addresses instead of From: for all messages that come from the user that invoked the program.
subject

Type: String.
Default: Unset. Contains default subject line. This will be used when asksub is off.
toplines

Type: Numeric.
Default: 5 Number of lines to be displayed by top and Top commands.
verbose

Type: Boolean.
Default: False. When set, the actual delivery of messages is displayed on the user's terminal.
xmailer

Type: Boolean.
Default: Set. Controls whether the header ‘X-Mailer’ should be added to outgoing messages. The default value of this header is
          X-Mailer: mail (GNU Mailutils 2.0)


Previous: Mail Variables, Up: mail

2.4.7 Personal and System-wide Configuration Files

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

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

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


Next: , Previous: mail, Up: Programs

2.5 messages — Count the Number of Messages in a Mailbox

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

     Number of messages in folder: number

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

Following configuration file statements affect the behaviour of messages:

Statement Reference
debug See Debug Statement.
tls See TLS Statement.
mailbox See Mailbox Statement.
locking See Locking Statement.

The program accepts following command line options:

-q
--quiet
-s
--silent
Be quiet. Display only number of messages per mailbox, without leading text.
-?
--help
Output help message and exit.
--usage
Output short usage summary and exit.
-V
--version
Output program version and exit.


Next: , Previous: messages, Up: Programs

2.6 movemail — Moves Mail from the User Maildrop to the Local File

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

     movemail /var/mail/smith INBOX

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

You will probably never have to run this program manually. It is intended as a replacement for movemail from GNU Emacs. The movemail program is run by Emacs Rmail module. See Rmail, for detailed description of Rmail interface.

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


Next: , Up: movemail

2.6.1 Movemail Configuration

Following configuration file statements affect the behavior of movemail:

— Movemail Config: preserve bool

If bool is ‘true’, do not remove messages from the source mailbox.

— Movemail Config: reverse bool

If bool is ‘true’, reverse message sorting order.

— Movemail Config: emacs bool

If bool is ‘true’, output information used by Emacs rmail interface.

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


Next: , Previous: Movemail Configuration, Up: movemail

2.6.2 Movemail Options

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

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

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

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

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

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

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

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

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

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

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

     --lock-expire-timeout=seconds

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

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


Previous: Movemail Options, Up: movemail

2.6.3 Summary of Movemail Usage

     movemail [option...] inbox destfile [remote-password]

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

Following is the summary of available command line options:

--emacs
Output information used by Emacs rmail interface
-p
--preserve
--keep-messages
Preserve the source mailbox
-r
--reverse
Reverse the sorting order
--license
Print GPL license and exit
--external-locker=program
Use given program as the external locker program.
--lock-expire-timeout=seconds
Set number of seconds after which the lock expires
--lock-flags=flags
Set locker flags. flags is composed of the following letters: ‘E’ – use external locker program dotlock, ‘R’ – retry 10 times if acquiring of the lock failed (see also --lock-retry-count below), ‘T’ – remove stale locks after 10 minutes (see also --lock-expire-timeout, and ‘P’ – write process PID to the lock file.
--lock-retry-count=number
Set the maximum number of times to retry acquiring the lockfile
--lock-retry-timeout=seconds
Set timeout for acquiring the lockfile
-m url
--mail-spool URL
Use specified URL as a mailspool directory
--tls[=bool]
Enable (default) or disable TLS support


Next: , Previous: movemail, Up: Programs

2.7 readmsg — Extract Messages from a Folder

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

  1. A lone ‘*’ means “select all messages in the mailbox”.
  2. A list of message numbers may be specified. Values of ‘0’ and ‘$’ in the list both mean the last message in the mailbox. For example:
              readmsg 1 3 0
    

    extracts three messages from the folder: the first, the third, and the last.

  3. Finally, the selection may be some text to match. This will select a mail message which exactly matches the specified text. For example,
              readmsg staff meeting
    

    extracts the message which contains the words ‘staff meeting’. Note that it will not match a message containing ‘Staff Meeting’ – the matching is case sensitive. Normally only the first message which matches the pattern is printed.


Next: , Up: readmsg

2.7.1 Invocation of readmsg.

-a
--show-all
If a pattern is use for selection show all messages that match pattern by default only the first one is presented.
-d
--debug
Display mailbox debugging information.
-f mailbox
--folder=mailbox
Specified the default mailbox.
-h
--header
Show the entire header and ignore the weedlist.
-n
--no-header
Do not print the message header.
-p
--form-feed
Put form-feed (Control-L) between messages instead of newline.


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


Previous: Opt-readmsg, Up: readmsg

2.7.2 Configuration of readmsg.

Following configuration statements affect the behavior of readmsg:

— Readmsg Conf: header bool

If bool is ‘true’, display entire headers.

— Readmsg Conf: weedlist str

Set the weedlist. The str argument is a string, containing a list of header names, separated by whitespace, commands or colons. This corresponds to the --weedlist command line option (see –weedlist).

— Readmsg Conf: no-header bool

If bool is ‘true’, exclude all headers.

— Readmsg Conf: form-feeds bool

If bool is ‘true’, output formfeed character between messages.

— Readmsg Conf: folder url

Set the URL of the mailbox folder to read.

— Readmsg Conf: show-all-match bool

If bool is ‘true’, print all messages matching pattern, not only the first.

Statement Reference
debug See Debug Statement.
tls See TLS Statement.
mailbox See Mailbox Statement.
locking See Locking Statement.


Next: , Previous: readmsg, Up: Programs

2.8 sieve

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


Next: , Up: sieve

2.8.1 A Sieve Interpreter

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


Next: , Up: sieve interpreter
Invoking sieve

The sieve invocation syntax is:

     sieve [options] script

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

-c
--compile-only
Compile script and exit.
--clear-library-path
--clearpath
Clear Sieve library path. See also clear-library-path.
--clear-include-path
Clear Sieve include path. See also clear-include-path.
-d[flags]
--debug[=flags]
Specify debug flags. The flags argument is a sequence of one or more of the following letters:

gEnable main parser traces
TEnable mailutils traces
PTrace network protocols
tEnable sieve trace
iTrace the program instructions

-D
--dump
Compile the script, dump disassembled code on standard output and exit.
-e address
--email address
Override the user email address. This is useful for reject and redirect actions. By default, the user email address is deduced from the user name and the full name of the machine where sieve is executed. See also email.
-I dir
--includedir=dir
Append directory dir to the list of directories searched for include files. See also include-path.
-f
--mbox-url=mbox
Mailbox to sieve (defaults to user's system mailbox). See also mbox-url.
-k
--keep-going
Keep on going if execution fails on a message. See also keep-going.
-L dir
--libdir=dir
Append directory dir to the list of directories searched for library files. See also library-path.
-n
--no-actions
Dry run: do not execute any actions, just print what would be done.
-t ticket
--ticket=ticket
Ticket file for mailbox authentication. See also ticket.
-v
--verbose
Log all actions executed. See also verbose.


Next: , Previous: Invoking Sieve, Up: sieve interpreter
Sieve Configuration

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

Statement Reference
debug See Debug Statement.
tls See TLS Statement.
mailbox See Mailbox Statement.
locking See Locking Statement.
logging See Logging Statement.
mailer See Mailer Statement.

The following statements configure sieve-specific features:

— Sieve Conf: sieve { ... }

This block statement configures search paths sieve uses to locate its loadable modules. See Require Statement, for a detailed information of this feature.

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

— Sieve Conf: clear-library-path bool

Used within the sieve block statement.

If bool is ‘true’, clear library search path.

— Sieve Conf: clear-include-path bool

Used within the sieve block statement.

If bool is ‘true’, clear include search path.

— Sieve Conf: library-path path

Used within the sieve block statement.

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

— Sieve Conf: include-path path

Used within the sieve block statement.

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

— Sieve Conf: keep-going bool

If bool is ‘true’, do not abort if execution of a Sieve script fails on a particular message.

— Sieve Conf: mbox-url url

Sets URL of the mailbox to be processed.

— Sieve Conf: ticket file

Sets the name of the ticket file for user authentication.

— Sieve Conf: debug flags

Sets Sieve debug flags. See Logging and Debugging, for a detailed description.

— Sieve Conf: verbose bool

If bool is ‘true’, log all executed actions.

— Sieve Conf: line-info bool

If bool is ‘true’, print source locations along with action logs. This statement takes effect only if verbose true is also set.

— Sieve Conf: email addr

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


Next: , Previous: Sieve Configuration, Up: sieve interpreter
Logging and debugging

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

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

t
This flag enables sieve tracing. It means that every test will be logged when executed.
T
This flag enables debugging of underlying mailutils library.
P
Trace network protocols: produces log of network transactions executed while running the script.
g
Enable main parser traces. This is useful for debugging the sieve grammar.
i
Trace the program instructions. It is the most extensive debugging level. It produces the full execution log of a sieve program, showing each instruction and states of the sieve machine. It is only useful for debugging the code generator.

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

If the argument to --debug is omitted, it defaults to ‘TPt’.

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

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


Previous: Logging and Debugging, Up: sieve interpreter
Extending sieve

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

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

  1. Look up the name in a symbol table. If the name begins with ‘comparator-’ it is looked up in the comparator table. If it begins with ‘test-’, the test table is used instead. Otherwise the name is looked up in the action table.
  2. If the name is found, the search is terminated.
  3. Otherwise, transform the name. First, any ‘comparator-’ or ‘test-’ prefix is stripped. Then, any character other than alphanumeric characters, ‘.’ and ‘,’ is replaced with dash (‘-’). The name thus obtained is used as a file name of an external loadable module.
  4. Try to load the module. The module is searched in the following search paths (in the order given):
    1. Mailutils module directory. By default it is $prefix/lib/mailutils.
    2. The value of the environment variable LTDL_LIBRARY_PATH.
    3. Additional search directories specified with the library-path statement (see library-path) in Sieve configuration file.
    4. Additional search directories specified with the. --libdir command line option ().
    5. Additional search directories specified with the #searchpath Sieve directive (see #searchpath).
    6. System library search path: The system dependent library search path (e.g. on Linux it is set by the contents of the file /etc/ld.so.conf and the value of the environment variable LD_LIBRARY_PATH).

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

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

    1. the libtool archive extension ‘.la
    2. the extension used for native dynamic libraries on the host platform, e.g., ‘.so’, ‘.sl’, etc.
  5. If the module is found, sieve executes its initialization function (see below) and again looks up the name in the symbol table. If found, search terminates successfully.
  6. If either the module is not found, or the symbol wasn't found after execution of the module initialization function, search is terminated with an error status. sieve then displays the following diagnostic message:
              source for the required action NAME is not available
    


Previous: sieve interpreter, Up: sieve

2.8.2 A Sieve to Scheme Translator and Filter

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

-f filename
--file filename
Set input file name.
-o filename
--output filename
Set output file name
-L dirname
--lib-dir dirname
Set sieve library directory name
-d level
--debug level
Set debugging level

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


Next: , Previous: sieve, Up: Programs

2.9 guimb — A Mailbox Scanning and Processing Language

Guimb is for mailboxes what awk is for text files. It processes mailboxes, applying the user-supplied scheme procedures to each of them in turn and saves the resulting output in mailbox format.

The following configuration statements affect the behavior of guimb:

Statement Reference
debug See Debug Statement.
mailbox See Mailbox Statement.
locking See Locking Statement.


Next: , Up: guimb

Specifying Scheme Program to Execute

The Scheme program or expression to be executed is passed to guimb via the following options:

-s file
--source file
Load Scheme source code from file.
-c expr
--code expr
Execute given scheme expression.

The above switches stop further argument processing, and pass all remaining arguments as the value of (command-line).

If the remaining arguments must be processed by guimb itself, use following options:

-e expr
--expression expr
Execute scheme expression.
-f file
--file file
Load Scheme source code from file.

You can specify both of them. In this case, the file is read first, then expr is executed. You may still pass any additional arguments to the script using --guile-arg option.


Next: , Previous: Specifying Scheme Program to Execute, Up: guimb

Specifying Mailboxes to Operate Upon

There are four basic ways of passing mailboxes to guimb.

guimb [options] [mailbox...]
The resulting mailbox is not saved, unless the user-supplied scheme program saves it.
guimb [options] --mailbox defmbox
The contents of defmbox is processed and is replaced with the resulting mailbox contents. Useful for applying filters to user's mailbox.
guimb [options] --mailbox defmbox mailbox [mailbox...]
The contents of specified mailboxes is processed, and the resulting mailbox contents is appended to defmbox.
guimb [options] --user username [mailbox...]
The contents of specified mailboxes is processed, and the resulting mailbox contents is appended to the user's system mailbox. This allows to use guimb as a mail delivery agent.

If no mailboxes are specified in the command line, guimb reads and processes the system mailbox of the current user.


Next: , Previous: Specifying Mailboxes to Operate Upon, Up: guimb

Passing Options to Scheme

Sometimes it is necessary to pass some command line options to the scheme procedure. There are three ways of doing so.

When using --source (-s) or --code (-c) options, all the rest of the command line following the option's argument is passed to Scheme program verbatim. This allows for making guimb scripts executable by the shell. If your system supports ‘#!’ magic at the start of scripts, add the following two lines to the beginning of your script to allow for its immediate execution:

     #! /usr/local/bin/guimb -s
     !#

(replace ‘/usr/local/bin/’ with the actual path to the guimb).

Otherwise, if you use --file or --expression options, the additional arguments may be passed to the Scheme program -g (--guile-arg) command line option. For example:

     guimb --guile-arg -opt --guile-arg 24 --file progfile

In this example, the scheme procedure will see the following command line:

     progfile -opt 24

Finally, if there are many arguments to be passed to Scheme, it is more convenient to enclose them in -{ and -} escapes:

     guimb -{ -opt 24 -} --file progfile


Previous: Passing Options to Scheme, Up: guimb

Command Line Option Summary

This is a short summary of the command line options available to guimb.

-d
--debug
Start with debugging evaluator and backtraces.
-e expr
--expression expr
Execute given Scheme expression.
-m path
--mail-spool=path
Set path to the mailspool directory
-f progfile
--file progfile
Read Scheme program from progfile.
-g arg
--guile-command arg
Append arg to the command line passed to Scheme program.
-{ ... -}
Pass all command line options enclosed between -{ and -} to Scheme program.
-m
--mailbox mbox
Set default mailbox name.
-u
--user name
Act as local MDA for user name.
-h
--help
Display help message.
-v
--version
Display program version.


Next: , Previous: guimb, Up: Programs

2.10 maidag

The name ‘maidag’ stands for Mail delivery agent. It is a general-purpose MDA offering a rich set of features. It can operate both in traditional mode, reading the message from its standard input, and in LMTP mode. Maidag is able to deliver mail to any mailbox format, supported by GNU Mailutils. These formats, among others, include ‘remote+smtp’, ‘remote+prog’ and ‘remote+sendmail’ which are equivalent to forwarding a message over SMTP to a remote node. Thus, maidag supersedes both mail.local and mail.remote utilities from GNU Mailutils versions prior to 2.0.

Maidag is also able to process incoming messages using Sieve or Scheme scripts and, based on results of this processing, to take a decision on whether to actually deliver and where to deliver them. Due to its extensive scripting facilities, maidag offers much more flexibility than other popular MDAs, such as procmail.


Next: , Up: maidag

2.10.1 Using maidag with Sendmail.

When used as a MDA with Sendmail, maidag must be invoked from the local mailer definition in the sendmail.cf file. It must have the following flags set: ‘lswS’. These mean: the mailer is local, quote characters should be stripped off the address before invoking the mailer, the user must have a valid account on this machine and the userid should not be reset before calling the mailer. Additionally, the flags ‘fn’ may be specified to allow maidag to generate the usual ‘From ’ envelope instead of the one supplied by sendmail.

If you wish to use maidag with non-local authentication, such as SQL or LDAP, you also need to remove the ‘w’ flag, since in that case the user is not required to have a valid account on the machine that runs sendmail.

Here is an example of mailer definition in sendmail.cf

     Mlocal, P=/usr/local/sbin/maidag,
             F=lsDFMAw5:/|@qSPfhn9,
             S=EnvFromL/HdrFromL, R=EnvToL/HdrToL,
             T=DNS/RFC822/X-Unix,
             A=mail $u

To define local mailer in ‘mc’ source file, it will suffice to set:

     define(`LOCAL_MAILER_PATH', `/usr/local/sbin/maidag')
     define(`LOCAL_MAILER_ARGS', `mail $u')


Next: , Previous: Sendmail-maidag, Up: maidag

2.10.2 Using maidag with Exim.

Using maidag with Exim is quite straightforward. The following example illustrates the definition of the appropriate transport and director in exim.conf:

     # transport
     maidag_pipe:
       driver = pipe
       command = /usr/local/sbin/maidag $local_part
       return_path_add
       delivery_date_add
       envelope_to_add
     
     # director
     maidag:
       driver = localuser
       transport = maidag_pipe


Next: , Previous: Exim-maidag, Up: maidag

2.10.3 Using maidag with MeTA1.

MeTA1 (http://meta1.org) communicates with the delivery agent using LMTP.

LMTP mode is enabled in maidag by the ‘lmpt yes’ statement. The socket to listen on must be specified using server statement (see Server Settings). For the purposes of this section, let's suppose maidag will listen on a UNIX socket /var/spool/meta1/lmtpsock. Then, the following (minimal) maidag configuration will do the job:

     # Start in LMTP mode.
     lmtp yes;
     # Run as daemon.
     mode daemon;
     # Switch to this group after startup.
     group meta1c;
     # Configure server:
     server unix:///var/spool/meta1/lmtpsock {
       transcript no;
     };

To configure MeTA1 to use this socket, add the following statement to the ‘smtpc’ section in /etc/meta1/meta1.conf:

       LMTP_socket="lmtpsock";


Next: , Previous: MeTA1-maidag, Up: maidag

2.10.4 Mailbox Quotas

Mailbox quota is a limit on the size of the mailbox. When a mailbox size reaches this limit, maidag stops accepting messages for this recipient and returns an error condition to the sender. The error code is accompanied by the following error message:

     user: mailbox quota exceeded for this recipient

Furthermore, if accepting the incoming message would make the mailbox size exceed the quota, such a message will be rejected as well. In this case, the error message is:

     user: message would exceed maximum mailbox size for this recipient

In both cases, the default return code will be ‘service unavailable’ (corresponding to the SMTP return code ‘550’), unless the following statement is present in the maidag configuration file:

     exit-quota-tempfail yes;

in which case a temporary error will be returned.

The mailbox quota can be retrieved from the following sources:

  1. Authentication method.
  2. DBM file.
  3. SQL database.


Next: , Up: Mailbox Quotas
2.10.4.1 Keeping Quotas in DBM File

To use DBM quota database, GNU Mailutils must be compiled with one of the following command line options: --with-gdbm, --with-berkeley-db, or --with-ndbm. Examine the output of maidag --show-config-options, if not sure.

The quota database should have the following structure:

Key
Key represents the user name. Special key ‘DEFAULT’ means default quota value, i.e. the one to be used if the user is not explicitly listed in the database.
Value
Mailbox quota for this user. If it is a number, it represents the maximum mailbox size in bytes. A number may optionally be followed by ‘kb’ or ‘mb’, meaning kilobytes and megabytes, respectively.

A special value ‘NONE’ means no mailbox size limit for this user.

Here is an example of a valid quota database

     # Default quota value:
     DEFAULT         5mb
     
     # Following users have unlimited mailbox size
     root            NONE
     smith           NONE
     
     # Rest of users
     plog            26214400
     karin           10mB

To use the DBM quota database, specify its absolute name using quota-db configuration statement, e.g.:

     quota-db /etc/mail/quota.db;


Previous: DBM Quotas, Up: Mailbox Quotas
2.10.4.2 Keeping Quotas in SQL Database

Configuration statement quota-query allows to specify a special query to retrieve the quota from the database. Currently (as of mailutils version 2.0) it is assumed that this table can be accessed using the credentials set in ‘sql’ configuration statement (see SQL Statement).

For example, suppose you have the following quota table:

     create table mailbox_quota (
       user_name varchar(32) binary not null,
       quota int,
       unique (user_name)
     );

To retrieve user quota the following query can be used:

     SELECT quota FROM mailbox_quota WHERE user_name='${user}'

There are no special provisions for specifying group quotas, similar to ‘DEFAULT’ in DBM databases. This is because group quotas can easily be implemented using SQL language. Maidag always uses the first tuple from the set returned by mailbox quota query. So, you may add a special entry to the mailbox_quota table that would keep the group quota. In the discussion below we assume that the user_name column for this entry is lexicographically less than any other user name in the table. Let's suppose the group quota name is ‘00DEFAULT’. Then the following query:

     SELECT quota
     FROM mailbox_quota
     WHERE user_name IN ('${user}','00DEFAULT')
     ORDER BY user_name DESC

will return two tuples if the user is found in mailbox_quota. Due to ORDER statement, the first tuple will contain the quota for the user, which will be used by maidag. On the other hand, if the requested user name is not present in the table, the above query will return a single tuple containing the group quota.

The following configuration statement instructs maidag to use this query for retrieving the user quota:

     quota-query "SELECT quota "
                 "FROM mailbox_quota "
                 "WHERE user_name IN ('${user}','00DEFAULT') "
                 "ORDER BY user_name DESC";


Next: , Previous: Mailbox Quotas, Up: maidag

2.10.5 Maidag Scripting

Maidag can use global or per-user mail filters to decide whether to deliver the message, and where to deliver it. As of Mailutils version 2.0, such mail filters may be written in the following languages:


Next: , Up: Maidag Scripting
2.10.5.1 Sieve Maidag Filters

The file name of the Sieve filter to use is specified using ‘sieve-filter’ configuration statement. The following meta-symbols can be used in its argument:

~
%h
Expands to the recipient home directory.
%u
Expands to the recipient user name.

For example, the following configuration statement:

     sieve-filter "~/.maidag.sv"

instructs maidag to use file .maidag.sv in the recipient home directory as a Sieve filter.

Normal message delivery is attempted if execution of the Sieve code ended with keep action (either implicit or explicit).

Other Sieve actions are executed as described in Actions. For example, to deliver message to another mailbox, use the fileinto action.

Any modifications to headers or body of the message performed by the Sieve code will be visible in the delivered message.


Previous: Sieve Maidag Filters, Up: Maidag Scripting
2.10.5.2 Scheme Maidag Filters

The file name of the Scheme mail filter is specified using ‘guile-filter’ configuration statement. This statement is processed as described in Sieve Maidag Filters.

Only one of guile-filter or sieve-filter may be used. The behavior of maidag if both statements are used is undefined.


Next: , Previous: Maidag Scripting, Up: maidag

2.10.6 Forwarding

Forward file is a special file in the user's home directory that contains the email address of the mailbox where the user wants to forward his mail. Normally, forward files are processed by MTA. However, there are some MTA that lack this feature. One of them is MeTA1.

Maidag provides a forwarding feature that is useful to compensate the lack of it.

Name of the forward file is given using forward-file configuration statement. A common usage is:

     forward-file .forward;

The forward file is always searched in the recipient home directory.

Before actually using the file, a number of safety checks are performed on it. If the file fails to pass one of these checks, no forwarding is performed and the message is delivered as usual. These checks can be configured using forward-file-checks statement. Its argument is a list of the following keywords:

groupwritablefile
file_iwgrp
The file must not be group writable.
worldwritablefile
file_iwoth
The file must not be world writable.
linkedfileinwritabledir
link
The file cannot be a symlink in a writable directory.
fileingroupwritabledir
dir_iwgrp
The file cannot reside in a group writable directory.
fileinworldwritabledir
dir_iwoth
The file cannot reside in a world writable directory.
all
All of the above checks.

The default is ‘forward-file-checks all’.

Each of these keywords may be prefixed by ‘no’ to disable this particular check. For example:

     forward-file-checks (nodir_iwoth, nodir_iwgrp);


Next: , Previous: Forwarding, Up: maidag

2.10.7 Delivering Messages to a URL.

When invoked with the --url command line option, maidag treats its arguments as a list of mailbox URLs and attempts to deliver the message to each of them.

For example:

     $ maidag --url maildir:///home/smith/Mail


Next: , Previous: Url-mode, Up: maidag

2.10.8 Remote Mailbox Delivery

Maidag can be used to deliver mail to remote mailboxes, such as ‘imap’ or ‘remote+smtp’. If the mailbox URL is ‘remote+smtp’ or ‘remote+sendmail’, the message is actually forwarded over SMTP to the remote node, so maidag acts as a message transfer agent. For example:

     $ maidag --url remote+smtp://10.10.1.100:24

This command line will send the message to the machine ‘10.10.1.100’ using port ‘24’ (private mail system).

The ‘remote+prog’ mailbox may be of special use. Delivering to this mailbox results in invoking the specified command with the given arguments and passing the message to its standard input. There are two ways to specify a ‘remote+prog’ mailbox:

remote+prog://program?args
Here, program is the absolute pathname of the program binary, and args are its arguments, separated by ‘&’ signs.
|program args
In this notation, args are command line arguments separated by white space.

In both cases, args do not include argv[0].

The ‘remote+prog’ mailbox may be used, in particular, to implement mailing lists with MeTA1.

For example, suppose that the maidag configuration contains:

     auth {
       authorization sql:system;
       authentication generic:system;
     }
     
     sql {
       interface mysql;
       db mail;
       getpwnam "SELECT user as name, mailbox, "
                "'x' as passwd, 500 as uid, 2 as gid, "
                "'/nonexistent' as dir, '/sbin/nologin' as shell "
                "FROM userdb "
                "WHERE user='${user}'";
     }

Then, the following entries in the ‘userdb’ table implement mailman@yourdomain mailing list:

     mysql> select * from userdb;
     +---------------------+---------------------------------------+
     | user                | mailbox                               |
     +---------------------+---------------------------------------+
     | mailman             | |/usr/bin/mailman post mailman        |
     | mailman-admin       | |/usr/bin/mailman admin mailman       |
     | mailman-bounces     | |/usr/bin/mailman bounces mailman     |
     | mailman-confirm     | |/usr/bin/mailman confirm mailman     |
     | mailman-join        | |/usr/bin/mailman join mailman        |
     | mailman-leave       | |/usr/bin/mailman leave mailman       |
     | mailman-owner       | |/usr/bin/mailman owner mailman       |
     | mailman-request     | |/usr/bin/mailman request mailman     |
     | mailman-subscribe   | |/usr/bin/mailman subscribe mailman   |
     | mailman-unsubscribe | |/usr/bin/mailman unsubscribe mailman |
     +---------------------+---------------------------------------+


Previous: Remote Mailbox Delivery, Up: maidag

2.10.9 Maidag Configuration File Summary

The behavior of maidag is affected by the following configuration statements:

Statement Reference
debug See Debug Statement.
mailbox See Mailbox Statement.
locking See Locking Statement.
pam See PAM Statement.
sql See SQL Statement.
virtdomain See Virtdomain Statement.
radius See Radius Statement.
ldap See LDAP Statement.
auth See Auth Statement.
mailer See Mailer Statement.
server See Server Settings. Used only in LMTP mode.
acl See ACL Statement.
tcp-wrappers See Tcp-wrappers Statement.

— Maidag Config: ex-multiple-delivery-success bool

In case of multiple delivery, exit with code 0 if at least one delivery has succeeded.

— Maidag Config: ex-quota-tempfail bool

Indicate temporary failure if the recipient is over his mail quota. By default, permanent failure is returned. See Mailbox Quotas.

— Maidag Config: quota-db file

Set the name of DBM quota database file. See DBM Quotas.

— Maidag Config: sieve-filter pattern

Set file name or name pattern of the Sieve filter file. See Sieve Maidag Filters.

— Maidag Config: message-id-header name

When logging Sieve actions, identify messages by the value of this header.

— Maidag Config: guile-filter pattern

File name or name pattern for Guile filter file. See Scheme Maidag Filters.

— Maidag Config: debug flags

Set additional debugging flags. Valid flags are:

g
Print guimb stack traces.
t
Enable sieve trace (MU_SIEVE_DEBUG_TRACE).
i
Enable sieve instructions trace (MU_SIEVE_DEBUG_INSTR).
l
Log executed Sieve actions.

— Maidag Config: stderr bool

Log to stderr instead of syslog.

— Maidag Config: forward-file file

Process forward file file. See Forwarding.

— Maidag Config: forward-file-checks list

Configure safety checks for the forward file. See forward-file-checks.

— Maidag Config: lmtp bool

Run in LMTP mode.

— Maidag Config: group list

In LMTP mode, retain supplementary groups from list.

— Maidag Config: listen url

In LMTP mode, listen on url. Valid URLs are: ‘tcp://host:port’ (note that port is mandatory), ‘file://socket-file-name’ or ‘socket://socket-file-name’.

— Maidag Config: reuse-address bool

Reuse existing address (LMTP mode). Default is ‘yes’.


Next: , Previous: maidag, Up: Programs

2.11 mail.local — Deliver Mail to the Local UNIX Mailbox

Mail.local reads the standard input up to an end-of-file and appends the received data to the local mailboxes in UNIX mailbox format. This program is superseded by maidag (see maidag) and will be decommissioned in future releases.


Next: , Up: mail.local

2.11.1 Invoking mail.local

General usage of mail.local program is:

           mail.local [option...] recipient [recipient ...]

If recipient part is a FQDN, mail.local will attempt to deliver to a virtual host.

-f addr
--from addr
Specify the sender's name. This option forces mail.local to add ‘From ’ envelope to the beginning of the message. If it is not specified, mail.local first looks into the first line from the standard input. If it starts with ‘From ’, it is assumed to contain a valid envelope. If it does not, mail.local creates the envelope by using current user name and date.
-q
--quota-db file
Specify path to DBM mailbox quota database (see Mailbox Quotas).
--quota-query
Specify SQL query that should be used to obtain user mailbox quotas from the SQL database (see Mailbox Quotas).
-s pattern
--source pattern
Set name pattern for user-defined mail filters written in Scheme. The metacharacters ‘%u’ and ‘%h’ in the pattern are expanded to the current recipient user name and home directory correspondingly.

This option is available only if the package has been configured to use Guile extension language.

-S pattern
--sieve pattern
Set name pattern for user-defined mail filters written is Sieve. The metacharacters ‘%u’ and ‘%h’ in the pattern are expanded to the current recipient user name and home directory correspondingly.
-t number
--timeout number
Wait number seconds for acquiring the lockfile. If it doesn't become available after that amount of time, return failure. The timeout defaults to 5 minutes.
-x flags
--debug flags
Enable debugging. The debugging information will be output using syslog. The flags is a string consisting of the following flags: Debug flags are:
g
Start with guile debugging evaluator and backtraces. This is convenient for debugging user-defined filters.
T
Enable libmailutil traces (MU_DEBUG_TRACE).
P
Enable network protocol traces (MU_DEBUG_PROT)
t
Enable sieve trace (MU_SIEVE_DEBUG_TRACE)
l
Enable sieve action logs

The digits in the range ‘0’ – ‘9’ used in flags set mail.local debugging level.

-v
--version
Display program version and exit.
--ex-multiple-delivery-success
Don't return errors when delivering to multiple recipients.
--ex-quota-tempfail
Return temporary failure if disk or mailbox quota is exceeded. By default, 'service unavailable' is returned if the message exceeds the mailbox quota.


Previous: Invocation, Up: mail.local

2.11.2 Mail.local Configuration

The behavior of mail.local is affected by the following configuration statements:

Statement Reference
debug See Debug Statement.
mailbox See Mailbox Statement.
locking See Locking Statement.
pam See PAM Statement.
sql See SQL Statement.
virtdomain See Virtdomain Statement.
radius See Radius Statement.
ldap See LDAP Statement.
auth See Auth Statement.
mailer See Mailer Statement.

Additionally, mail.local defines the following configuration statements for its use:

— Mail.local Config: ex-multiple-delivery-success bool

In case of multiple delivery, exit with code 0 if at least one delivery has succeeded.

— Mail.local Config: ex-quota-tempfail bool

Indicate temporary failure if the recipient is over his mail quota. By default, permanent failure is returned.

— Mail.local Config: quota-db file

Set the name of DBM quota database file.

— Mail.local Config: sieve-filter pattern

Set file name or name pattern of the Sieve filter file.

The following meta-sequences are expanded in pattern:

~
%h
Expands to the recipient home directory.
%u
Expands to the recipient user name.

— Mail.local Config: message-id-header name

When logging Sieve actions, identify messages by the value of this header.

— Mail.local Config: guile-filter pattern

File name or name pattern for Guile filter file. See sieve-filter above, for the description if pattern.

— Mail.local Config: debug flags

Set additional debugging flags. Valid flags are:

g
Print guimb stack traces.
t
Enable sieve trace (MU_SIEVE_DEBUG_TRACE).
i
Enable sieve instructions trace (MU_SIEVE_DEBUG_INSTR).
l
Log executed Sieve actions.


Next: , Previous: mail.local, Up: Programs

2.12 mail.remote — Pseudo-Sendmail Interface for Mail Delivery

The mail.remote utility reads the standard input, which must be formatted as an RFC-2822 email message, and forwards it to the specified remote SMTP server. This utility is superseded by maidag and will be decommissioned in future releases. For a description of how to use maidag for remote delivery, Remote Mailbox Delivery.

This section provides a short overview of the mail.remote utility.

     $ mail.remote [option...] rcpt [rcpt...]

Options are:

-b arg
Ignored, for compatibility with sendmail.
-d
--debug
Print envelope commands in SMTP protocol transaction. If specified more than once, the data part of the protocol transaction is also printed.
-f addr
--from=addr
Override the default from address.
-i
-o arg
Ignored, for for compatibility with sendmail.
-t
--read-recipients
Read recipient addresses from the message headers.
--debug-auth
Debug authentication functions.


Next: , Previous: mail.remote, Up: Programs

2.13 mimeview

For each file given in its command line, mimeview attempts to autodetect its type and invoke an appropriate file viewer.

To detect the file type, mimeview uses mime.types file. This file is a part of Common UNIX Printing System, mime.types. By default mimeview searches for mime.types in $prefix/etc/cups/2, however its exact location can be specified at runtime as well (see --mimetypes below).

Once file MIME type is successfully determined, mimeview consults mailcap files in order to determine how to display the file. It does so essentially in the same manner as metamail utility, i.e., it scans all files specified in METAMAIL environment variable until it finds an entry describing the desired file format or until the list of files is exhausted. If METAMAIL variable is not set, mimeview uses the following default path instead:

     $HOME/.mailcap:/usr/local/etc/mailcap:\
      /usr/etc/mailcap:/etc/mailcap:\
      /etc/mail/mailcap:/usr/public/lib/mailcap


Next: , Up: mimeview

2.13.1 Mimeview Invocation

The following table summarizes options specific for mimeview:

-a[type-list]
--no-ask[=type-list]
By default mimeview asks for confirmation before running interpreter to view a message. If this option is used without argument, it disables the default behavior for all message types. Otherwise, if argument type-list is given, it specifies a comma-separated list of MIME types for which no questions should be asked. Elements of this list may include shell-style globbing patterns, e.g. setting
          --no-ask='text/*,image/jpeg'

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

Notice, that when the long form is used, its argument must be separated from the option by a single equal sign, as shown in the example above. When the short form (-a) is used, its argument must follow the option immediately, without any intervening whitespace, e.g. -a'text/*').

-d[flags]
--debug[=flags]
Enables debugging output. Flags is a sequence of characters specifying the desired debugging level. Following characters are meaningful in flags:
g
Enables debugging of mime.types parser
l
Enables debugging of mime.types lexical analyzer (warning: produces very copious output)
1
Prints basic information about actions to be executed and reports about exit status of executed commands.
2
Additionally displays each file name along with its MIME type
3
Additionally traces the process of looking up the matching entry in mailcap files.
digits from 4 to 9
The same as 3, currently.

If flags are not given, the default ‘9’ is assumed.

--metamail[=file]
Run metamail to display files, instead of using the internal mechanisms. If file is specified, it is taken as metamail command line.
-h
--no-interactive
--print
This options tells mimeview that it should run in non-interactive mode. In this mode prompting is disabled, and the normal mailcap command field is not executed. Instead mimeview will execute the command specified in the print field. If there is nothing in the print field, the mailcap entry is ignored and the search continues for a matching mailcap entry that does have a print field.

Notice, that unlike in metamail -h, this option does not force mimeview to send the output to the printer daemon.

When used with --metamail option, this option passes -h flag to the invocation of metamail.

By default mimeview behaves as if given --no-interactive option whenever its standard input is not a tty device.

-n
--dry-run
Do not do anything, just print what would be done. Implies --debug=1, unless the debugging level is set up explicitly.
-t file
--mimetypes file
Use file as mime.types file. If file is a directory, use file/mime.types


Previous: Mimeview Invocation, Up: mimeview

2.13.2 Mimeview Config

The following configuration statements affect the behavior of mimeview:

Statement Reference
debug See Debug Statement.

— Mimeview Config: debug number

Set mimeview debug level. See –debug, for a description of debug levels.

— Mimeview Config: mimetypes file

Read file instead of the default mime.types.

— Mimeview Config: metamail program

Use program to display files.


Next: , Previous: mimeview, Up: Programs

2.14 POP3 Daemon

The pop3d daemon implements the Post Office Protocol Version 3 server.

pop3d has two operation modes:

Inetd
The server is started from /etc/inetd.conf file:
          pop3  stream tcp nowait  root  /usr/local/sbin/pop3d pop3d

This is the default operation mode.

Standalone
The server runs as daemon, forking a child for each new connection.

The server operation mode is configured using mode statement (see mode).


Next: , Up: pop3d

2.14.1 Login delay

POP3 clients often login frequently to check for new mail. Each new connection implies authenticating the user and opening his maildrop and can be very resource consuming. To reduce server load, it is possible to impose a minimum delay between any two consecutive logins. This is called ‘LOGIN-DELAY’ capability and is described in RFC 2449.

As of version 2.0, GNU Mailutils pop3d allows to set global login delay, i.e. such enforcement will affect all POP3 users. If a user attempts to log in before the specified login delay expires, he will get the following error message:

     -ERR [LOGIN-DELAY] Attempt to log in within the minimum login delay interval

The message will be issued after a valid password is entered. This prevents this feature from being used by malicious clients for account harvesting.

To enable the login delay capability, specify the minimum delay using login-delay configuration statement, e.g.:

     login-delay 60;

The pop3d utility keeps each user's last login time in a special DBM file, called login statistics database, so to be able to use this feature, Mailutils must be compiled with DBM support. By default, the login statistics database is called /var/run/pop3-login.db. You can change its name using stat-file configuration statement:

     login-delay 60;
     stat-file /tmp/pop.login;

Notice, that there is no need to include the ‘.db’ suffix in the file name.

The login delay facility will be enabled only if pop3d is able to access the statistics database for both reading and writing. If it is not, it will report this using syslog and start up without login delay restrictions. A common error message looks like:

     Unable to open statistics db: Operation not permitted

You can check whether your pop3d uses login delays by connecting to it and issuing the ‘CAPA’ command. If login delays are in use, there response will contain the string ‘LOGIN-DELAY n’, where n is the actual login delay value.


Next: , Previous: Login delay, Up: pop3d

2.14.2 Auto-expire

Automatic expiration of messages allows you to limit the period of time users are permitted to keep their messages on the server. It is enabled by expire configuration statement:

expire n;
Enable automatic expiration of messages after n days.

The current implementation works as follows. When a message is downloaded by RETR or TOP command, it is marked with ‘X-Expire-Timestamp: n’ header, where n is current value of UNIX timestamp. The exact expiration mechanism depends on you. Mailutils allows you two options:

  1. Expired messages are deleted by pop3d upon closing the mailbox. You specify this mechanism using delete-expired configuration statement:
    delete-expired bool;
    If bool is ‘true’, delete expired messages after receiving the QUIT command.
  2. Expired messages remain in the mailbox after closing it. The system administrator is supposed to run a cron job that purges the mailboxes. Such a cron job can be easily implemented using sieve from GNU Mailutils and the following script:
              require "timestamp";
              # Replace "5" with the desired expiration period
              if timestamp :before "X-Expire-Timestamp" "now - 5 days"
                {
                  discard;
                }
    

    This script will remove expired messages 5 days after the retrieval. Replace ‘5’ with the desired expiration period and make sure it equals the argument to expire configuration keyword.

The statement expire 0 means the client is not permitted to leave mail on the server. It always implies delete-expired true.


Next: , Previous: Auto-expire, Up: pop3d

2.14.3 Bulletins

The bulletin feature allows you to send important announcements to all POP3 users without mailing them. It works by creating a bulletin source mailbox and sending the announcements to it.

After a user successfully authenticates, pop3d checks the last bulletin number the user receives. The bulletin number refers to the number of the bulletin message in the bulletin source mailbox. If the latter contains more messages, these are appended to the user mailbox.

The user last bulletin number can be kept in two places. First, it can be stored in file .popbull in his home directory. Secondly, if Mailutils is compiled with DBM support, the numbers can be kept in a DBM file, supplied via bulletin-db configuration statement. If both the database and the .popbull file are present, the data from the database take precedence.

To enable this feature, use the following configuration statements:

bulletin-source mbox
Set the URL of the bulletin source mailbox.
bulletin-db file
Set the name of the database file to keep last bulletin numbers in. Be sure not to specify ‘.db’ extension.

The following example instructs pop3d to look for the bulletin messages in MH folder /var/spool/bull/mbox and to keep the database of last delivered bulletin numbers in /var/spool/bull/numbers.db:

     bulletin-source mh:/var/spool/bull/mbox;
     bulletin-db /var/spool/bull/numbers;


Next: , Previous: Bulletins, Up: pop3d

2.14.4 Pop3d Configuration

The following configuration file statements affect the behavior of pop3d.

Statement Reference
debug See Debug Statement.
tls See TLS Statement.
mailbox See Mailbox Statement.
locking See Locking Statement.
logging See Logging Statement.
pam See PAM Statement.
sql See SQL Statement.
virtdomain See Virtdomain Statement.
radius See Radius Statement.
ldap See LDAP Statement.
auth See Auth Statement.
server See Server Settings.
acl See ACL Statement.
tcp-wrappers See Tcp-wrappers Statement.

— Pop3d Conf: undelete bool

On startup, clear deletion marks from all the messages.

— Pop3d Conf: expire n

Automatically expire read messages after n days. 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: tls-required bool

Always require STLS command before entering authentication phase.

— Pop3d Conf: login-delay duration

Set the minimal allowed delay between two successive logins. 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.


Previous: Conf-pop3d, Up: pop3d

2.14.5 Command line options

The following table summarizes all pop3d command line options.

-d[number]
--daemon[=number]
Run in standalone mode. An optional number specifies the maximum number of child processes allowed to run simultaneously. When it is omitted, it defaults to 10 processes. Please note, that there should be no whitespace between the -d and its parameter.
-i
--inetd
Run in inetd mode.
-h
--help
Display short help message and exit.
--foreground
Remain in foreground.
--tls[=bool]
Enable TLS. If optional argument is supplied and is ‘false’, then disable it.
--debug-auth
Enable debugging of authentication functions.


Next: , Previous: pop3d, Up: Programs

2.15 IMAP4 Daemon

GNU imap4d is a daemon implementing imap4 rev1 protocol for accessing and handling electronic mail messages on a server. It can be run either as a standalone program or from inetd.conf file.


Next: , Up: imap4d

2.15.1 Namespace

GNU imap4d supports a notion of namespaces defined in RFC 2342. A namespace is a set of directories upon which the user has certain permissions. It should be understood that these permissions apply only if the underlying filesystem allows them.

The three namespaces supported by imap4d are:

Personal Namespace
A namespace that is within the personal scope of the authenticated user on a particular connection. The user has all permissions on this namespace.
Other Users' Namespace
A namespace that consists of mailboxes from the “Personal Namespaces” of other users. The user can read and list mailboxes from this namespace. However, he is not allowed to use ‘%’ and ‘*’ wildcards with LIST command, that is he can access a mailbox only if he knows exactly its location.
Shared Namespace
A namespace that consists of mailboxes that are intended to be shared amongst users and do not exist within a user's Personal Namespace. The user has all permissions on this namespace.

By default, imap4d starts with the following namespaces:

Personal Namespace
The home directory of the user, if exists.
Other Users' Namespace
Empty
Shared Namespace
Empty

Note, that this means that by default, a user won't be able to see or otherwise access mailboxes residing in the directories other than his own home.

To change these defaults, use shared-namespace and other-namespace configuration statements:

shared-namespace list
Set shared namespace.
other-namespace list
Set other users' namespace.

For both statements, the argument is a list of directories that belong to this namespace, e.g.:

     shared-namespace (/var/spool/mail,/var/mail);

If during the session the user creates a mailbox within either of these namespaces, the mode of the mailbox is determined by the following configuration statements:

shared-mailbox-mode mode
Set file mode for mailboxes created in shared namespace.
other-mailbox-mode mode
Set file mode for mailboxes created in other users' namespace.

In both cases, the argument, mode is a list of symbolic mode settings, similar to that used by chmod. It is a list of comma-separated mode change commands. Each command begins with a letter ‘g’, which means set mode bits for file group, or ‘o’, which means set mode bits for other users (note, that there is no ‘u’ specifier, since user ownership of his mailbox cannot be changed). This letter is followed by an ‘=’ (or ‘+’), and a list of modes to be set. This list can contain only two letters: ‘r’ to set read permission, and ‘w’ to set write permission.

For example, the following statement sets read and write permissions for the group:

     shared-namespace-mode g=rw;


Next: , Previous: Namespace, Up: imap4d

2.15.2 Configuration of imap4d.

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

Statement Reference
debug See Debug Statement.
tls See TLS Statement.
mailbox See Mailbox Statement.
locking See Locking Statement.
logging See Logging Statement.
pam See PAM Statement.
sql See SQL Statement.
virtdomain See Virtdomain Statement.
radius See Radius Statement.
ldap See LDAP Statement.
auth See Auth Statement.
server See Server Settings.
acl See ACL Statement.
tcp-wrappers See Tcp-wrappers Statement.

— Imap4d Conf: shared-namespace list

Set shared namespace. List is a list of strings. See Namespace, for a detailed description.

— Imap4d Conf: other-namespace list

Set other users' namespace. List is a list of strings. See Namespace, for a detailed description.

— Imap4d Conf: shared-mailbox-mode str

Set file mode for mailboxes created within shared namespace. See Namespace, for a detailed description.

— Imap4d Conf: other-mailbox-mode str

Set file mode for mailboxes created within other users' namespace. See Namespace, for a detailed description.

— Imap4d Conf: login-disabled bool

Disable LOGIN command, if bool is ‘true’.

— Imap4d Conf: create-home-dir bool

Create nonexistent user home directories. See also home-dir-mode, below.

— Imap4d Conf: home-dir-mode mode

Set file mode for created user home directories. Mode is specified in octal.

The default value for mode is ‘700’ (‘drwx------’ in ls terms).

— Imap4d Conf: tls-required bool

Require successful STARTTLS command before entering authentication phase.

— Imap4d Conf: preauth mode

Configure PREAUTH mode. Valid arguments are:

prog:///program-name
Imap4d invokes an external program to authenticate the connection. The command line is obtained from the supplied string, by expanding the following meta-variables:
${client_address}
Remote IP address in dotted-quad notation;
${client_port}
Remote port number;
${server_address}
Local IP address;
${server_port}
Local port number.

If the connection is authenticated, the program should print the user name, followed by a newline character, on its standard output and exit with code ‘0’.

Otherwise, it should exit with a non-zero exit code.

ident[://:port]
The remote machine is asked about the requester identity using the identification protocol (RFC 1413). Both plaintext and DES encrypted replies are understood. Optional port specifies the port to use, if it differs from the default ‘113’. It can be either a decimal port number or a symbolic name of a service, listed in /etc/services.
stdio
PREAUTH mode is enabled automatically if imap4d is started from command line in interactive mode (-i command line option). The current login name is used as the user name.

— Imap4d Conf: preauth-only bool

If bool is ‘true’, use only preauth mode. If unable to setup it, disconnect immediately.

— Imap4d Conf: ident-keyfile file

Set DES keyfile for decoding encrypted ident responses. Used with ‘ident://’ preauth mode.

— Imap4d Conf: ident-encrypt-only bool

Use only encrypted IDENT responses.

— Imap4d Conf: id-fields list

Set list of fields to return in response to ID command.

Valid field names are:

name
Package name (‘GNU Mailutils’).
version
Package version (‘2.0’).
vendor
Vendor name (‘GNU’).
support-url
The string ‘http://www.gnu.org/software/mailutils
address
The string ‘51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA’.
os
OS name.
os-version
OS version number.
command
Name of the imap4d binary.
arguments
Invocation command line.
environment
List of environment variables with their values.


Previous: Conf-imap4d, Up: imap4d

2.15.3 Starting imap4d

imap4d may run either in standalone or in inetd operation modes. When run in “standalone” mode, the server disconnects from the terminal and runs as a daemon, forking a child for each new connection.

The “inetd” mode allows to start the server from /etc/inetd.conf file. This is the default operation mode.

     imap4  stream tcp nowait  root  /usr/local/sbin/imap4d imap4d

Command Line Options

-d[number]
--daemon[=number]
Run in standalone mode. An optional number specifies the maximum number of child processes the daemon is allowed to fork. When it is omitted, it defaults to 20 processes. Please note, that there should be no whitespace between the -d and its parameter.
-h
--help
Display short help message and exit.
-i
--inetd
Run in inetd mode.
--foreground
Run in foreground.
--preauth
Start in preauth mode
--tls[=bool]
Enable TLS support
--debug-auth
Debug authentication functions.
-v
--version
Display program version and exit.


Next: , Previous: imap4d, Up: Programs

2.16 Comsat Daemon

Comsatd is the server which receives reports of incoming mail and notifies users, wishing to get this service. It can be started either from inetd.conf or as a standalone daemon.


Next: , Up: comsatd

2.16.1 Starting comsatd

Comsatd uses following option groups: , , .

-C file
--convert-config=file
Convert the configuration file file to the new format. File must be a comsatd configuration file in Mailutils v. 1.x format. The converted file is printed on the standard output. For example, the following command can be used to convert old comsatd configuration file to new format:
          $ comsatd --convert-config=/etc/comsatd.conf > /etc/mailutils.d/comsatd

-d
--daemon
Run as a standalone daemon.
-i
--inetd
The server is started from /etc/inetd.conf file:
          comsat dgram  udp wait  root  /usr/sbin/comsatd \
          comsatd -c /etc/comsat.conf

This is the default operation mode.

-t
--test
Test mode. In this mode, comsatd takes two arguments: URL of a mailbox and QID of the message from that mailbox, e.g.:
          $ comsatd --test /var/mail/root 34589


Next: , Previous: Starting comsatd, Up: comsatd

2.16.2 Configuring comsatd

Following configuration statements affect the behavior of comsatd:

Statement Reference
debug See Debug Statement.
logging See Logging Statement.
mailbox See Mailbox Statement.
locking See Locking Statement.
acl See ACL Statement.


Next: , Up: Configuring comsatd
2.16.2.1 General Settings

These statements control the general behavior of the comsat daemon:

— Comsatd Conf: max-lines number

Set maximum number of message body lines to be output.

— Comsatd Conf: allow-biffrc bool

Enable or disable processing of user's .biffrc file. By default, it is enabled.


Previous: General Settings, Up: Configuring comsatd
2.16.2.2 Security Settings

These statements control the way comsatd fights possible flooding attacks.

— Comsatd Conf: max-requests number

Set maximum number of incoming requests per ‘request-control-interval’.

— Comsatd Conf: request-control-interval duration

Set the request control interval.

— Comsatd Conf: overflow-delay-time duration

Set initial amount of time to sleep, after the first overflow occurs.

— Comsatd Conf: overflow-control-interval duration

Set overflow control interval. If two consecutive overflows happen within that interval, the overflow-delay-time is doubled.


Previous: Configuring comsatd, Up: comsatd

2.16.3 A per-user Configuration File

By default, when a notification arrives, comsatd prints subject, from headers and the first five lines from the new message to the user's tty. The user is allowed to change this behavior by using his own configuration file. This file should be located in the user's home directory and should be named .biffrc. It must be owned by the user and have its permissions bits set to 0600. (Please note, that the use of per-user configuration files may be disabled, by specifying ‘allow-biffrc no’ in the main configuration file, see 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"


Next: , Previous: comsatd, Up: Programs

2.17 MH — The MH Message Handling System

The primary aim of this implementation is to provide an interface between Mailutils and Emacs using mh-e module.

To use Mailutils MH with Emacs, add the following line to your site-start.el or .emacs file:

(load "mailutils-mh")

For the information about the current state of Mailutils MH implementation please refer to file mh/TODO in the Mailutils distribution directory.

[FIXME]


Up: mh

2.17.1 Major differences between Mailutils MH and other MH implementations

  1. All programs use usual GNU long options. The support for MH single-dash options is provided for backward compatibility;
  2. UUCP addresses are not supported;
  3. Mailutils supports a set of new format specifications (see Format String Diffs);
  4. Mailutils provides a set of new profile variables (see Profile Variable Diffs);
  5. Several programs behave differently (see Program Diffs);


Next: , Up: Diffs
2.17.1.1 New and Differing MH Format Specifications

— MH Format: string decode (string str)

Decodes the input string str as per RFC 2047. Useful in printing ‘From:’, ‘To:’ and ‘Subject:’ headers.

Notice that, unlike the similar NMH function, decode checks the value of the global profile variable Charset (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.


Next: , Previous: Format String Diffs, Up: Diffs
2.17.1.2 New MH Profile Variables

— Variable: MH Variable string Charset

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


Previous: Profile Variable Diffs, Up: Diffs
2.17.1.3 Differences in MH Program Behavior
burst
The utility is able to burst both RFC 934 digest messages and MIME multipart messages. It provides two additional command line options: --recurse and --length.

The --recurse option instructs the utility to recursively expand the digest.

The --length option can be used to set the minimal encapsulation boundary length for RFC 934 digests. Default length is 1, i.e. encountering one dash immediately following a newline triggers digest decoding. It is OK for messages that follow RFC 934 specification. However, many user agents do not precisely follow it, in particular, they often do not escape lines starting with a dash by ‘- ’ sequence. Mailman is one of such agents. To cope with such digests you can set encapsulation boundary length to a higher value. For example, bounce --length=8 has been found to be sufficient for most Mailman-generated digests.

comp
Understands --build option.
fmtdump
This command is not provided. Use fmtcheck instead.
mhl
If the argument to ignores contains more than one component name it must be enclosed in double-quotes. Dangling equal sign is an error, to set a string variable to the empty value assign it an empty string, e.g.: overflowtext="" (see the supplied mhl.format file).

Interactive prompting is not yet implemented.

mhn

mhparam
The --all mode does not display commented out entries.
repl
Understands --use option. Disposition shell provides use command.
rmm
  1. Different behaviour if one of the messages in the list does not exist:

    Mailutils rmm does not delete any messages. Standard rmm in this case deletes all messages preceeding the non-existent one.

  2. The rmmproc profile component is not used.

pick
The non-standard command line syntax --field string), where field is any string, is deprecated. It is recognized only if pick is called from within another program, so that existing application continue to work. Please use the following syntax instead:
          pick --component field --pattern string

New command line option --cflags allows to control the type of regular expressions used. The option must occur right before --pattern or --component option (or one of its aliases, like --cc, --from, etc.)

The argument to this option is a string of type specifications:

B Use basic regular expressions
E Use extended regular expressions
I Ignore case
C Case sensitive

Default is ‘EI’.

The flags remain in effect until the next occurrence of --cflags option.

Sample usage:

          pick --cflag BC --subject '*a string'

The date comparison options (--before and --after accept date specifications in a wide variety of formats, e.g.:

          pick --after 20030301
          pick --after 2003-03-01
          pick --after 01-mar-2003
          pick --after 2003-mar-01
          pick --before '1 year ago'
          etc...

refile
  1. Linking messages between folders goes against the logic of Mailutils, so refile never makes links even if called with --link option. The latter is actually a synonym for --copy, which preserves the original message.
  2. The --preserve option is not implemented. It is retained for backward compatibility only.
  3. Message specs and folder names may be interspersed.

sortm
New option --numfield specifies numeric comparison for the given field.

Any number of --datefield, --textfield and --numfield options may be given, thus allowing to build sort criteria of arbitrary complexity.

The order of --.*field options sets the ordering priority. This differs from the behaviour of the standard sortm, which always orders datefield-major, textfield-minor.

Apart from sorting the mailfolder the following actions may be specified:

--list
List the ordered messages using a format string given by --form or --format option.
--dry-run
Do not actually sort messages, rather print what would have been done. This is useful for debugging purposes.


Previous: mh, Up: Programs

2.18 mailutils-config — Get the Information about the Mailutils Build

This program is designed for developers wishing to link their programs against libmailbox. It allows to examine the particulars of the current build of Mailutils and to get the command line parameters necessary for compiling and linking an application with Mailutils libraries.


Next: , Up: mailutils-config

Getting Compiler Flags

When invoked with the option --compile, or its short form -c, mailutils-config prints the flags that must be given to the compiler for compiling the program using Mailutils functions. An example usage:

     cc -omyprog.o `mailutils-config --compile` myprog.c


Next: , Previous: Compiler Flags, Up: mailutils-config

Getting Loader Flags

The --link, or its short form -l prints to the standard output the loader flags necessary to link a program against Mailutils libraries.

When invoked without arguments, it produces the flags necessary to link against the basic library of Mailutils: libmailbox. Arguments may be given that alter this behavior. These are:

auth
Print flags to link against libmuauth, the library adding new authentication methods to libmailbox.
guile
Print flags to link against libmu_scm, the Guile interface library.
mbox
Link against mbox format library.
mh
Link against mh format library.
maildir
Link against maildir format library.
mailer
Link against mailer library.
imap
Link against imap format library.
pop
Link against pop format library.
all
Link against all Mailutils format libraries.

The order of arguments does not matter.

For example, if you wrote a program myprog.c that uses standard unix mailbox format, mh format and the Guile interface, then you would link it with the following command:

     cc -omyprog myprog.o `mailutils-config --link mbox mh guile`


Previous: Loader Flags, Up: mailutils-config

Obtaining General Build Information

The --info, or -i retrieves the options (flags) used when building Mailutils. It may be used with or without arguments.

When used without arguments, it prints the list of all build flags, e.g.:

     $ mailutils-config --info
     VERSION=2.0
     SYSCONFDIR=/usr/local/etc
     MAILSPOOLDIR=/var/mail/
     SCHEME=mbox
     LOG_FACILITY=mail
     USE_LIBPAM
     HAVE_LIBLTDL
     WITH_GDBM
     WITH_GNUTLS
     WITH_GSASL
     WITH_GUILE
     WITH_PTHREAD
     WITH_READLINE
     HAVE_MYSQL
     ENABLE_VIRTUAL_DOMAINS
     ENABLE_IMAP
     ENABLE_POP
     ENABLE_MH
     ENABLE_MAILDIR
     ENABLE_SMTP
     ENABLE_SENDMAIL

When this option is used in conjunction with the --verbose option, a short description is printed to the right of each keyword, e.g.:

     $ mailutils-config --info --verbose
     VERSION=1.9.93             - Version of this package
     SYSCONFDIR=/usr/local/etc  - System configuration directory
     MAILSPOOLDIR=/var/mail/    - Default mail spool directory
     SCHEME=mbox                - Default mailbox type
     LOG_FACILITY=mail          - Default syslog facility
     USE_LIBPAM                 - PAM support
     HAVE_LIBLTDL               - a portable `dlopen' wrapper library
     WITH_GDBM                  - GNU DBM
     ...

This option also accepts any number of arguments. When these are given, each argument is treated as a name of a build flag. Mailutils-config checks if such a flag was defined and prints its full name if so. It exits with zero code if all the flags given on the command line are defined. Otherwise, it exits with code of 1.

The comparison of the flag names is case-insensitive. The arguments given need not include the leading prefix (i.e. the characters up to and including the first underscore character).

Given the previous example, the invocation

     $ mailutils --info readline use_libpam pop

will produce the following output:

     WITH_READLINE
     USE_LIBPAM
     ENABLE_POP

and will exit with a zero status.

The following command:

     $ mailutils --info readline gssapi pop

will exit with status 1, and will print:

     WITH_READLINE
     ENABLE_POP

since WITH_GSSAPI flag is not defined.

The flags and their meanings are:

USE_LIBPAM
The Mailutils uses pam libraries.
HAVE_LIBLTDL
The GNU wrapper library libltdl is present and is used by Mailutils. See Using libltdl, for more information on libltdl library.
WITH_BDB2
Support for Berkeley DB is compiled in (the package was configured with --with-db2 option).
WITH_NDBM
Support for NDBM is compiled in (the package was configured with --with-ndbm option).
WITH_OLD_DBM
Support for old style DBM is compiled in (the package was configured with --with-dbm option).
WITH_GDBM
Support for GNU DBM is compiled in (the package was configured with --with-gdbm option). See Introduction, for more information about this library.
WITH_GNUTLS
Support for GnuTLS (a Transport Layer Security Library) is compiled in (the package was configured with --with-gnutls option).
WITH_GSASL
Support for GNU SASL is compiled in (the package was configured with --with-gsasl option). See Introduction, for more information about this library.
WITH_GSSAPI
Support for gssapi is compiled in (the package was configured with --with-gssapi option).
WITH_GUILE
Support for Guile extension language is built (the package was configured with --with-guile option). See Overview, for more information about Guile.
WITH_PTHREAD
The posix thread support is compiled in.
WITH_READLINE
The readline support is enabled (the package was configured with --with-readline option). See Top, for more information.
HAVE_MYSQL
Authentication via MySQL is supported (the package was configured with --enable-mysql option).
ENABLE_VIRTUAL_DOMAINS
Support for mail virtual domains is enabled (the package was configured with --enable-virtual-domains option).
ENABLE_IMAP
Support for imap4 protocol is enabled.
ENABLE_POP
Support for pop3 protocol is enabled.
ENABLE_MH
Support for mailboxes in mh format is enabled.
ENABLE_MAILDIR
Support for mailboxes in Maildir format is enabled.
ENABLE_SMTP
Support for smtp mailer is enabled.
ENABLE_SENDMAIL
Support for Sendmail mailer is enabled.


Next: , Previous: Programs, Up: Top

3 Mailutils Libraries


Next: , Up: Libraries

3.1 Framework

Wherever the mail is and whatever format it is stored in, it is operated upon using the same set of functions. To unified the C API, GNU Mailutils offers a heteroclite set of objects that work in aggregation to do operations on emails. Each object does a specific task and delegates non-related tasks to others. The object comes alive by specifying a URL parameter when created, it will indicate the storage format or protocol (POP3, IMAP4, MH, MAILDIR, etc ..).

                               mu_folder_t                  mu_url_t
       -/var/mail-    +- .. ->+-------------------+   +-->+------------+
      (  alain *-)-+  |       |   mu_url_t      *-|---+   |   port     |
       ----------  |  |       |-------------------|       |   hostname |
      (  jakob *-)-+--+       |   mu_auth_t     *-|---+   |   file     |
       ----------  |          |-------------------|   |   |   ...      |
      (  jeff  *-)-+          |   mu_stream_t     |   |   +------------+
       ----------  |          |-------------------|   |
      (  shaleh*-)-+          |   .....           |   |    mu_auth_t
       ----------             |-------------------|   +-->+-------------+
                          +---|-* mu_mailbox_t[]  |       | mu_ticket_t |
       mu_mailbox_t       |   +-------------------+       +-------------+
      +-------------------+
      |   mu_locker_t  *--|-------------+
      |-------------------|             |
      |   mu_url_t        |             |          mu_locker_t
      |-------------------|             +-------->+---------+
      |   mu_stream_t     |                       | lock    |
      |-------------------|                       | unlock  |
      |  mu_message_t[] *-|-------+               +---------+
      +-------------------+       |                     mu_envelope_t
                                  |          +-------->+-----------+
       mu_message_t               |          |         | date      |
      +-------------------+<------+          |         | from      |
      |   mu_envelope_t *-|------------------+         | to        |
      |-------------------|              mu_header_t   +-----------+
      |   mu_header_t   *-|------------>+-----------------+
      |-------------------|             |   mu_stream_t   |
      |   mu_body_t     *-|----+        +-----------------+
      +-------------------+    |    mu_body_t
                               +-->+-----------------+
                                   |   mu_stream_t   |
                                   +-----------------+

As an example, here is a simplified version of from command. It lists the ‘From’ and ‘Subject’ headers of every mail in a mailbox.

     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     #ifdef HAVE_CONFIG_H
     # include <config.h>
     #endif
     #include <stdio.h>
     #include <stdlib.h>
     #include <string.h>
     #include <unistd.h>
     
     #include <mailutils/mailutils.h>
     
     int
     main (int argc, const char **argv)
     {
       char *from;
       char *subject;
       mu_mailbox_t mbox;
       size_t msgno, total = 0;
       int status;
     
       /* Register the formats. */
       mu_register_all_mbox_formats ();
     
       status = mu_mailbox_create_default (&mbox, argv[1]);
       if (status != 0)
         {
           mu_error ("mu_mailbox_create: %s", mu_strerror (status));
           exit (EXIT_FAILURE);
         }
     
       status = mu_mailbox_open (mbox, MU_STREAM_READ);
       if (status != 0)
         {
           mu_error ("mu_mailbox_open: %s", mu_strerror (status));
           exit (EXIT_FAILURE);
         }
     
       mu_mailbox_messages_count (mbox, &total);
     
       for (msgno = 1; msgno <= total; msgno++)
         {
           mu_message_t msg;
           mu_header_t hdr;
     
           if ((status = mu_mailbox_get_message (mbox, msgno, &msg)) != 0
               || (status = mu_message_get_header (msg, &hdr)) != 0)
             {
               mu_error ("Error message: %s", mu_strerror (status));
               exit (EXIT_FAILURE);
             }
     
           if (mu_header_aget_value (hdr, MU_HEADER_FROM, &from))
             from = strdup ("(NO FROM)");
     
           if (mu_header_aget_value (hdr, MU_HEADER_SUBJECT, &subject))
             subject = strdup ("(NO SUBJECT)");
     
           printf ("%s\t%s\n", from, subject);
           free (from);
           free (subject);
         }
     
       status = mu_mailbox_close (mbox);
       if (status != 0)
         {
           mu_error ("mu_mailbox_close: %s", mu_strerror (status));
           exit (EXIT_FAILURE);
         }
     
       mu_mailbox_destroy (&mbox);
       return 0;
     }

Here is a sample output produced by this program:

     

% ./sfrom pop://alain@localhost Passwd: xxxx Jim Meyering <meyering@foo.org> fetish(shellutils) beta François Pinard <pinard@bar.org> recode new alpha ...


Next: , Up: libmailbox

3.1.1 Folder

     /* Prefix mu_folder_ is reserved. */
     #include <mailutils/folder.h>
     
                                  mu_folder_t                mu_url_t
       -/var/mail-    +---//--->/-------------------\   +-->/-----------\
      (  alain *-)-+  |         |  mu_url_t       *-|---+   |  port     |
       ----------  |  |         |-------------------+       |  hostname |
      (  jakob *-)-+--+         |  mu_observer_t  *-|       |  file     |
       ----------  |            |-------------------+       |  ...      |
      (  jeff  *-)-+            |  mu_stream_t      |       \-----------/
       ----------  |            |-------------------|
      (  sean  *-)-+            |  mu_auth_t        |
       ----------               |-------------------|
                                |  mu_mailbox_t(1)  |
                                |-------------------|
                                |  mu_mailbox_t(2)  |
                                |  ......           |
                                |  mu_mailbox_t(n)  |
                                \-----------------/

Data structures:

     struct mu_list_response
     {
       int type;
       int separator;
       char *name;
     };
— Function: int mu_folder_create (mu_folder_t *, const char *url)
— Function: void mu_folder_destroy (mu_folder_t *)
— Function: int mu_folder_open (mu_folder_t, int flag)
— Function: int mu_folder_close (mu_folder_t)
— Function: int mu_folder_delete (mu_folder_t, const char *mailbox)
— Function: int mu_folder_rename (mu_folder_t, const char *, const char *mailbox)
— Function: int mu_folder_subscribe (mu_folder_t, const char *mailbox)
— Function: int mu_folder_unsubscribe (mu_folder_t, const char *mailbox)
— Function: int mu_folder_list (mu_folder_t, const char *ref, const char *wcard, size_t size, mu_list_t *list)
— Function: int mu_folder_lsub (mu_folder_t, const char *ref, const char *wcard, mu_list_t *list)
— Function: int mu_folder_get_stream (mu_folder_t, mu_stream_t *)
— Function: int mu_folder_set_stream (mu_folder_t, mu_stream_t)
— Function: int mu_folder_get_observable (mu_folder_t, mu_observable_t *)
— Function: int mu_folder_has_debug (mu_folder_t)
— Function: int mu_folder_get_debug (mu_folder_t, mu_debug_t *)
— Function: int mu_folder_set_debug (mu_folder_t, mu_debug_t)
— Function: int mu_folder_get_authority (mu_folder_t, mu_authority_t *)
— Function: int mu_folder_set_authority (mu_folder_t, mu_authority_t)
— Function: int mu_folder_get_url (mu_folder_t, mu_url_t *)
— Function: int mu_folder_set_url (mu_folder_t, mu_url_t)


Next: , Previous: Folder, Up: libmailbox

3.1.2 Mailbox

     /* Prefix mu_mailbox_ is reserved. */
     #include <mailutils/mailbox.h>
— Data Type: mu_mailbox_t

The mu_mailbox_t object is used to hold information and it is an opaque data structure to the user. Functions are provided to retrieve information from the data structure.

                                  mu_mailbox_t               mu_url_t
       -/var/mail-    +---//--->/------------------\   +-->/-----------\
      (  alain   )    |         |  mu_url_t      *-|---+   |  port     |
       ----------     |         |------------------+       |  hostname |
      (  jakob *-)----+         |  mu_observer_t *-|       |  file     |
       ----------               |------------------+       |  ...      |
      (  jeff    )              |  mu_stream_t     |       \-----------/
       ----------               |------------------|
      (  sean    )              |  mu_locker_t     |
       ----------               |------------------|
                                |  mu_message_t(1) |
                                |------------------|
                                |  mu_message_t(2) |
                                |  ......          |
                                |  mu_message_t(n) |
                                \------------------/
— Function: int mu_mailbox_create (mu_mailbox_t *mbox, const char *name)

The function mu_mailbox_create allocates and initializes mbox. The concrete mailbox type instantiate is based on the scheme of the url name.

The return value is 0 on success and a code number on error conditions:

MU_ERR_OUT_PTR_NULL
The pointer mbox supplied is NULL.
MU_ERR_NO_HANDLER
The url name supplied is invalid or not supported.
EINVAL
ENOMEM
Not enough memory to allocate resources.

— Function: int mu_mailbox_create_default (mu_mailbox_t *mbox, const char *name)

Create a mailbox with mu_mailbox_create() based on the environment variable MAIL or the string formed by _PATH_MAILDIR/user" or LOGNAME if user is null,

— Function: void mu_mailbox_destroy (mu_mailbox_t *mbox)

Destroys and releases resources held by mbox.

— Function: int mu_mailbox_open (mu_mailbox_t mbox, int flag)

A connection is open, if no stream was provided, a stream is created based on the mbox type. The flag can be OR'ed. See stream_create() for flag's description.

The return value is 0 on success and a code number on error conditions:

EAGAIN
EINPROGRESS
Operation in progress.
EBUSY
Resource busy.
MU_ERROR_INVALID_PARAMETER
mbox is NULL or flag is invalid.
ENOMEM
Not enough memory.

— Function: int mu_mailbox_close (mu_mailbox_t mbox)

The stream attach to mbox is closed.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is NULL.

— Function: int mu_mailbox_flush (mu_mailbox_t mbox, int expunge)
— Function: int mu_mailbox_get_folder (mu_mailbox_t mbox, folder_t *folder)

Get the folder.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is NULL.

— Function: int mu_mailbox_set_folder (mu_mailbox_t mbox, mu_folder_t folder)
— Function: int mu_mailbox_uidvalidity (mu_mailbox_t mbox, unsigned long *number);

Give the uid validity of mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is NULL.

— Function: int mu_mailbox_uidnext (mu_mailbox_t mbox, size_t *number);

Give the next predicted uid for mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is NULL.

— Function: int mu_mailbox_get_message (mu_mailbox_t mbox, size_t msgno, mu_message_t *message)

Retrieve message number msgno, message is allocated and initialized.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is NULL or msgno is invalid.
ENOMEM
Not enough memory.

— Function: int mu_mailbox_append_message (mu_mailbox_t mbox, mu_message_t message)

The message is appended to the mailbox mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is NULL or message is invalid.

— Function: int mu_mailbox_messages_count (mu_mailbox_t mbox, size_t *number);

Give the number of messages in mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is NULL.

— Function: int mu_mailbox_messages_recent (mu_mailbox_t mbox, size_t *number);

Give the number of recent messages in mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is NULL.

— Function: int mu_mailbox_message_unseen (mu_mailbox_t mbox, size_t *number);

Give the number of first unseen message in mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is NULL.

— Function: int mu_mailbox_expunge (mu_mailbox_t mbox)

All messages marked for deletion are removed.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is NULL.

— Function: int mu_mailbox_save_attributes (mu_mailbox_t mbox)
— Function: int mu_mailbox_get_size (mu_mailbox_t mbox, mu_off_t *size)

Gives the mbox size.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is NULL.

— Function: int mu_mailbox_is_updated (mu_mailbox_t mbox)
— Function: int mu_mailbox_scan (mu_mailbox_t mbox, size_t msgno, size_t *count);

Scan the mailbox for new messages starting at message msgno.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is NULL.
ENOMEM
Not enough memory.

— Function: int mu_mailbox_get_stream (mu_mailbox_t mbox, mu_stream_t *stream)

The mailbox stream is put in stream.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is invalid or stream is NULL.

— Function: int mu_mailbox_set_stream (mu_mailbox_t mbox, mu_stream_t stream)

Set the stream connection to use for the mailbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox or stream is NULL.

— Function: int mu_mailbox_get_locker (mu_mailbox_t mbox, mu_locker_t *locker)

Get the mu_locker_t object.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is NULL.

— Function: int mu_mailbox_set_locker (mu_mailbox_t mbox, mu_locker_t locker)

Set the type of locking done by the mbox.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is NULL.

— Function: int mu_mailbox_get_property (mu_mailbox_t mbox, mu_property_t *property)

Get the property object. The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is NULL.
ENOMEM

— Function: int mu_mailbox_get_url (mu_mailbox_t mbox, mu_url_t *url)

Gives the constructed url.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is NULL.

— Function: int mu_mailbox_has_debug (mu_mailbox_t mbox)
— Function: int mu_mailbox_get_debug (mu_mailbox_t mbox, mu_debug_t *debug)

Get a debug object. The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is NULL.
ENOMEM

— Function: int mu_mailbox_set_debug (mu_mailbox_t mbox, mu_debug_t debug)
— Function: int mu_mailbox_get_observable (mu_mailbox_t mbox mbox, mu_observable_t *observable)

Get the observable object.

The return value is 0 on success and a code number on error conditions:

MU_ERROR_INVALID_PARAMETER
mbox is NULL.
ENOMEM
Not enough memory.

— Function: int mu_mailbox_lock (mu_mailbox_t mbox)
— Function: int mu_mailbox_unlock (mu_mailbox_t mbox)


Next: , Previous: Mailbox, Up: libmailbox

3.1.3 Mailer

     /* Prefix mu_mailer_ is reserved. */
     #include <mailutils/mailer.h>
     
— Function: int mu_mailer_create (mu_mailer_t *, const char *url)
— Function: void mu_mailer_destroy (mu_mailer_t *)
— Function: int mu_mailer_open (mu_mailer_t, int flags)
— Function: int mu_mailer_close (mu_mailer_t)
— Function: int mu_mailer_send_message (mu_mailer_t mailer, mu_message_t msg, mu_address_t from, mu_address_t to);

If from is not NULL, it must contain a single fully qualified RFC2822 email address which will be used as the envelope from address. This is the address to which delivery status notifications are sent, so it never matters what it is set to until it really matters. This is equivalent to Sendmail's -f flag.

The default for from is provided by the specific mailer.

If to is not NULL, then the message will be sent to the list of addresses that it specifies.

The default for to is to use the contents of the standard "To:", "Cc:", and "Bcc:" fields, this is equivalent to Sendmail's -t flag.

— Function: int mu_mailer_get_property (mu_mailer_t, mu_property_t *)
— Function: int mu_mailer_get_stream (mu_mailer_t, mu_stream_t *)
— Function: int mu_mailer_set_stream (mu_mailer_t, mu_stream_t)
— Function: int mu_mailer_get_debug (mu_mailer_t, mu_debug_t *)
— Function: int mu_mailer_set_debug (mu_mailer_t, mu_debug_t)
— Function: int mu_mailer_get_observable (mu_mailer_t, observable_t *)
— Function: int mu_mailer_get_url (mu_mailer_t, url_t *)
— Function: int mu_mailer_check_from (mu_address_t from)
— Function: int mu_mailer_check_to (mu_address_t to)

Some Usage Notes

Some possible use cases the API must support are:

The Sendmail Mailer

/sbin/sendmail isn't always Sendmail... Sometimes it's a Sendmail-compatible wrapper, so assume /sbin/sendmail understands only a recipient list, -f and -oi, these seem to be pretty basic. Cross fingers.

Pipe to "/sbin/sendmail -oi [-f from] [to...]", supplying -f if there was a from, and supplying the recipient list from the to (if there is no recipient list, assume it will read the message contents for the recipients).

Caution: since the stdout and stderr of Sendmail is closed, we have no way of ever giving feedback on failure. Also, what should the return code be from mu_mailer_send_message() when Sendmail returns ‘1’? ‘1’ maps to EPERM, which is less than descriptive!

The SMTP Mailer

This mailer does not canonicalize the message. This must be done before sending the message, or it may be assumed that the MTA will do so.

It does blind out the Bcc: header before sending, though.

Caution: Mutt always puts the recipient addresses on the command line, even Bcc: ones, do we strip the Bcc: before forwarding with SMTP?

Non-RFC822 Addresses

An address that has no domain is not and RFC822 email address. What do I do with them? Should the user of the API be responsible for determining what is mean by email to "John" means? Or should the be able to configure Sendmail to decide globally what this means. If so, we can pass the address to Sendmail, but we have to decide for SMTP! So, right now these addresses are rejected. This could be changed.


Next: , Previous: Mailer, Up: libmailbox

3.1.4 Message

     /* Prefix mu_message_ is reserved. */
     #include <mailutils/message.h>
     

The mu_message_t object is a convenient way to manipulate messages. It encapsulates the envelope_t, the header_t and the body_t.

         mailbox_t
         ----------                   mu_message_t
        (message[1])        +------>+--------------------+
         ----------         |       |  mu_envelope_t     |
        (message[2])        |       |--------------------|
         ----------         |       |  mu_header_t       |
        (message[3])--------+       |--------------------|
         ----------                 |  mu_body_t         |
        (message[n])                |--------------------|
         ----------                 |  mu_attribute_t    |
                                    |--------------------|
                                    |  mu_stream_t       |
                                    +--------------------+
— Function: void mu_message_create (mu_message_t *msg, void *owner)
— Function: void mu_message_destroy (mu_message_t *msg, void *owner)

The resources allocate for msg are freed.

— Function: int mu_message_create_copy (mu_message_t *to, mu_message_t *from)
— Function: void* mu_message_get_owner (mu_message_t msg)
— Function: int mu_message_is_modified (mu_message_t msg)
— Function: int mu_message_clear_modified (mu_message_t msg)
— Function: int mu_message_get_mailbox (mu_message_t msg, mu_mailbox_t *mbox)
— Function: int mu_message_set_mailbox (mu_message_t msg, mu_mailbox_t mbox, void *owner)
— Function: int mu_message_ref (mu_message_t msg)
— Function: int mu_message_get_envelope (mu_message_t msg, mu_envelope_t *envelope)
— Function: int mu_message_set_envelope (mu_message_t msg, mu_envelope_t envelope, void *owner)
— Function: int mu_message_get_header (mu_message_t msg, mu_header_t *header)

Retrieve msg header.

— Function: int mu_message_set_header (mu_message_t msg, mu_header_t header, void *owner)
— Function: int mu_message_get_body (mu_message_t msg, mu_body_t *body)
— Function: int mu_message_set_body (mu_message_t msg, mu_body_t body, void *owner)
— Function: int mu_message_get_stream (mu_message_t msg, mu_stream_t *stream)
— Function: int mu_message_set_stream (mu_message_t msg, mu_stream_t stream, void *owner)
— Function: int mu_message_get_attribute (mu_message_t msg, mu_attribute_t *attribute)
— Function: int mu_message_set_attribute (mu_message_t msg, mu_attribute_t attribute, void *owner)
— Function: int mu_message_get_observable (mu_message_t msg, mu_observable_t *observable)
— Function: int mu_message_is_multipart (mu_message_t msg, int *multi)

Set *multi to non-zero value if msg is multi-part.

— Function: int mu_message_set_is_multipart (mu_message_t msg, int (*_is_multipart) (mu_message_t, int *), void *);
— Function: int mu_message_size (mu_message_t msg, size_t *size)
— Function: int mu_message_set_size (mu_message_t msg, int (*_size) (mu_message_t, size_t *), void *owner)
— Function: int mu_message_lines (mu_message_t msg, size_t *size)
— Function: int mu_message_set_lines (mu_message_t msg, int (*_lines) (mu_message_t, size_t *), void *owner)
— Function: int mu_message_get_num_parts (mu_message_t msg, size_t *nparts)
— Function: int mu_message_set_get_num_parts (mu_message_t msg, int (*_get_num_parts) (mu_message_t, size_t *), void *owner)
— Function: int mu_message_get_part (mu_message_t msg, size_t part, mu_message_t *msg)
— Function: int mu_message_set_get_part (mu_message_t msg, int (*_get_part) (mu_message_t, size_t, mu_message_t *), void *owner)
— Function: int mu_message_get_uidl (mu_message_t msg, char *buffer, size_t buflen, size_t *writen)
— Function: int mu_message_set_uidl (mu_message_t msg, int (*_get_uidl) (mu_message_t, char *, size_t, size_t *), void *owner)
— Function: int mu_message_get_uid (mu_message_t msg, size_t *uid)
— Function: int mu_message_set_uid (mu_message_t msg, int (*_get_uid) (mu_message_t, size_t *), void *owner)
— Function: int mu_message_create_attachment (const char *content_type, const char *encoding, const char *filename, mu_message_t *newmsg)
— Function: int mu_message_save_attachment (mu_message_t msg, const char *filename, void **data)
— Function: int mu_message_encapsulate (mu_message_t msg, mu_message_t *newmsg, void **data)
— Function: int mu_message_unencapsulate (mu_message_t msg, mu_message_t *newmsg, void **data);
— Function: int mu_message_get_attachment_name (mu_message_t msg, char *name, size_t bufsize, size_t *size);
— Function: int mu_message_aget_attachment_name (mu_message_t msg, char **name);
— Function: int mu_message_save_to_mailbox (mu_message_t msg, mu_ticket_t ticket, mu_debug_t debug, const char *toname);


Next: , Previous: Message, Up: libmailbox

3.1.5 Envelope

     /* Prefix mu_envelope_ is reserved. */
     #include <mailutils/envelope.h>
— Function: int mu_envelope_create (mu_envelope_t *, void *)

Primarily for internal use.

— Function: void mu_envelope_destroy (mu_envelope_t *, void *)

Primarily for internal use.

— Function: void* mu_envelope_get_owner (mu_envelope_t)
— Function: int mu_envelope_sender (mu_envelope_t, char *, size_t, size_t *)

Get the address that this message was reportedly received from. This would be the "mail from" argument if the message was delivered or received via SMTP, for example.

— Function: int mu_envelope_set_sender (mu_envelope_t, int (*_sender) (mu_envelope_t, char *, size_t, size_t *), void *)

Primarily for internal use. The implementation of mu_envelope_t depends on the mailbox type, this allows the function which actually gets the sender to be set by the creator of an mu_envelope_t.

— Function: int mu_envelope_date (mu_envelope_t, char *, size_t, size_t *)

Get the date that the message was delivered to the mailbox, in something close to ANSI ctime() format: Mon Jul 05 13:08:27 1999.

— Function: int mu_envelope_set_date (mu_envelope_t, int (*_date) (mu_envelope_t, char *, size_t, size_t *), void *)

Primarily for internal use. The implementation of mu_envelope_t depends on the mailbox type, this allows the function which actually gets the date to be set by the creator of an mu_envelope_t.


Next: , Previous: Envelope, Up: libmailbox

3.1.6 Headers

     /* Prefix mu_header_ is reserved. */
     #include <mailutils/header.h>
     

So far we plan support for RFC822 and plan for RFC1522. With RFC1522 non-ASCII characters will be encoded.

— Function: int mu_header_create (mu_header_t *hdr, const char *blurb, size_t len, void *owner)

Initialize a hdr to a supported type. If blurb is not NULL, it is parsed.

— Function: void mu_header_destroy (mu_header_t *hdr, void *owner)

The resources allocated for hdr are freed.

— Function: void* mu_header_get_owner (mu_header_t *hdr)
— Function: int mu_header_is_modified (mu_header_t hdr)
— Function: int mu_header_clear_modified (mu_header_t hdr)
— Function: int mu_header_set_value (mu_header_t hdr, const char *fn, const char *fv, int n)

Some basic macros are already provided for RFC822.

MU_HEADER_UNIX_FROM
From
MU_HEADER_RETURN_PATH
Return-Path
MU_HEADER_RECEIVED
Received
MU_HEADER_DATE
Date
MU_HEADER_FROM
From
MU_HEADER_SENDER
Sender
MU_HEADER_RESENT_FROM
Resent-From
MU_HEADER_SUBJECT
Subject
MU_HEADER_SENDER
Sender
MU_HEADER_RESENT_SENDER
Resent-SENDER
MU_HEADER_TO
To
MU_HEADER_RESENT_TO
Resent-To
MU_HEADER_CC
Cc
MU_HEADER_RESENT_CC
Resent-Cc
MU_HEADER_BCC
Bcc
MU_HEADER_RESENT_BCC
Resent-Bcc
MU_HEADER_REPLY_TO
Reply-To
MU_HEADER_RESENT_REPLY_TO
Resent-Reply-To
MU_HEADER_MESSAGE_ID
Message-ID
MU_HEADER_RESENT_MESSAGE_ID
Resent-Message-ID
MU_HEADER_IN_REPLY_TO
In-Reply-To
MU_HEADER_REFERENCE
Reference
MU_HEADER_REFERENCES
References
MU_HEADER_ENCRYPTED
Encrypted
MU_HEADER_PRECEDENCE
Precedence
MU_HEADER_STATUS
Status
MU_HEADER_CONTENT_LENGTH
Content-Length
MU_HEADER_CONTENT_LANGUAGE
Content-Language
MU_HEADER_CONTENT_TRANSFER_ENCODING
Content-transfer-encoding
MU_HEADER_CONTENT_ID
Content-ID
MU_HEADER_CONTENT_TYPE
Content-Type
MU_HEADER_CONTENT_DESCRIPTION
Content-Description
MU_HEADER_CONTENT_DISPOSITION
Content-Disposition
MU_HEADER_CONTENT_MD5
Content-MD5
MU_HEADER_MIME_VERSION
MIME-Version
MU_HEADER_X_UIDL
X-UIDL
MU_HEADER_X_UID
X-UID
MU_HEADER_X_IMAPBASE
X-IMAPbase
MU_HEADER_ENV_SENDER
X-Envelope-Sender
MU_HEADER_ENV_DATE
X-Envelope-Date
MU_HEADER_FCC
Fcc
MU_HEADER_DELIVERY_DATE
Delivery-date
MU_HEADER_ENVELOPE_TO
Envelope-to

— Function: int mu_header_get_value (mu_header_t hdr, const char *fn, char *fv, size_t len, size_t *n)

Value of field-name fn is returned in buffer fv of size len. The number of bytes written is put in n.

— Function: int mu_header_aget_value (mu_header_t hdr, const char *fn, char **fv)

The value is allocated.

— Function: int mu_header_get_address (mu_header_t hdr, const char *buf, address_t *addr)
— Function: int mu_header_get_stream (mu_header_t hdr, stream_t *stream)
— Function: int mu_header_set_stream (mu_header_t hdr, stream_t stream, void *)
— Function: int mu_header_get_field_count (mu_header_t hdr, size_t *count)
— Function: int mu_header_get_field_value (mu_header_t hdr, size_t index, char *, size_t, size_t *)
— Function: int mu_header_get_field_name (mu_header_t hdr, size_t index, char *, size_t, size_t *)
— Function: int mu_header_aget_field_value (mu_header_t hdr, size_t index, char **)
— Function: int mu_header_aget_field_name (mu_header_t hdr, size_t index, char **)
— Function: int mu_header_get_value_unfold (mu_header_t hdr, const char *name, char *buffer, size_t buflen, size_t *n)
— Function: int mu_header_aget_value_unfold (mu_header_t hdr, const char *name, char **value)
— Function: int mu_header_get_field_value_unfold (mu_header_t hdr, size_t num, char *buf, size_t buflen, size_t *nwritten)
— Function: int mu_header_aget_field_value_unfold (mu_header_t hdr, size_t num, char **value);
— Function: int mu_header_size (mu_header_t hdr, size_t *);
— Function: int mu_header_lines (mu_header_t hdr, size_t *);
— Function: int mu_header_set_set_value (mu_header_t hdr, int (*_set_value) (mu_header_t, const char *, const char *, int), void *);
— Function: int mu_header_set_get_value (mu_header_t hdr, int (*_get_value) (mu_header_t, const char *, char *, size_t, size_t *), void *);
— Function: int mu_header_set_get_fvalue (mu_header_t hdr, int (*_get_value) (mu_header_t, const char *, char *, size_t, size_t *), void *);
— Function: int mu_header_set_size (mu_header_t hdr, int (*_size) (mu_header_t, size_t *), void *);
— Function: int mu_header_set_lines (mu_header_t hdr, int (*_lines) (mu_header_t, size_t *), void *);
— Function: int mu_header_set_fill (mu_header_t hdr, int (*_fill) (mu_header_t, char *, size_t, mu_off_t, size_t *), void *owner);


Next: , Previous: Headers, Up: libmailbox

3.1.7 Body

     /* Prefix mu_body_ is reserved. */
     #include <mailutils/body.h>
— Function: int mu_body_create (mu_body_t *body, void *owner)

Initialize an object body.

— Function: void mu_body_destroy (mu_body_t *body)

The resources allocated are release.

— Function: void* mu_body_get_owner (mu_body_t body)
— Function: int mu_body_is_modified (mu_body_t body)
— Function: int mu_body_clear_modified (mu_body_t body)
— Function: int mu_body_get_stream (mu_body_t body, stream_t *stream)
— Function: int mu_body_set_stream (mu_body_t body, stream_t stream, void *owner)
— Function: int mu_body_get_filename (mu_body_t body, char *buffer, size_t buflen, size_t *writen)
— Function: int mu_body_size (mu_body_t body, size_t *size)
— Function: int mu_body_set_size (mu_body_t body, int (*_size) (mu_body_t, size_t *), void *owner)
— Function: int mu_body_lines (mu_body_t body, size_t *lines)
— Function: int mu_body_set_lines (mu_body_t body, int (*_lines) (mu_body_t, size_t *), void *owner)


Next: , Previous: Body, Up: libmailbox

3.1.8 Attribute

     /* Prefix mu_attribute_ is reserved. */
     #include <mailutils/attribute.h>
— Function: int mu_attribute_create (mu_attribute_t *attr, void *)
— Function: void mu_attribute_destroy (mu_attribute_t *attr, void *)
— Function: void* mu_attribute_get_owner (mu_attribute_t attr)
— Function: int mu_attribute_is_modified (mu_attribute_t attr)
— Function: int mu_attribute_clear_modified (mu_attribute_t attr)
— Function: int mu_attribute_set_modified (mu_attribute_t attr)
— Function: int mu_attribute_is_userflag (mu_attribute_t attr)
— Function: int mu_attribute_is_seen (mu_attribute_t attr)
— Function: int mu_attribute_is_answered (mu_attribute_t attr)
— Function: int mu_attribute_is_flagged (mu_attribute_t attr)
— Function: int mu_attribute_is_deleted (mu_attribute_t attr)
— Function: int mu_attribute_is_draft (mu_attribute_t attr)
— Function: int mu_attribute_is_recent (mu_attribute_t attr)
— Function: int mu_attribute_is_read (mu_attribute_t attr)
— Function: int mu_attribute_set_userflag (mu_attribute_t attr, int)
— Function: int mu_attribute_set_seen (mu_attribute_t attr)
— Function: int mu_attribute_set_answered (mu_attribute_t attr)
— Function: int mu_attribute_set_flagged (mu_attribute_t attr)
— Function: int mu_attribute_set_deleted (mu_attribute_t attr)
— Function: int mu_attribute_set_draft (mu_attribute_t attr)
— Function: int mu_attribute_set_recent (mu_attribute_t attr)
— Function: int mu_attribute_set_read (mu_attribute_t attr)
— Function: int mu_attribute_unset_userflag (mu_attribute_t attr, int)
— Function: int mu_attribute_unset_seen (mu_attribute_t attr)
— Function: int mu_attribute_unset_answered (mu_attribute_t attr)
— Function: int mu_attribute_unset_flagged (mu_attribute_t attr)
— Function: int mu_attribute_unset_deleted (mu_attribute_t attr)
— Function: int mu_attribute_unset_draft (mu_attribute_t attr)
— Function: int mu_attribute_unset_recent (mu_attribute_t attr)
— Function: int mu_attribute_unset_read (mu_attribute_t attr)
— Function: int mu_attribute_get_flags (mu_attribute_t attr, int *)
— Function: int mu_attribute_set_flags (mu_attribute_t attr, int)
— Function: int mu_attribute_unset_flags (mu_attribute_t attr, int)
— Function: int mu_attribute_set_set_flags (mu_attribute_t attr, int (*_set_flags) (mu_attribute_t, int), void *)
— Function: int mu_attribute_set_unset_flags (mu_attribute_t attr, int (*_unset_flags) (mu_attribute_t, int), void *)
— Function: int mu_attribute_set_get_flags (mu_attribute_t attr, int (*_get_flags) (mu_attribute_t, int *), void *)
— Function: int mu_attribute_is_equal (mu_attribute_t attr1, mu_attribute_t attr2)
— Function: int mu_attribute_copy (mu_attribute_t dst, mu_attribute_t src)
— Function: int mu_attribute_to_string (mu_attribute_t attr, char *buf, size_t len, size_t *writen)
— Function: int string_to_flags (const char *buf, int *)


Next: , Previous: Attribute, Up: libmailbox

3.1.9 Stream

     #include <mailutils/stream.h>

These generic flags are interpreted as appropriate to the specific streams.

MU_STREAM_READ
The stream is open read only.
MU_STREAM_WRITE
The stream is open write only.
MU_STREAM_RDWR
The stream is open read and write.
MU_STREAM_APPEND
The stream is open in append mode for writing.
MU_STREAM_CREAT
The stream open will create the underlying resource (such as a file) if it doesn't exist already.
MU_STREAM_NONBLOCK
The stream is set non blocking.
MU_STREAM_NO_CHECK
Stream is destroyed without checking for the owner.
MU_STREAM_SEEKABLE

MU_STREAM_NO_CLOSE
Stream doesn't close it's underlying resource when it is closed or destroyed.
MU_STREAM_ALLOW_LINKS
— Function: int mu_file_stream_create (mu_stream_t *stream, const char *filename, int flags)
— Function: int mu_tcp_stream_create (mu_stream_t *stream, const char *host, int port, int flags)
— Function: int mu_mapfile_stream_create (mu_stream_t *stream, const char *filename, int flags)
— Function: int mu_memory_stream_create (mu_stream_t *stream, const char *filename, int flags)
— Function: int mu_encoder_stream_create (mu_stream_t *stream, mu_stream_t iostream, const char *encoding)
— Function: int mu_decoder_stream_create (mu_stream_t *stream, mu_stream_t iostream, const char *encoding)
— Function: int mu_stdio_stream_create (mu_stream_t *stream, FILE *stdio, int flags)

If MU_STREAM_NO_CLOSE is specified, fclose() will not be called on stdio when the stream is closed.

— Function: int mu_prog_stream_create (mu_stream_t *stream, const char *progname, int flags)
— Function: int mu_filter_prog_stream_create (mu_stream_t *stream, const char *progname, mu_stream_t input)
— Function: void mu_stream_destroy (mu_stream_t *stream, void *owner)
— Function: int mu_stream_open (mu_stream_t stream)
— Function: int mu_stream_close (mu_stream_t stream)
— Function: int mu_stream_is_seekable (mu_stream_t stream)
— Function: int mu_stream_get_fd (mu_stream_t stream, int *fd)
— Function: int mu_stream_get_fd2 (mu_stream_t stream, int *fd1, int *fd2)
— Function: int mu_stream_read (mu_stream_t stream, char *buffer, size_t buflen, mu_off_t offset, size_t *writen)
— Function: int mu_stream_readline (mu_stream_t stream, char *buffer, size_t buflen, mu_off_t offset, size_t *writen)
— Function: int mu_stream_size (mu_stream_t stream, mu_off_t *size)
— Function: n int mu_stream_truncate (mu_stream_t stream, mu_off_t size)
— Function: int mu_stream_write (mu_stream_t stream, const char *buffer, size_t buflen, mu_off_t offset, size_t *writen)
— Function: int mu_stream_setbufsiz (mu_stream_t stream, size_t size)
— Function: int mu_stream_flush (mu_stream_t stream)
— Function: int mu_stream_create (mu_stream_t *stream, int flags, void *owner)

Used to implement a new kind of stream.

— Function: void* mu_stream_get_owner (mu_stream_t stream)
— Function: void mu_stream_set_owner (mu_stream_t stream, void *owner)
— Function: int mu_stream_get_flags (mu_stream_t stream, int *flags)
— Function: int mu_stream_set_flags (mu_stream_t stream, int flags)
— Function: int mu_stream_get_property (mu_stream_t stream, property_t *)
— Function: int mu_stream_set_property (mu_stream_t stream, property_t, void *)
— Function: int mu_stream_get_state (mu_stream_t stream, int *state)
MU_STREAM_STATE_OPEN
Last action was mu_stream_open.
MU_STREAM_STATE_READ
Last action was mu_stream_read or mu_stream_readline.
MU_STREAM_STATE_WRITE
Last action was mu_stream_write.
MU_STREAM_STATE_CLOSE
Last action was mu_stream_close.

— Function: int mu_stream_set_destroy (mu_stream_t stream, void (*_destroy) (mu_stream_t), void *owner)
— Function: int mu_stream_set_open (mu_stream_t stream, int (*_open) (mu_stream_t), void *owner)
— Function: int mu_stream_set_close (mu_stream_t stream, int (*_close) (mu_stream_t), void *owner)
— Function: int mu_stream_set_fd (mu_stream_t stream, int (*_get_fd) (mu_stream_t, int *, int *), void *owner)
— Function: int mu_stream_set_read (mu_stream_t stream, int (*_read) (mu_stream_t, char *, size_t, mu_off_t, size_t *), void *owner)
— Function: int mu_stream_set_readline (mu_stream_t stream, int (*_readline) (mu_stream_t, char *, size_t, mu_off_t, size_t *), void *owner)
— Function: int mu_stream_set_size (mu_stream_t stream, int (*_size) (mu_stream_t, mu_off_t *), void *owner)
— Function: int mu_stream_set_truncate (mu_stream_t stream, int (*_truncate) (mu_stream_t, mu_off_t), void *owner)
— Function: int mu_stream_set_write (mu_stream_t stream, int (*_write) (mu_stream_t, const char *, size_t, mu_off_t, size_t *), void *owner)
— Function: int mu_stream_set_flush (mu_stream_t stream, int (*_flush) (mu_stream_t), void *owner)
— Function: int mu_stream_set_strerror (mu_stream_t stream, int (*_fp) (mu_stream_t, char **), void *owner)
— Function: int mu_stream_sequential_readline (mu_stream_ts stream, char *buf, size_t size, size_t *nbytes)
— Function: int mu_stream_sequential_write (mu_stream_t stream, char *buf, size_t size)
— Function: int mu_stream_seek (mu_stream_t stream, mu_off_t off, int whence)
— Function: int mu_stream_strerror (mu_stream_t stream, char **p)

An example using mu_tcp_stream_create() to make a simple web client:

     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     /* This is an example program to illustrate the use of stream functions.
        It connects to a remote HTTP server and prints the contents of its
        index page */
     
     #ifdef HAVE_CONFIG_H
     # include <config.h>
     #endif
     #include <stdio.h>
     #include <stdlib.h>
     #include <string.h>
     #include <errno.h>
     #include <unistd.h>
     #include <sys/time.h>
     
     #include <mailutils/mailutils.h>
     
     char wbuf[1024];
     char rbuf[1024];
     
     size_t io_timeout = 3;
     size_t io_attempts = 3;
     
     int
     http_stream_wait (mu_stream_t stream, int flags, size_t *attempt)
     {
       int rc;
       int oflags = flags;
       struct timeval tv;
     
       while (*attempt < io_attempts)
         {
           tv.tv_sec = io_timeout;
           tv.tv_usec = 0;
           rc = mu_stream_wait (stream, &oflags, &tv);
           switch (rc) {
           case 0:
             if (flags & oflags)
               return 0;
             /* FALLTHROUGH */
           case EAGAIN:
           case EINPROGRESS:
             ++*attempt;
             continue;
     
           default:
             return rc;
           }
         }
       return ETIMEDOUT;
     }
     
     int
     main (int argc, char **argv)
     {
       int ret, off = 0;
       mu_stream_t stream;
       size_t nb, size;
       size_t attempt;
       char *url = "www.gnu.org";
     
       if (argc > 3)
         {
           fprintf (stderr, "usage: %s [hostname [url]]\n", argv[0]);
           exit (1);
         }
     
       if (argc > 1)
         url = argv[1];
     
       snprintf (wbuf, sizeof wbuf, "GET %s HTTP/1.0\r\n\r\n",
                 argc == 3 ? argv[2] : "/");
     
       ret = mu_tcp_stream_create (&stream, url, 80, MU_STREAM_NONBLOCK);
       if (ret != 0)
         {
           mu_error ("mu_tcp_stream_create: %s", mu_strerror (ret));
           exit (EXIT_FAILURE);
         }
     
       for (attempt = 0; (ret = mu_stream_open (stream)); )
         {
           if ((ret == EAGAIN || ret == EINPROGRESS) && attempt < io_attempts)
             {
               ret = http_stream_wait(stream, MU_STREAM_READY_WR, &attempt);
               if (ret == 0)
                 continue;
             }
           mu_error ("mu_stream_open: %s", mu_strerror (ret));
           exit (EXIT_FAILURE);
         }
     
       for (attempt = 0, size = strlen (wbuf); size > 0; )
         {
           ret = mu_stream_write (stream, wbuf + off, strlen (wbuf), 0, &nb);
           if (ret == 0)
             {
               if (nb == 0)
                 {
                   mu_error("mu_stream_write: wrote 0 bytes");
                   exit (EXIT_FAILURE);
                 }
               off += nb;
               size -= nb;
             }
           else if (ret == EAGAIN)
             {
               if (attempt < io_attempts)
                 {
                   ret = http_stream_wait (stream, MU_STREAM_READY_WR, &attempt);
                   if (ret)
                     {
                       mu_error ("http_wait failed: %s", mu_strerror (ret));
                       return -1;
                     }
                   continue;
                 }
               else
                 {
                   mu_error ("mu_stream_write timed out");
                   exit (EXIT_FAILURE);
                 }
             }
           else
             {
               mu_error ("mu_stream_write: %s", mu_strerror (ret));
               exit (EXIT_FAILURE);
             }
         }
     
       attempt = 0;
       for (;;)
         {
           ret = mu_stream_read (stream, rbuf, sizeof (rbuf), 0, &nb);
           if (ret == 0)
             {
               if (nb == 0)
                 break;
               write (1, rbuf, nb);
             }
           else if (ret == EAGAIN)
             {
               if (attempt < io_attempts)
                 {
                   ret = http_stream_wait (stream, MU_STREAM_READY_RD, &attempt);
                   if (ret)
                     {
                       mu_error ("http_stream_wait failed: %s", mu_strerror (ret));
                       exit (EXIT_FAILURE);
                     }
                 }
               else
                 {
                   mu_error ("mu_stream_read: %s", mu_strerror (ret));
                   exit (EXIT_FAILURE);
                 }
             }
         }
     
       ret = mu_stream_close (stream);
       if (ret != 0)
         {
           mu_error ("mu_stream_close: %s", mu_strerror (ret));
           exit (EXIT_FAILURE);
         }
     
       mu_stream_destroy (&stream, NULL);
       exit (EXIT_SUCCESS);
     }


Next: , Previous: Stream, Up: libmailbox

3.1.10 Iterator

     /* Prefix mu_iterator_ is reserved. */
     #include <mailutils/iterator.h>
— Function: int mu_iterator_create (mu_iterator_t *iterator, void *obj)
— Function: int mu_iterator_dup (mu_iterator_t *iterator, mu_iterator_t orig)
— Function: void mu_iterator_destroy (mu_iterator_t *)
— Function: int mu_iterator_first (mu_iterator_t)
&mdas