![[MU Poststamp]](/graphics/mustamp.png)
|
|
GNU Mailutils |
General-Purpose Mail Package |
Official GNU Software |
frm and from — List Headers from a Mailboxmail — Send and Receive Mail
messages — Count the Number of Messages in a Mailboxmovemail — Moves Mail from the User Maildrop to the Local File
readmsg — Extract Messages from a Folder
sieve
guimb — A Mailbox Scanning and Processing Languagemailutils-config — Get the Information about the Mailutils BuildThis edition of the GNU Mailutils Manual, last updated on 14 December 2010, documents GNU Mailutils Version 2.2.
GNU Mailutils is a rich and powerful protocol-independent mail framework. It contains a series of useful mail libraries, clients, and servers. These are the primary mail utilities for the GNU system. The central library is capable of handling electronic mail in various mailbox formats and protocols, both local and remote. Specifically, this project contains a POP3 server, an IMAP4 server, and a Sieve mail filter. It also provides a POSIX `mailx' client, and a collection of other handy tools.
The GNU Mailutils libraries supply an ample set of primitives for handling electronic mail in programs written in C, C++, Python or Scheme.
At the core of Mailutils is libmailutils, a library which provides universal access to various mailboxes and protocols: UNIX mailbox, Maildir, MH, POP3, IMAP4, Sendmail, SMTP. Mailutils offers functions for almost any mail-related task, such as parsing of messages, email addresses and URLs, handling MIME messages, listing mail folders, mailcap facilities, extensible Sieve filtering, access control lists. It supports various modern data security and authentication techniques: TLS encryption, SASL and GSSAPI, to name a few. The framework is able to work with a wide variety of authorization databases, ranging from traditional system password database up to RADIUS, SQL and LDAP.
The utilities provided by Mailutils include imap4d and pop3d mail servers, mail reporting utility comsatd, general-purpose mail delivery agent maidag, mail filtering program sieve, and an implementation of MH message handling system.
All utilities share the same subset of command line options and use a unified configuration mechanism, which allows to easily configure the package as a whole.
This software is part of the GNU Project and is copyrighted by the Free Software Foundation. All libraries are distributed under the terms of the Lesser GNU Public License. The documentation is licensed under the GNU FDL, and everything else is licensed under the GNU GPL.
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.
(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.
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.
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.
All GNU Mailutils programs understand a common subset of options.
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.
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 section Configuring Help Summary, for a detailed descriptions of it.
Print program version and exit.
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.
Load this configuration file, instead of the default.
Show configuration file summary.
Check configuration file syntax and exit
Verbosely log parsing of the configuration files.
Do not load site-wide configuration file.
Do not load user 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:
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.
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.
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.
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.
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.
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:
A number is a sequence of decimal digits.
A boolean value is one of the following: ‘yes’, ‘true’, ‘t’ or ‘1’, meaning true, and ‘no’, ‘false’, ‘nil’, ‘0’ meaning false.
An unquoted string may contain letters, digits, and any of the following characters: ‘_’, ‘-’, ‘.’, ‘/’, ‘:’.
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 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.
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);’.
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.
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.
logging {
# Set syslog facility.
facility name;
# Tag syslog messages with this string.
tag text;
}
|
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 |
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.
Tag syslog messages with text. By default, program name is used as syslog tag.
debug {
# Set Mailutils debugging level.
level spec;
# Prefix debug messages with Mailutils source locations.
line-info bool;
}
|
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:
Display only error messages.
Eight levels of verbosity, ‘trace0’ producing less output, ‘trace7’ producing maximum possible output.
Display network protocol interactions, where appropriate.
Table 2: Debugging levels
The most important debugging modules are:
Debug access control lists. .
Debug configuration parser and/or lexical analyzer. The following levels are supported:
Minimal information about configuration statements.
Trace lexical structure of the configuration files.
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 based servers, such as imap4d and pop3d. This
module supports ‘trace0’ and ‘error’ levels. See section Server Settings, for more information about servers.
UDP based servers, such as comsatd. This module supports
‘trace0’ and ‘error’ levels. See section Server Settings, for
more information about servers.
Operations over mailboxes. This module supports the following levels: ‘error’, ‘trace0’, ‘trace1’, and ‘proto’. The latter is used by remote mailbox support libraries.
Debug Sieve parser and run-time evaluator. Currently supported levels are ‘error’, ‘trace1’ and ‘trace7’.
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 debugging levels table, so that, e.g. ‘<trace2’ means levels ‘error’, ‘trace0’, ‘trace1’ and ‘trace2’.
Both prefixes can be used together, in this order: ‘!<’. This means all levels except this one and ones listed before it in the table.
A comma before equal sign, as in ‘mailbox:=<trace7’ means set this debugging levels in all modules, invoked by this one.
The level in the level specification can also be a comma-separated list of valid levels, e.g.:
mailbox=<trace2,!<trace4 |
which means “levels trace3 and trace4”.
The following example illustrates two equivalent ways of setting debugging level in a configuration file:
level ("mailbox=!proto", "acl=<trace7");
level "mailbox=!proto;acl=<trace7";
|
The ‘--debug-level’ command line option overrides the settings
of the level configuration statement.
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.
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;
}
|
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.
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.
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:
Specifies the mailbox type. It must be one of mailbox types, supported by Mailutils. . By default, ‘local’ is assumed. .
The path pattern.
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:
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:
Indexed directory structures are configured using the following arguments:
Specifies type of indexing. Valid values are ‘index’, for direct indexed structure, ‘rev-index’ for reverse indexing, and ‘hash’ for hashed structure.
Specifies indexing level.
Specifies indexing key. The only meaningful value, as of Mailutils version 2.2 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:
FOLDER its value is used.
MAIL is set, its value
is used.
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.
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.
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/’.
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;
}
|
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.
Set locking flags. Argument is a string consisting of one or more of the following letters:
Use an external program to manage locks. The program is given by
external-locker statement (see below).
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.
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.
Store the PID of the locking process in a lock file.
Number of locking attempts. The ‘P’ flag must be set for this to take effect.
Time interval, in seconds, between the two successive locking attempts. The ‘P’ flag must be set for this to take effect.
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.
Set command line of an external locker program. The ‘E’ flag must be set for this to take effect.
mailer {
url url;
}
|
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:
Set the mailer URL.
GNU Mailutils supports two types of mailer URLs, described in the table below. As usual, square brackets indicate optional parts:
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.
Use sendmail-compatible program progname. Sendmail-compatible means that the program must support following command line options:
Do not treat ‘.’ as message terminator.
Use addr as the sender address.
Get recipient addresses from the message.
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.
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:
Expands to the sender email address.
Expands to the recipient email addresses.
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;
}
|
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.2 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:
Allow connections from IP addresses matching this cidr block.
Deny connections from IP addresses matching this cidr block.
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:
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:
For inet IPv4 connections. The variables ip and port are replaced by the remote IP address and port number, correspondingly.
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:
aclnoOrdinal number of the control in the ACL. Numbers begin from ‘0’.
familyConnection family. Mailutils version 2.2 supports two families: ‘AF_INET’ and ‘AF_UNIX’.
addressRemote 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.
portRemote 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.
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.
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;
}
|
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 (hosts_access(5))ACCESS CONTROL FILES section `ACCESS CONTROL FILES' in hosts_access(5) man page, for details.
Enable access control using TCP wrappers. It is on by default.
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.
Use file as allow table. By default, ‘/etc/hosts.allow’ is used.
Use file as negative table. By default, ‘/etc/hosts.deny’ is used.
Log allowed accesses using syslog priority prio.
Log denied accesses using syslog priority prio.
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.
# 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; |
These statements configure general server-related issues.
Set operation mode of the server. Two operation modes are supported:
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.
Operate as a subprocess of UNIX internet super-server program,
inetd. See (inetd(8))Internet super-server section `Internet super-server' in inetd(8) man page, 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.
[daemon mode only]
Do not disconnect from the controlling terminal and remain in the
foreground.
[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.
After startup, store the PID of the main server process in file. When the process terminates, the file is removed. As of version 2.2, GNU Mailutils servers make no further use of this file. It is intended for use by automated startup scripts and controlling programs ().
[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 (services(5))Internet network services list section `Internet network services list' in services(5) man page).
Set maximum idle time out in seconds. If a client does not send any requests during time seconds, the child process terminates.
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 section ACL Statement. */ };
}
|
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 (services(5))Internet network services list section `Internet network services list' in services(5) man page). If port is omitted,
Mailutils uses the port set by port statement (see section 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.
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.
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.
Set idle timeout for this server. This overrides global timeout settings (see section timeout).
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.
auth {
# Set a list of modules for authentication.
authentication module-list;
# Set a list of modules for authorization.
authorization module-list;
}
|
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.
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:
User credentials are retrieved from the system user database (‘/etc/password’).
User credentials are retrieved from a SQL database.
A separate configuration statement, sql, is used to configure
it (see section SQL Statement).
User credentials are retrieved from a “virtual domain” user
database. Virtual domains are configured using virtdomain
statement (see section Virtdomain Statement).
User credentials are retrieved using RADIUS. See section Radius Statement, for a detailed description on how to configure it.
User credentials are retrieved from an LDAP database. See section 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) |
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:
The generic authentication type. User password is hashed and compared against the hash value returned in authorization stage.
The hashed value of the user password is retrieved from ‘/etc/shadow’ file on systems that support it.
The hashed value of the user password is retrieved from a
SQL database using query supplied by getpass
statement (see section getpass).
The user is authenticated via pluggable authentication module
(PAM). The PAM service name to be used is
configured in pam statement (see section PAM Statement).
The user is authenticated on a remote RADIUS server. See section Radius Statement.
The user is authenticated using LDAP. See section LDAP Statement.
Unless overridden by authentication statement,
the list of authentication modules is:
(generic, system, pam, sql) |
pam {
# Set PAM service name.
service text;
}
|
The pam statement configures PAM authentication. It
contains a single sub-statement:
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 section Auth Statement).
virtdomain {
# Name of the virtdomain password directory.
passwd-dir dir;
}
|
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.
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 (passwd(5))password file section `password file' in passwd(5) man page), with encrypted passwords stored in it (as of GNU Mailutils version 2.2, 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.
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;
}
|
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: (radius)client.conf section `Client Configuration' in GNU Radius Reference Manual). 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:
Set full path name to the GNU Radius configuration directory.
It authorization is used, the Radius dictionary file must declare the the following attributes:
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: (radius)Overview section `Overview' in GNU Radius Reference Manual) 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: (radius)dictionary file section `dictionary file' in GNU Radius Reference Manual). 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 ():
The actual user name (for auth and getpwnam), or user ID
(for getpwuid). For example:
User-Name = ${user}
|
User password. For examples:
User-Password = ${passwd}
|
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: (radius)Authentication Requests section `Authentication Requests' in GNU Radius Reference Manual). Any returned attribute-value
pairs are ignored.
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 section 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.
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).
(The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised.)
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;
}
|
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.
Configures type of DBMS interface. Allowed values for type are:
Interface with a MySQL server (http://www.mysql.org).
Use ODBC interface. See http://www.unixodbc.org, for a detailed description of ODBC configuration.
Interface with a PostgreSQL server (http://www.postgres.org).
The database and database access credentials are configured using the following statements:
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.
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.
Name of the database.
SQL user name.
Password to access the database.
This node is to be written.
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;
}
|
This node is to be written.
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;
}
|
This node is to be written.
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;
}
|
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 section Debug Statement. |
| tls | See section TLS Statement. |
| mailbox | See section Mailbox Statement. |
| locking | See section 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:
Enable debugging output.
Display the header named by string instead of From
Subject pair.
Include the contents of To header to the output. The output field
order is then: To From Subject.
Prefix each line with corresponding message number.
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.
Print a message only if there are unread messages in the mailbox.
Print a summary line.
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.
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:
Prints only a count of messages in the mailbox and exit.
Prints additional debugging output.
Prints only mail whose ‘From:’ headers contain the supplied string.
Examine mailbox from the given url.
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 the user system mailbox. The ‘--file’ (‘-f’)
command line option allows to specify another mailbox name. 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 section Personal and System-wide Configuration Files,
for a detailed description of its format.
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:
Return true if the mailbox contains some messages. Return false otherwise. This is useful for writing shell scripts.
Execute command before opening the mailbox. Any number of ‘--exec’ options can be given. The commands will be executed after sourcing configuration files (see section Personal and System-wide Configuration Files), but before opening the mailbox.
Operate on the mailbox given by the first non-optional command line argument. If there is no such argument, read messages from the user's ‘mbox’ file. See section Reading Mail, for more details about using this option.
Record outgoing messages in a file named after the first recipient. The name is the login-name portion of the address found first on the ‘To:’ line in the mail header. This option sets the ‘byname’ variable, which see (see byname).
Print header summary to stdout and exit.
Ignore interrupts.
Set path to the mailspool directory
Do not read the system-wide mailrc file. See section Personal and System-wide Configuration Files.
Do not display initial header summary.
Print all mail to standard output. It is equivalent to issuing following commands after starting ‘mail -N’:
print * quit |
Cause interrupts to terminate program.
Send a message with a Subject of subj. Valid only in sending mode.
Switch to sending mode.
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).
Display a help message.
Display a short usage summary.
Print program version and exit.
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
This specifier addresses the message with the given ordinal number in the mailbox.
Message range is specified as two message numbers separated by a dash. It selects all messages with the number lying within that range.
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:
Selects all deleted messages.
Selects all recent messages, i.e. the messages that have not been neither read not seen so far.
Selects all messages that have been seen.
Selects all messages that have been read.
Selects all messages that have not been read.
Selects all tagged messages.
Selects all untagged messages.
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:’.
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:
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 section How to Alter the Behavior of mail).
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.
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.
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.
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.
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.
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 |
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.
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.
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.
The ‘~i’ escape enters the value of the named mail variable into the body of the message being composed.
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.
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.
To read messages from a given mailbox, use one of the following ways of
invoking mail:
mailTo read messages from your system mailbox.
mail -fmail --fileTo read messages from your mailbox (‘$HOME/mbox’). If the ‘--user’ option (see below) is also given, read messages from that user's ‘mbox’.
mail -f path_to_mailboxmail --file path_to_mailboxTo read messages from the specified mailbox.
mail -u usermail --user=userTo 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.
Notice that path_to_mailbox is not an argument to ‘--file’ (‘-f’) option, but rather the first non-optional argument on the command line. Therefore, the following three invocations are equivalent:
$ mail -fin mymbox $ mail -f mymbox -in $ mail --file -in mymbox $ mail --file -i mymbox -n |
Additionally, for conformance to the GNU standards, the following form is also accepted:
$ mail --file=mymbox -i -n |
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 Personal and System-wide 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.
Following commands quit the program:
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.
Program exits to the Shell without modifying the mailbox it operates upon.
Typing EOF (‘C-D’) alone is equivalent to ‘quit’.
Following commands can be used during the session to request online help:
Display detailed command synopsis. If no command is given, help for all available commands is displayed.
Print a list of available commands.
Display program version.
Display program warranty statement.
Move to the first undeleted message.
Move to the last undeleted message.
Move to the next message.
Move to the previous message.
Change to the specified directory. If dir is omitted, $HOME is
assumed.
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.:
|
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.
Add header-field-list to the ignored list. When used without arguments, this command prints the contents of ignored list.
Add header-field-list to the retained list. When used without arguments, this command prints the contents of retained list.
Displays the current message number.
Lists the current pageful of headers.
Lists the contents of ‘From’ headers for a given set of messages.
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.
Lists the message number and message size in bytes for each message in msglist.
Displays the value of folder variable.
Displays current mailbox summary. E.g.:
|
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.
Like print but also prints out ignored header fields.
Print a multipart message. The decode command decodes and prints
out specified message parts. E.g.
|
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 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.
Prints the MIME structure of each message from msglist. Empty msglist means current message.
Example:
|
Tag messages. The tagged messages can be referred to in message list using ‘:t’ notation.
Clear tags from specified messages. To untag all messages tagged so far type
& untag :t |
Marks each message to be held in user's system mailbox. This command
does not override the effect of delete command.
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.
Clear delete mark from the specified messages.
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.
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.
Like save, but the file to append messages to is named after the
sender of the first message in msglist. For example:
|
i.e., 22 lines (603 characters) have been appended to the file “smith”. If the file does not exist, it is created.
Similar to save, except that only message body (without the
header) is saved.
Similar to Save, except that only message body (without the
header) is saved.
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.
Similar to save, except that saved messages are not marked for
deletion.
Similar to Save, except that saved messages are not marked for
deletion.
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.
Edits each message in msglist with the editor, specified in
EDITOR environment variable.
Edits each message in msglist with the editor, specified in
VISUAL environment variable.
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.
Takes a list of names defined by alias commands and discards the remembered groups of users. The alias names no longer have any significance.
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.
Switches to compose mode. After composing the message, sends messages to the specified addresses.
For each message in msglist, switches to compose mode and sends the composed message to the sender and all recipients of the message.
Like reply, except that the composed message is sent only to
originators of the specified messages.
Notice, that setting mail variable flipr (see section How to Alter the Behavior of mail) 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.
Switches to compose mode. After composing, sends the message to the originators and recipients of all messages in 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:
|
Now, you issue the following commands:
|
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:
|
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:
|
Command nosender is used to remove items from the sender
field list:
|
When used without arguments, this command clears the list:
|
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.
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 !.
The ‘#’ character introduces an end-of-line comment. All characters until and including the end of line are ignored.
The ‘echo’ (‘ec’) command prints its arguments to stdout.
The command ‘source filename’ reads commands from the named file. Its minimal abbreviation is ‘so’.
The mail variables are set using ‘set’ (‘se’) command. The command takes a list of assignments. The syntax of an assignment is
Assign a string value to the variable. If string contains whitespace characters it must be enclosed in a pair of double-quote characters (‘"’)
Assign a numeric value to the variable.
Assign boolean True value.
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 |
When used without arguments, both set or unset
list all currently defined variables. The form of this listing is
controlled by variable-pretty-print (varpp) variable. If
it is set, a description precedes each variable, e.g.:
# prompt user for subject before composing the message ask # prompt user for cc before composing the message askcc # output character set for decoded header fields charset="auto" # number of columns on terminal screen columns=80 |
If variable-pretty-print is not set, only the settings are
shown, e.g.:
ask askcc charset="auto" columns=80 |
A special command is provided to list all internal mail
variables:
variable [names...] |
If used without arguments, it prints all known internal variables. If arguments are given, it displays only those internal variables that are listed in command line. For each variable, this command prints its name, data type, current value and a short description. For example:
& variable ask datefield ask, asksub Type: boolean Current value: yes prompt user for subject before composing the message datefield Type: boolean Current value: [not set] get date from the `Date:' header, instead of the envelope |
Shell environment may be modified using ‘setenv’ (‘sete’) command. The command takes a list of assignments. The syntax of an assignment is:
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.
Delete the variable name from the environment (“unset” it).
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:
True if mail is operating in mail sending mode.
True if mail is operating in mail reading mode.
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 |
mail Following variables control the behavior of GNU mail:
appendType: Boolean, Read-Only
Default: True
Messages saved in mbox are appended to the end rather than prepended.
This is the default and cannot be changed. This variable exists only
for compatibility with other mailx implementations.
appenddeadletterType: 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.
askbccType: Boolean.
Default: False.
When set to True the user will be prompted to enter Bcc
field before composing the message.
askccWhen set to True the user will be prompted to enter Cc
field before composing the message.
asksubType: 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.
autoincAutomatically incorporate newly arrived messages.
autoprintType: Boolean.
Default: False.
Causes the delete command to behave like dp - thus, after deleting a message, the next one will be typed automatically.
bangType: Boolean.
Default: False.
When set, every occurrence of ! in arguments to !
command is replaced with the last executed command.
bynameRecord outgoing messages in a file named after the first recipient. The name is the login-name portion of the address found first on the ‘To:’ line in the mail header. This variable overrides the ‘record’ variable.
It is set by the ‘--byname’ (‘-F’) command line option.
datefieldType: 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.
See fromfield.
charsetThe 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.
cmdContains default shell command for pipe.
columnsType: 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.
crtType: 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.
debugType: String to boolean
Default: Not set
Sets mailutils debug level. If set to string, the value must be a valid Mailutils debugging specification. See section Debug Statement, for a description.
If unset (i.e. set nodebug), clears and disables all debugging
information. If set to ‘true’ (i.e. set debug), sets
maximum debugging (‘<trace7’) on mailbox and its underlying
objects.
decode-fallbackType: String.
Default: ‘none’.
This variable controls the way to represent characters that cannot be rendered using current character set. It can have three values:
Such characters are not printed at all. The conversion process stops at the first character that cannot be rendered.
The characters are displayed ‘as is’. Notice, that depending on your setup, this may screw-up your terminal settings.
Unprintable characters are represented by their octal codes. Printable ones are printed ‘as is’.
debugThis variable is not used. It exists for compatibility with other
mailx implementations and for future use.
dotType: Boolean.
Default: False.
If True, causes mail to interpret a period alone on a line as the
terminator of a message you are sending.
emptystartType: 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.
editheadersType: 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.
escapeIf defined, the first character of this option gives the character to denoting escapes.
fliprIf set, the variable flipr swaps the meanings of reply
and Reply commands (see Replying).
folderThe name of the directory to use for storing folders of messages. If
unset, $HOME is assumed.
fromfieldType: Boolean.
Default: True.
By default the sender address is taken from the ‘From’ header.
Unsetting this variable tells mail to obtain it from the
SMTP envelope, instead.
See datefield.
headerType: Boolean.
Default: True, unless started with ‘--nosum’ (‘-N’) option.
Whether to run headers command automatically after entering
interactive mode.
headlineType: String
Default: ‘%>%a%4m %18f %16d %3l/%-5o %s’
A format string to use for the header summary. The ‘%’ character introduces a format specifier. Valid format specifiers are:
| Letter | Meaning |
|---|---|
| %a | Message attributes. |
| %d | The date when the message was received. |
| %f | The address of the message sender. |
| %l | The number of lines of the message. |
| %m | Message number. |
| %o | The number of octets (bytes) in the message. |
| %s | Message subject (if any). |
| %S | Message subject (if any) in double quotes. |
| %> | A ‘>’ for the current message, otherwise a space. |
| %< | A ‘<’ for the current message, otherwise a space. |
| %% | A `%' character. |
Some additional symbols are allowed between ‘%’ and the specifier letter. The ‘-’ character immediately following ‘%’ indicates that this field should be left aligned. Similarly, the ‘+’ character indicates right alignment. Default alignment depends on the type of the specifier: the specifiers that produce numeric values (‘%l’, ‘%m’, and ‘%o’) are aligned to the right, whereas the ones producing string values are aligned to the left.
A number following ‘%’ or the alignment flag, indicates the field width. Consider, for example, the following specifiers:
Print current message number. Take as much screen columns as necessary to output it.
Print current message number. Occupy 4 screen columns, truncate the output if it does not fit that width. Align the output to the right.
Same as above, but align to the left.
holdType: 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.
ignoreType: 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.
ignoreeofType: Boolean.
Default: False.
Controls whether typing EOF character terminates the letter being composed.
indentprefixType: String.
Default: "\t" (a tab character).
String used by the ~m tilde escape for indenting quoted messages.
inplacealiasesType: Boolean
Default: False
If set, mail will expand aliases in the address header field
before entering send mode (see section Composing Mail). By default, the
address header fields are left intact while composing, the alias
expansion takes place immediately before sending message.
keepType: Boolean, Read-Only
Default: True
Truncate the user's system mailbox when it is empty, instead of
removing it. This is the default and cannot be changed. This variable
exists only for compatibility with other mailx implementations.
keepsaveType: 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.
mailxType: Boolean.
Default: False.
When set, enables mailx compatibility mode. This mode has the following effects:
mail will ask
for Cc and Bcc addresses after composing the body.
The default behavior is to ask for these values before composing
the body.
mail
will exit with zero status. By default it exits with zero status only
if the message was sent successfully.
metamailType: 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" |
mimenoaskBy 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’.
metooType: 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.
modeType: String, Read-Only
Default: The name of current operation mode.
This variable keeps the name of the current operation mode. Its possible values are:
The program is started with the ‘--headers’ (‘-H’) command
line option (see section Invoking mail).
The program is started with the ‘--exist’ (‘-e’) command
line option (see section Invoking mail).
The program is started with the ‘--print’ (‘-p’) command
line option (see section Invoking mail).
The progran operates in read mode. This is the default.
The program operates in send mode. This means it was given one or more recipient addresses in the command line.
nullbodyControls 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' |
showenvelopeType: Boolean
Default: Unset
If this variable is set, the print command will include the
STMP envelope in its output.
nullbodymsgType: 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.
onehopThis variable is not used. It exists for compatibility with other
mailx implementations and for future use.
outfolderContains the directory in which files created by save,
write, etc. commands will be stored. When unset, current
directory is assumed.
pageType: Boolean.
Default: False.
If set to True, the pipe command will emit a linefeed
character after printing each message.
promptContains the command prompt sequence.
quietThis variable is not used. It exists for compatibility with other
mailx implementations and for future use.
quitType: Boolean.
Default: False, unless started with ‘--quit’ (‘-q’) option.
When set, causes keyboard interrupts to terminate the program.
rcType: 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 Personal and System-wide Configuration Files.
readonlyWhen set, mailboxes are opened in readonly mode. In this mode, any
mail commands that alter the contents of the mailbox are
disabled. These commands include, but are not limited to:
delete, save and mbox.
recordWhen set, any outgoing message will be saved to the named file.
recursivealiasesType: Boolean
Default: True
When set, mail will expand aliases recursively.
regexSetting this to True enables use of regular expressions in
‘/.../’ message specifications.
replyprefixSets the prefix that will be used when constructing the subject line of a reply message.
replyregexType: 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).
saveWhen set, the aborted messages will be stored in the user's
‘dead.file’. See also appenddeadletter.
screenType: 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.
sendmailType: String.
Default: sendmail:/usr/lib/sendmail
Contains URL of the mail transport agent.
sendwaitThis variable is not used. It exists for compatibility with other
mailx implementations and for future use.
showtoIf the message was sent by the user, print its recipient address in the header summary.
SignContains the filename holding users signature. The contents of this
file is appended to the end of a message being composed by ~A
escape.
signContains 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.
showtoIf this variable is set, mail will show To: addresses
instead of From: for all messages that come from the user that
invoked the program.
subjectContains default subject line. This will be used when asksub is
off.
toplinesNumber of lines to be displayed by top and Top commands.
variable-strictvarstrictType: Boolean.
Default: False.
Setting this variable enables strict control over variable
settings. In this mode, mail refuses to set read-only
variables. Also, if the user is trying to set an unknown variable,
mail prints a warning.
variable-pretty-printvarppType: Boolean.
Default: False.
If this variable is set, the listing ouput by set contains short
descriptions before each variable. See Setting and Unsetting the Variables.
verboseType: Boolean.
Default: False.
When set, the actual delivery of messages is displayed on the user's terminal.
xmailerControls whether the header ‘X-Mailer’ should be added to outgoing messages. The default value of this header is
X-Mailer: mail (GNU Mailutils 2.2) |
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’.
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 section Debug Statement. |
| tls | See section TLS Statement. |
| mailbox | See section Mailbox Statement. |
| locking | See section Locking Statement. |
The program accepts following command line options:
Be quiet. Display only number of messages per mailbox, without leading text.
Output help message and exit.
Output short usage summary and exit.
Output program version and exit.
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 (emacs)Rmail section `Rmail' in Reading Mail with Rmail, for detailed
description of Rmail interface.
Mailutils version of movemail is fully
backward-compatible with its Emacs predecessor, so it should run
flawlessly with older versions of Emacs. Emacs versions
starting from 22.1 contain improved Rmail interface and
are able to take advantage of all new features mailutils
movemail provides.
Following configuration file statements affect the behavior of
movemail:
If bool is ‘true’, do not remove messages from the source mailbox.
If bool is ‘true’, reverse message sorting order.
If bool is ‘true’, output information used by Emacs rmail interface.
Continue moving messages after errors. By default,
mailfromd exits immediately if it cannot copy a message.
Set program identifier, i.e. a string which will prefix all diagnostic messages issued by the program. By default, program name is used.
The fmt is a format string that may contain references to the following macro variables ():
prognameThe program name.
sourceURL of the source mailbox.
source:userUser part of the source mailbox URL.
source:hostHost part of the source mailbox URL.
source:pathPath part of the source mailbox URL.
destURL of the destination mailbox
dest:userUser part of the destination mailbox URL.
dest:hostHost part of the destination mailbox URL.
dest:pathPath part of the destination mailbox URL.
Setting program-id may be necessary if several movemail
instances are run simultaneously (e.g. invoked from a script) to
discern between the instances. For example:
program-id "${progname}: ${source} => ${dest}"
|
Avoid copying the message if a message with the same UIDL already exists in the destination mailbox.
Set verbosity level.
Define list of methods for setting ownership of the destination mailbox. The method-list argument can contain the following elements:
Copy owner UID and GID from the source mailbox. This method works only with local mailboxes, i.e.: ‘mbox’ (UNIX mailbox), ‘maildir’ and ‘mh’.
Get owner name from the source mailbox URL and obtain UID and GID for this user using mailutils authorization methods.
Set supplied uid and gid. If gid is not supplied, it is read from the ‘/etc/passwd’ record for this UID.
Make destination mailbox owned by user.
| Statement | Reference |
|---|---|
| debug | See section Debug Statement. |
| tls | See section TLS Statement. |
| mailbox | See section Mailbox Statement. |
| locking | See section Locking Statement. |
| pam | See section PAM Statement. |
| sql | See section SQL Statement. |
| virtdomain | See section Virtdomain Statement. |
| radius | See section Radius Statement. |
| ldap | See section LDAP Statement. |
| auth | See section Auth Statement. |
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.
(The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised.)
movemail [option...] inbox destfile [remote-password] |
The first argument, inbox, is the url (see section 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:
Output information used by Emacs rmail interface
Continue moving messages after an error occurs.
Preserve the source mailbox
Set program identifier for diagnostic purposes. See program-id, for a detailed discussion of this feature.
Reverse the sorting order
Enable (default) or disable TLS support
Use UIDLs to avoid downloading the same message twice.
Define list of methods for setting ownership of the destination
mailbox. See mailbox-ownership-methods, for a description of
method-list. This option is useful only when running
movemail as root.
Increase verbosity level.
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:
readmsg 1 3 0 |
extracts three messages from the folder: the first, the third, and the last.
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.
readmsg. If a pattern is use for selection show all messages that match pattern by default only the first one is presented.
Display mailbox debugging information.
Specified the default mailbox.
Show the entire header and ignore the weedlist.
Do not print the message header.
Put form-feed (Control-L) between messages instead of newline.
A whitespace or coma separated list of header names to show per message. Default is ‘--weedlist="From Subject Date To CC Apparently-"’.
readmsg. Following configuration statements affect the behavior of
readmsg:
If bool is ‘true’, display entire headers.
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 section –weedlist).
If bool is ‘true’, exclude all headers.
If bool is ‘true’, output formfeed character between messages.
Set the URL of the mailbox folder to read.
If bool is ‘true’, print all messages matching pattern, not only the first.
| Statement | Reference |
|---|---|
| debug | See section Debug Statement. |
| tls | See section TLS Statement. |
| mailbox | See section Mailbox Statement. |
| locking | See section Locking Statement. |
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.
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 section Sieve Language,
for a description of the Sieve language. See section GNU Extensions, for a
discussion of differences between the GNU implementation of Sieve and
its standard.
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:
Compile script and exit.
Clear Sieve library path. See also clear-library-path.
Clear Sieve include path. See also clear-include-path.
Specify debug flags. The flags argument is a sequence of one or more of the following letters:
| ‘g’ | Enable main parser traces |
| ‘T’ | Enable mailutils traces |
| ‘P’ | Trace network protocols |
| ‘t’ | Enable sieve trace |
| ‘i’ | Trace the program instructions |
Compile the script, dump disassembled code on standard output and exit.
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.
Append directory dir to the list of directories searched for include files. See also include-path.
Mailbox to sieve (defaults to user's system mailbox). See also mbox-url.
Keep on going if execution fails on a message. See also keep-going.
Append directory dir to the list of directories searched for library files. See also library-path.
Dry run: do not execute any actions, just print what would be done.
Ticket file for mailbox authentication. See also ticket.
Log all actions executed. See also verbose.
The behavior of sieve is affected by the following
configuration statements:
| Statement | Reference |
|---|---|
| debug | See section Debug Statement. |
| tls | See section TLS Statement. |
| mailbox | See section Mailbox Statement. |
| locking | See section Locking Statement. |
| logging | See section Logging Statement. |
| mailer | See section Mailer Statement. |
The following statements configure sieve-specific features:
This block statement configures search paths sieve uses to
locate its loadable modules. See section 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.
Used within the sieve block statement.
If bool is ‘true’, clear library search path.
Used within the sieve block statement.
If bool is ‘true’, clear include search 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.
Used within the sieve block statement.
Add directories to the include search path. Argument is a string containing a colon-separated list of directories.
If bool is ‘true’, do not abort if execution of a Sieve script fails on a particular message.
Sets URL of the mailbox to be processed.
Sets the name of the ticket file for user authentication.
Sets Sieve debug flags. See Logging and Debugging, for a detailed description.
If bool is ‘true’, log all executed actions.
If bool is ‘true’, print source locations along with action
logs. This statement takes effect only if verbose true is also
set.
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.
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:
This flag enables sieve tracing. It means that every test will be logged when executed.
This flag enables debugging of underlying mailutils library.
Trace network protocols: produces log of network transactions executed while running the script.
Enable main parser traces. This is useful for debugging the sieve grammar.
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.
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:
LTDL_LIBRARY_PATH.
library-path statement (see library-path) in Sieve configuration file.
#searchpath Sieve directive (see #searchpath).
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:
sieve executes its
initialization function (see below) and again looks up the name
in the symbol table. If found, search terminates successfully.
sieve then displays
the following diagnostic message:
source for the required action NAME is not available |
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 (guile)Top section `Overview' in The Guile Reference Manual.
Set input file name.
Set output file name
Set sieve library directory name
Set debugging level
The Scheme programs produced by sieve.scm can be used with
guimb or maidag.
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 section Debug Statement. |
| mailbox | See section Mailbox Statement. |
| locking | See section Locking Statement. |
The Scheme program or expression to be executed is passed to
guimb via the following options:
Load Scheme source code from file.
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:
Execute scheme expression.
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.
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 defmboxThe 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.
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
|
This is a short summary of the command line options available to
guimb.
Start with debugging evaluator and backtraces.
Execute given Scheme expression.
Set path to the mailspool directory
Read Scheme program from progfile.
Append arg to the command line passed to Scheme program.
Pass all command line options enclosed between ‘-{’ and ‘-}’ to Scheme program.
Set default mailbox name.
Act as local MDA for user name.
Display help message.
Display program version.
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, Scheme or Python 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.
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') |
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 |
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 section 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"; |
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:
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 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.
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; |
Configuration statement quota-query allows to specify a special
query to retrieve the quota from the database. Currently (as of mailutils
version 2.2) it is assumed that this table can be accessed
using the credentials set in ‘sql’ configuration statement
(see section 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";
|
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.2, such mail filters may be written in
the following languages:
Mail filters to use are specified using ‘script’ configuration statement. The following meta-symbols can be used in its argument:
Expands to the recipient home directory.
Expands to the recipient user name.
By default, a filename extension decide which scripting language will be used. User can alter the choice using ‘language’ configuration statement. For example:
language "python" script "~/.maidag-py-filter" |
The file name of the Sieve filter to use is specified using ‘script’ configuration statement. For example, the following configuration statement:
script "~/.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.
The file name of the Scheme mail filter is specified using ‘script’ configuration statement. For example, the following configuration statement:
script "~/.maidag.scm" |
instructs `maidag' to use file `.maidag.scm' in the recipient home directory as a Scheme filter.
The file name of the Python mail filter is specified using ‘script’ configuration statement. For example, the following configuration statement:
script "~/.maidag.py" |
instructs `maidag' to use file `.maidag.py' in the recipient home directory as a Python filter.
A simple example of a mail filter written in Python:
from mailutils import *
import maidag
import re
msg = message.Message (maidag.message)
hdr = msg.header
try:
if 'List-Post' in hdr and 'Received' in hdr \
and hdr['Received'].find ('fencepost.gnu.org') != -1:
# check envelope's sender address
m = re.search (r'([\w\-]+)-bounces\+([\w]+)=.*',
msg.envelope.get_sender ())
if m:
lbox = m.group (1)
user = m.group (2)
# open destination mailbox and append message
dst = mailbox.MailboxDefault ('~/Mail/%s' % lbox)
dst.open ('ac')
dst.append_message (msg)
dst.close ()
# set deleted flag so maidag will not deliver msg elsewhere
msg.attribute.set_deleted ()
except Exception:
pass
|
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:
The file must not be group writable.
The file must not be world writable.
The file cannot be a symlink in a writable directory.
The file cannot reside in a group writable directory.
The file cannot reside in a world writable directory.
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); |
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 |
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:
Here, program is the absolute pathname of the program binary, and args are its arguments, separated by ‘&’ signs.
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 | +---------------------+---------------------------------------+ |
The behavior of maidag is affected by the following configuration
statements:
| Statement | Reference |
|---|---|
| debug | See section Debug Statement. |
| mailbox | See section Mailbox Statement. |
| locking | See section Locking Statement. |
| pam | See section PAM Statement. |
| sql | See section SQL Statement. |
| virtdomain | See section Virtdomain Statement. |
| radius | See section Radius Statement. |
| ldap | See section LDAP Statement. |
| auth | See section Auth Statement. |
| mailer | See section Mailer Statement. |
| server | See section Server Settings. Used only in LMTP mode. |
| acl | See section ACL Statement. |
| tcp-wrappers | See section Tcp-wrappers Statement. |
In case of multiple delivery, exit with code 0 if at least one delivery has succeeded.
Indicate temporary failure if the recipient is over his mail quota. By default, permanent failure is returned. See section Mailbox Quotas.
Set the name of DBM quota database file. See section Keeping Quotas in DBM File.
Set file name or name pattern of the Sieve filter file. See section Sieve Maidag Filters.
When logging Sieve actions, identify messages by the value of this header.
File name or name pattern for Guile filter file. See section Scheme Maidag Filters.
Set additional debugging flags. Valid flags are:
Print guimb stack traces.
Enable sieve trace (MU_SIEVE_DEBUG_TRACE).
Enable sieve instructions trace
(MU_SIEVE_DEBUG_INSTR).
Log executed Sieve actions.
Log to stderr instead of syslog.
Process forward file file. See section Forwarding.
Configure safety checks for the forward file. See section forward-file-checks.
Run in LMTP mode.
In LMTP mode, retain supplementary groups from list.
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’.
Reuse existing address (LMTP mode). Default is ‘yes’.
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(5))mime.types section `mime.types' in mime.types man page. 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 |
The following table summarizes options specific for mimeview:
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/*'’).
Enables debugging output. Flags is a sequence of characters specifying the desired debugging level. Following characters are meaningful in flags:
Enables debugging of ‘mime.types’ parser
Enables debugging of ‘mime.types’ lexical analyzer (warning: produces very copious output)
Prints basic information about actions to be executed and reports about exit status of executed commands.
Additionally displays each file name along with its MIME type
Additionally traces the process of looking up the matching entry
in mailcap files.
The same as 3, currently.
If flags are not given, the default ‘9’ is assumed.
Run metamail to display files, instead of using the internal
mechanisms. If file is specified, it is taken as
metamail command line.
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.
Do not do anything, just print what would be done. Implies ‘--debug=1’, unless the debugging level is set up explicitly.
Use file as ‘mime.types’ file. If file is a directory, use ‘file/mime.types’
The following configuration statements affect the behavior of
mimeview:
| Statement | Reference |
|---|---|
| debug | See section Debug Statement. |
Set mimeview debug level. See section –debug, for a description of debug levels.
Read file instead of the default ‘mime.types’.
Use program to display files.
The pop3d daemon implements the Post Office Protocol
Version 3 server.
pop3d has two operation modes:
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.
The server runs as daemon, forking a child for each new connection.
The server operation mode is configured using mode statement
(see section mode).
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.2, 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.
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:
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.
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.
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 mboxSet the URL of the bulletin source mailbox.
bulletin-db fileSet 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; |
The following configuration file statements affect the behavior of
pop3d.
| Statement | Reference |
|---|---|
| debug | See section Debug Statement. |
| tls | See section TLS Statement. |
| mailbox | See section Mailbox Statement. |
| locking | See section Locking Statement. |
| logging | See section Logging Statement. |
| pam | See section PAM Statement. |
| sql | See section SQL Statement. |
| virtdomain | See section Virtdomain Statement. |
| radius | See section Radius Statement. |
| ldap | See section LDAP Statement. |
| auth | See section Auth Statement. |
| server | See section Server Settings. |
| acl | See section ACL Statement. |
| tcp-wrappers | See section Tcp-wrappers Statement. |
On startup, clear deletion marks from all the messages.
Automatically expire read messages after n days. See section Auto-expire, for a detailed description.
Delete expired messages upon closing the mailbox. See section Auto-expire, for a detailed description.
Always require STLS command before entering authentication
phase.
Set the minimal allowed delay between two successive logins. See section Login delay, for more information.
Set the name of login statistics file for the login-delay
facility. See section Login delay, for more information.
Get bulletins from the specified mailbox. See section Bulletins, for a detailed description.
Set bulletin database file name. See section Bulletins, for a detailed description.
The following table summarizes all pop3d command line options.
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.
Run in inetd mode.
Display short help message and exit.
Remain in foreground.
Enable TLS. If optional argument is supplied and is ‘false’, then disable it.
Enable debugging of authentication functions.
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.
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:
A namespace that is within the personal scope of the authenticated user on a particular connection. The user has all permissions on this 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.
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:
The home directory of the user, if exists.
Empty
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 listSet shared namespace.
other-namespace listSet 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 modeSet file mode for mailboxes created in shared namespace.
other-mailbox-mode modeSet 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; |
imap4d. The behavior of imap4d is altered by the following
configuration statements:
| Statement | Reference |
|---|---|
| debug | See section Debug Statement. |
| tls | See section TLS Statement. |
| mailbox | See section Mailbox Statement. |
| locking | See section Locking Statement. |
| logging | See section Logging Statement. |
| pam | See section PAM Statement. |
| sql | See section SQL Statement. |
| virtdomain | See section Virtdomain Statement. |
| radius | See section Radius Statement. |
| ldap | See section LDAP Statement. |
| auth | See section Auth Statement. |
| server | See section Server Settings. |
| acl | See section ACL Statement. |
| tcp-wrappers | See section Tcp-wrappers Statement. |
Set shared namespace. List is a list of strings. See section Namespace, for a detailed description.
Set other users' namespace. List is a list of strings. See section Namespace, for a detailed description.
Set file mode for mailboxes created within shared namespace. See section Namespace, for a detailed description.
Set file mode for mailboxes created within other users' namespace. See section Namespace, for a detailed description.
Disable LOGIN command, if bool is ‘true’.
Create nonexistent user home directories. See also home-dir-mode, below.
Set file mode for created user home directories. Mode is specified in octal.
The default value for mode is ‘700’ (‘drwx------’ in
ls terms).
Require successful STARTTLS command before entering
authentication phase.
Configure PREAUTH mode. Valid arguments are:
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.
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’.
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.
If bool is ‘true’, use only preauth mode. If unable to setup it, disconnect immediately.
Set DES keyfile for decoding encrypted ident responses. Used with ‘ident://’ preauth mode.
Use only encrypted IDENT responses.
Set list of fields to return in response to ID command.
Valid field names are:
Package name (‘GNU Mailutils’).
Package version (‘2.2’).
Vendor name (‘GNU’).
The string ‘http://www.gnu.org/software/mailutils’
The string ‘51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA’.
OS name.
OS version number.
Name of the imap4d binary.
Invocation command line.
List of environment variables with their values.
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 |
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.
Display short help message and exit.
Run in inetd mode.
Run in foreground.
Start in preauth mode
Enable TLS support
Debug authentication functions.
Display program version and exit.
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.
comsatd Comsatd uses following option groups: ,
, .
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 |
Run as a standalone daemon.
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.
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 |
comsatd Following configuration statements affect the behavior of
comsatd:
| Statement | Reference |
|---|---|
| debug | See section Debug Statement. |
| logging | See section Logging Statement. |
| mailbox | See section Mailbox Statement. |
| locking | See section Locking Statement. |
| acl | See section ACL Statement. |
These statements control the general behavior of the comsat daemon:
Set maximum number of message body lines to be output.
Enable or disable processing of user's ‘.biffrc’ file. By default, it is enabled.
These statements control the way comsatd fights possible
flooding attacks.
Set maximum number of incoming requests per ‘request-control-interval’.
Set the request control interval.
Set initial amount of time to sleep, after the first overflow occurs.
Set overflow control interval. If two consecutive overflows happen within that interval, the overflow-delay-time is doubled.
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 section 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:
Produce an audible signal.
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.
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:
Expands to username
Expands to hostname
Expands to value of message header ‘name’.
Expands to message body. c and l give maximum number of characters and lines in the expansion. When omitted, they default to 400, 5.
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 ---
|
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"
|
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]
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.
Returns package name (string ‘mailutils’).
Returns full package string (e.g. ‘GNU Mailutils 2.1’)
Returns mailutils version.
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%>
|
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.
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.
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.
Appends whitespace + arg to string register.
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.
Generates the value for ‘In-reply-to:’ header according to RFC 2822.
Generates the value for ‘References:’ header according to RFC 2822.
Controls the character set in which the components decoded via
the decode (see decode function) format function should be
output.
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.
burstThe 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.
compUnderstands ‘--build’ option.
fmtdumpThis command is not provided. Use ‘fmtcheck’ instead.
mhlIf 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.
mhnmhn editing mode. This
is also the default mode. This differs from the standard
mhn, which switches to the editing mode only if no other
options were given and the input file name coincides with the value of
mhdraft environment variable.
mhn
prints the decoded message content using moreproc
variable. Standard mhn in this case used to print ‘don't
know how to display content’ diagnostic.
The default behaviour is to pipe the content to the standard input
of the mhn-show-type[/subtype] command. This is altered to using a
temporary file if the command contains %f or %F escapes.
Content-Disposition header contains ‘filename=’,
and mhn is invoked with ‘--auto’ switch, it
transforms the file name into the absolute notation and uses it only
if it lies below the current mhn-storage directory. Standard
mhn only requires that the file name do not begin with ‘/’.
Before saving a message part, GNU mhn checks if the file already
exists. If so, it asks whether the user wishes to rewrite it. This
behaviour is disabled when ‘--quiet’ option was given.
mhparamThe ‘--all’ mode does not display commented out entries.
replUnderstands ‘--use’ option. Disposition shell provides
use command.
rmmMailutils rmm does not delete any messages. Standard
rmm in this case deletes all messages preceding the
non-existent one.
rmmproc profile component is not used.
pickThe 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... |
refilerefile never makes links even if called with
‘--link’ option. The latter is actually a synonym for ‘--copy’,
which preserves the original message.
sortmNew 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 the ordered messages using a format string given by ‘--form’ or ‘--format’ option.
Do not actually sort messages, rather print what would have been done. This is useful for debugging purposes.
mailutils-config — Get the Information about the Mailutils Build This program is designed for developers wishing to link their programs against libmailutils. 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.
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 |
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: ‘libmailutils’. Arguments may be given that alter this behavior. These are:
Print flags to link against ‘libmu_auth’, the library adding new authentication methods to ‘libmailutils’.
Print flags to link against ‘libmu_scm’, the Guile interface library.
Link against mbox format library.
Link against mh format library.
Link against maildir format library.
Link against mailer library.
Link against imap format library.
Link against pop format library.
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` |
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.2 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:
The Mailutils uses PAM libraries.
The GNU wrapper library ‘libltdl’ is present and is used by Mailutils. See (libtool)Using libltdl section `Using libltdl' in Using libltdl, for more information on ‘libltdl’ library.
Support for Berkeley DB is compiled in (the package was configured with ‘--with-db2’ option).
Support for NDBM is compiled in (the package was configured with ‘--with-ndbm’ option).
Support for old style DBM is compiled in (the package was configured with ‘--with-dbm’ option).
Support for GNU DBM is compiled in (the package was configured with ‘--with-gdbm’ option). See (gdbm)Top section `Introduction' in The GNU DBM Manual, for more information about this library.
Support for GnuTLS (a Transport Layer Security Library) is compiled in (the package was configured with ‘--with-gnutls’ option).
Support for GNU SASL is compiled in (the package was configured with ‘--with-gsasl’ option). See (gsasl)Top section `Introduction' in The GNU SASL Manual, for more information about this library.
Support for GSSAPI is compiled in (the package was configured with ‘--with-gssapi’ option).
Support for Guile extension language is built (the package was configured with ‘--with-guile’ option). See (guile)Top section `Overview' in The Guile Reference Manual, for more information about Guile.
The POSIX thread support is compiled in.
The readline support is enabled (the package was configured with ‘--with-readline’ option). See (readline)Top section `Top' in The GNU Readline Library, for more information.
Authentication via MySQL is supported (the package was configured with ‘--enable-mysql’ option).
Support for mail virtual domains is enabled (the package was configured with ‘--enable-virtual-domains’ option).
Support for IMAP4 protocol is enabled.
Support for POP3 protocol is enabled.
Support for mailboxes in MH format is enabled.
Support for mailboxes in MAILDIR format is enabled.
Support for SMTP mailer is enabled.
Support for Sendmail mailer is enabled.
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:
|
|
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;
};
|
|
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) |
\------------------/
|
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_NULLThe pointer mbox supplied is NULL.
MU_ERR_NO_HANDLERThe url name supplied is invalid or not supported.
EINVALENOMEMNot enough memory to allocate resources.
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,
Destroys and releases resources held by mbox.
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:
EAGAINEINPROGRESSOperation in progress.
EBUSYResource busy.
MU_ERROR_INVALID_PARAMETERmbox is NULL or flag is invalid.
ENOMEMNot enough memory.
The stream attach to mbox is closed.
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETERmbox is NULL.
Get the folder.
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETERmbox is NULL.
Give the uid validity of mbox.
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETERmbox is NULL.
Give the next predicted uid for mbox.
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETERmbox is NULL.
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_PARAMETERmbox is NULL or msgno is invalid.
ENOMEMNot enough memory.
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_PARAMETERmbox is NULL or message is invalid.
Give the number of messages in mbox.
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETERmbox is NULL.
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_PARAMETERmbox is NULL.
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_PARAMETERmbox is NULL.
All messages marked for deletion are removed.
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETERmbox is NULL.
Gives the mbox size.
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETERmbox is NULL.
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_PARAMETERmbox is NULL.
ENOMEMNot enough memory.
The mailbox stream is put in stream.
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETERmbox is invalid or stream is NULL.
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_PARAMETERmbox or stream is NULL.
Get the mu_locker_t object.
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETERmbox is NULL.
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_PARAMETERmbox is NULL.
Get the property object.
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETERmbox is NULL.
ENOMEMGives the constructed url.
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETERmbox is NULL.
Get a debug object.
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETERmbox is NULL.
ENOMEMGet the observable object.
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETERmbox is NULL.
ENOMEMNot enough memory.
|
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.
Some possible use cases the API must support are:
mu_mailer_send_message(mailer, msg, NULL, NULL)
To: or Apparently-To: header will be added if non is present (for RFC compliance)
mu_mailer_send_message(mailer, msg, from, to)
Resent-[To,From,...]
mu_mailer_send_message(mailer, msg, NULL, to)
mu_mailer_deliver(mailer, msg, address_t("<>"), to)
Don't want mail loops, so the null but valid SMTP address of ‘<>’ is the envelope From.
‘/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!
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?
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.
|
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 |
+--------------------+
|
The resources allocate for msg are freed.
Retrieve msg header.
Set *multi to non-zero value if msg is multi-part.
|
Primarily for internal use.
Primarily for internal use.
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.
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.
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.
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.
|
So far we plan support for RFC822 and plan for RFC1522. With RFC1522 non-ASCII characters will be encoded.
Initialize a hdr to a supported type. If blurb is not NULL,
it is parsed.
The resources allocated for hdr are freed.
Some basic macros are already provided for RFC822.
MU_HEADER_UNIX_FROMFrom
MU_HEADER_RETURN_PATHReturn-Path
MU_HEADER_RECEIVEDReceived
MU_HEADER_DATEDate
MU_HEADER_FROMFrom
MU_HEADER_SENDERSender
MU_HEADER_RESENT_FROMResent-From
MU_HEADER_SUBJECTSubject
MU_HEADER_SENDERSender
MU_HEADER_RESENT_SENDERResent-SENDER
MU_HEADER_TOTo
MU_HEADER_RESENT_TOResent-To
MU_HEADER_CCCc
MU_HEADER_RESENT_CCResent-Cc
MU_HEADER_BCCBcc
MU_HEADER_RESENT_BCCResent-Bcc
MU_HEADER_REPLY_TOReply-To
MU_HEADER_RESENT_REPLY_TOResent-Reply-To
MU_HEADER_MESSAGE_IDMessage-ID
MU_HEADER_RESENT_MESSAGE_IDResent-Message-ID
MU_HEADER_IN_REPLY_TOIn-Reply-To
MU_HEADER_REFERENCEReference
MU_HEADER_REFERENCESReferences
MU_HEADER_ENCRYPTEDEncrypted
MU_HEADER_PRECEDENCEPrecedence
MU_HEADER_STATUSStatus
MU_HEADER_CONTENT_LENGTHContent-Length
MU_HEADER_CONTENT_LANGUAGEContent-Language
MU_HEADER_CONTENT_TRANSFER_ENCODINGContent-transfer-encoding
MU_HEADER_CONTENT_IDContent-ID
MU_HEADER_CONTENT_TYPEContent-Type
MU_HEADER_CONTENT_DESCRIPTIONContent-Description
MU_HEADER_CONTENT_DISPOSITIONContent-Disposition
MU_HEADER_CONTENT_MD5Content-MD5
MU_HEADER_MIME_VERSIONMIME-Version
MU_HEADER_X_UIDLX-UIDL
MU_HEADER_X_UIDX-UID
MU_HEADER_X_IMAPBASEX-IMAPbase
MU_HEADER_ENV_SENDERX-Envelope-Sender
MU_HEADER_ENV_DATEX-Envelope-Date
MU_HEADER_FCCFcc
MU_HEADER_DELIVERY_DATEDelivery-date
MU_HEADER_ENVELOPE_TOEnvelope-to
Value of field-name fn is returned in buffer fv of size len. The number of bytes written is put in n.
The value is allocated.
|
Initialize an object body.
The resources allocated are release.
|
|
These generic flags are interpreted as appropriate to the specific streams.
MU_STREAM_READThe stream is open read only.
MU_STREAM_WRITEThe stream is open write only.
MU_STREAM_RDWRThe stream is open read and write.
MU_STREAM_APPENDThe stream is open in append mode for writing.
MU_STREAM_CREATThe stream open will create the underlying resource (such as a file) if it doesn't exist already.
MU_STREAM_NONBLOCKThe stream is set non blocking.
MU_STREAM_NO_CHECKStream is destroyed without checking for the owner.
MU_STREAM_SEEKABLEMU_STREAM_NO_CLOSEStream doesn't close it's underlying resource when it is closed or destroyed.
MU_STREAM_ALLOW_LINKSIf MU_STREAM_NO_CLOSE is specified, fclose() will not be called on
stdio when the stream is closed.
Used to implement a new kind of stream.
MU_STREAM_STATE_OPENLast action was mu_stream_open.
MU_STREAM_STATE_READLast action was mu_stream_read or mu_stream_readline.
MU_STREAM_STATE_WRITELast action was mu_stream_write.
MU_STREAM_STATE_CLOSELast action was mu_stream_close.
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);
}
|
|
|
There are many ways to authenticate to a server. To be flexible the
authentication process is provided by three objects mu_authority_t,
mu_ticket_t, and mu_wicket_t. The mu_authority_t can implement
different protocol like APOP, MD5-AUTH, One Time Passwd, etc. By default
if a mailbox does not understand or know how to authenticate it falls back
to user/passwd authentication. The mu_ticket_t is a way for
Mailboxes and Mailers provide a way to authenticate when the URL does not
contain enough information. The default action is to call the function
mu_authority_authenticate() which will get the user and passwd
if not set, this function can be overridden by a custom method.
A simple example of an authenticate function:
#include <stdio.h>
#include <string.h>
#include <mailutils/auth.h>
int
my_authenticate (auth_t auth, char **user, char **passwd)
{
char u[128] = "";
char p[128] = "";
/* prompt the user name */
printf ("User: ");
fflush (stdout);
fgets (u, sizeof (u), stdin);
u[strlen (u) - 1] = '\0'; /* nuke the trailing NL */
/* prompt the passwd */
printf ("Passwd: "); fflush (stdout);
echo_off ();
fgets (p, sizeof(p), stdin);
echo_on ();
p[strlen (p) - 1] = '\0';
/* duplicate */
*user = strdup (u);
*passwd = strdup (p);
return 0;
}
|
|
The Internet address format is defined in RFC 822. RFC 822 has been updated, and is now superceeded by RFC 2822, which makes some corrections and clarifications. References to RFC 822 here apply equally to RFC 2822.
The RFC 822 format is more flexible than many people realize, here is a quick summary of the syntax this parser implements, see RFC 822 for the details. ‘[]’ pairs mean "optional", ‘/’ means "one or the other", and double-quoted characters are literals.
addr-spec = local-part "@" domain
mailbox = addr-spec ["(" display-name ")"] /
[display-name] "<" [route] addr-spec ">"
mailbox-list = mailbox ["," mailbox-list]
group = display-name ":" [mailbox-list] ";"
address = mailbox / group / unix-mbox
address-list = address ["," address-list]
|
Unix-mbox is a non-standard extension meant to deal with the common practice of using user names as addresses in mail utilities. It allows addresses such as "root" to be parsed correctly. These are not valid internet email addresses, they must be qualified before use.
Several address functions have a set of common arguments with consistent semantics, these are described here to avoid repetition.
Since an address-list may contain multiple addresses, they are accessed by a one-based index number, no. The index is one-based because pop, imap, and other message stores commonly use one-based counts to access messages and attributes of messages.
If len is greater than 0 it is the length of the buffer
buf, and as much of the component as possible will be copied
into the buffer. The buffer will be NULL terminated.
The size of a particular component may be queried by providing 0
for the len of the buffer, in which case the buffer is optional.
In this case, if n is provided *n is assigned the length of
the component string.
The mu_address_t object is used to hold information about a parsed
RFC822 address list, and is an opaque
data structure to the user. Functions are provided to retrieve information
about an address in the address list.
This function allocates and initializes addr by parsing the RFC822 address-list string.
The return value is 0 on success and a code number on error conditions:
EINVALInvalid usage, usually a required argument was NULL.
ENOMEMNot enough memory to allocate resources.
ENOENTInvalid RFC822 syntax, parsing failed.
This function allocates and initializes addr by parsing the
array of pointers to RFC822 address-lists in sv. If len is
-1, then sv must be NULL terminated in the fashion of argv,
otherwise len is the length of the array.
The return value is 0 on success and a code number on error conditions:
EINVALInvalid usage, usually a required argument was NULL.
ENOMEMNot enough memory to allocate resources.
ENOENTInvalid RFC822 syntax, parsing failed.
The addr is destroyed.
Accesses the noth email address component of the address list. This address is the plain email address, correctly quoted, suitable for using in an smtp dialog, for example, or as the address part of a contact book entry.
Note that the entry may be valid, but be a group name. In this case success
is returned, but the length of the address is 0.
The return value is 0 on success and a code number on error conditions:
EINVALInvalid usage, usually a required argument was NULL.
ENOENTThe index no is outside of the range of available addresses.
Accesses the local-part of an email addr-spec extracted while parsing the noth email address.
The return value is 0 on success and a code number on error conditions:
EINVALInvalid usage, usually a required argument was NULL.
ENOENTThe index no is outside of the range of available addresses.
Accesses the domain of an email addr-spec extracted while
parsing the noth email address. This will be 0
length for a unix-mbox.
The return value is 0 on success and a code number on error conditions:
EINVALInvalid usage, usually a required argument was NULL.
ENOENTThe index no is outside of the range of available addresses.
Accesses the display-name describing the noth email address. This display-name is optional, so may not be present. If it is not present, but there is an RFC822 comment after the address, that comment will be returned as the personal phrase, as this is a common usage of the comment even though it is not defined in the internet mail standard.
A group is a kind of a special case. It has a display-name, followed
by an optional mailbox-list. The display-name will be allocated an address
all it's own, but all the other elements (local-part, domain, etc.) will
be zero-length. So "a group: ;" is valid, will have a count of 1, but
mu_address_get_email(), and all the rest, will return zero-length output.
The return value is 0 on success and a code number on error conditions:
EINVALInvalid usage, usually a required argument was NULL.
ENOENTThe index no is outside of the range of available addresses.
Accesses the comments extracted while parsing the noth email address. These comments have no defined meaning, and are not currently collected.
The return value is 0 on success and a code number on error conditions:
EINVALInvalid usage, usually a required argument was NULL.
ENOENTThe index no is outside of the range of available addresses.
Accesses the route of an email addr-spec extracted while parsing the noth email address. This is a rarely used RFC822 address syntax, but is legal in SMTP as well. The entire route is returned as a string, those wishing to parse it should look at ‘mailutils/parse822.h’.
The return value is 0 on success and a code number on error conditions:
EINVALInvalid usage, usually a required argument was NULL.
ENOENTThe index no is outside of the range of available addresses.
As above, but mallocs the email address, if present,
and write a pointer to it into bufp. bufp will be NULL
if there is no email address to return.
The return value is 0 on success and a code number on error conditions:
EINVALInvalid usage, usually a required argument was NULL.
ENOENTThe index no is outside of the range of available addresses.
Sets *yes to 1 if this address is just the name of a group,
0 otherwise. This is faster than checking if the address has
a non-zero length personal, and a zero-length local_part and domain.
yes can be NULL, though that doesn't serve much purpose other
than determining that no refers to an address.
Currently, there is no way to determine the end of the group.
The return value is 0 on success and a code number on error conditions:
EINVALInvalid usage, usually a required argument was NULL.
ENOENTThe index no is outside of the range of available addresses.
Returns the entire address list as a single RFC822 formatted address list.
The return value is 0 on success and a code number on error conditions:
EINVALInvalid usage, usually a required argument was NULL.
ENOMEMNot enough memory to allocate resources.
Returns a count of the addresses in the address list.
If addr is NULL, the count is 0. If count is
not NULL, the count will be written to *count.
The return value is 0.
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif
#include <stdio.h>
#include <string.h>
#include <errno.h>
#include <mailutils/address.h>
#include <mailutils/errno.h>
#include <mailutils/kwd.h>
#include <mailutils/mutil.h>
#define EPARSE MU_ERR_NOENT
struct mu_address hint;
int hflags;
static int
parse (const char *str)
{
size_t no = 0;
size_t pcount = 0;
int status;
const char *buf;
mu_address_t address = NULL;
status = mu_address_create_hint (&address, str, &hint, hflags);
mu_address_get_count (address, &pcount);
if (status)
{
printf ("%s=> error %s\n\n", str, mu_errname (status));
return 0;
}
else
{
printf ("%s=> pcount %lu\n", str, (unsigned long) pcount);
}
for (no = 1; no <= pcount; no++)
{
int isgroup;
mu_address_is_group (address, no, &isgroup);
printf ("%lu ", (unsigned long) no);
if (isgroup)
{
mu_address_sget_personal (address, no, &buf);
printf ("group <%s>\n", buf);
}
else
{
mu_address_sget_email (address, no, &buf);
printf ("email <%s>\n", buf);
}
if (mu_address_sget_personal (address, no, &buf) == 0 && buf && !isgroup)
printf (" personal <%s>\n", buf);
if (mu_address_sget_comments (address, no, &buf) == 0 && buf)
printf (" comments <%s>\n", buf);
if (mu_address_sget_local_part (address, no, &buf) == 0 && buf)
{
printf (" local-part <%s>", buf);
if (mu_address_sget_domain (address, no, &buf) == 0 && buf)
printf (" domain <%s>", buf);
printf ("\n");
}
if (mu_address_sget_route (address, no, &buf) == 0 && buf)
printf (" route <%s>\n", buf);
}
mu_address_destroy (&address);
printf ("\n");
return 0;
}
struct mu_kwd hintnames[] = {
{ "comments", MU_ADDR_HINT_COMMENTS },
{ "personal", MU_ADDR_HINT_PERSONAL },
{ "email", MU_ADDR_HINT_EMAIL },
{ "local", MU_ADDR_HINT_LOCAL },
{ "domain", MU_ADDR_HINT_DOMAIN },
{ "route", MU_ADDR_HINT_ROUTE },
{ NULL }
};
static char **
addr_fieldptr_by_mask (mu_address_t addr, int mask)
{
switch (mask)
{
case MU_ADDR_HINT_ADDR:
return &addr->addr;
case MU_ADDR_HINT_COMMENTS:
return &addr->comments;
case MU_ADDR_HINT_PERSONAL:
return &addr->personal;
case MU_ADDR_HINT_EMAIL:
return &addr->email;
case MU_ADDR_HINT_LOCAL:
return &addr->local_part;
case MU_ADDR_HINT_DOMAIN:
return &addr->domain;
case MU_ADDR_HINT_ROUTE:
return &addr->route;
}
return NULL;
}
void
sethint (char *str)
{
int mask;
char *p = strchr (str, '=');
if (!p)
{
printf ("%s=> bad assignment\n\n", str);
return;
}
*p++ = 0;
if (mu_kwd_xlat_name (hintnames, str, &mask) == 0)
{
char **fptr = addr_fieldptr_by_mask (&hint, mask);
if (*p == 0)
hflags &= ~mask;
else
{
*fptr = strdup (p);
hflags |= mask;
}
}
else
printf ("%s=> unknown hint name\n\n", str);
}
static int
parseinput (void)
{
char buf[BUFSIZ];
while (fgets (buf, sizeof (buf), stdin) != 0)
{
buf[strlen (buf) - 1] = 0;
if (buf[0] == '\\')
sethint (buf + 1);
else
parse (buf);
}
return 0;
}
int
main (int argc, char *argv[])
{
int i;
hint.domain = "localhost";
hflags = MU_ADDR_HINT_DOMAIN;
if (argc == 1)
return parseinput ();
for (i = 1; i < argc; i++)
{
if (strcmp (argv[i], "-") == 0)
parseinput ();
else if (strncmp (argv[i], "-v", 2) == 0)
sethint (argv[i] + 2);
else
parse (argv[i]);
}
return 0;
}
|
|
A flags of 0 means that the default will be used.
Time is measured in seconds.
A mailbox or a mailer can be described in a URL, the string will contain the
necessary information to initialize mailbox_t, or mailer_t
properly.
The POP URL scheme contains a POP server, optional port number and the authentication mechanism. The general form is
< |
If :port is omitted the default value is 110. Different forms of authentication can be specified with ;AUTH=type. The special string ;AUTH=* indicates that the client will use a default scheme base on the capability of the server.
< |
For more complete information see RFC 2368.
The POP3S URL scheme contains a POP server over SSL, optional port number and the authentication mechanism. The general form is
< |
If :port is omitted the default value is 995.
The IMAP URL scheme contains an IMAP server, optional port number and the authentication mechanism. The general form is
< |
If :port is omitted the default value is 143. Different forms of authentication can be specified with ;AUTH=type. The special string ;AUTH=* indicates that the client will use a default scheme base on the capability of the server.
< |
For more complete information see RFC 2192.
The IMAPS URL scheme contains an IMAP server over SSL, optional port number and the authentication mechanism. The general form is
< |
If :port is omitted the default value is 993.
Local folder should be handle by this URL. It is preferable to let the mailbox recognize the type of mailbox and take the appropriate action.
< |
For MMDF, MH local mailboxes URLs are provided, but it is preferable to
use <file://path> and let the library figure out which one.
< |
After setting a mailer, <mailto:> is used to tell the mailer where
and to whom the message is for.
< |
Mailto can be used to generate short messages, for example to subscribe to mailing lists.
< |
For more complete information see RFC 2368.
Helper functions are provided to retrieve and set the URL fields.
Create the url data structure, but do not parse it.
Destroy the url and free its resources.
Parses the url, after calling this the get functions can be called.
The syntax, condensed from RFC 1738, and extended with the ;auth= of RFC 2384 (for POP) and RFC 2192 (for IMAP) is:
url =
scheme ":" [ "//"
[ user [ ( ":" password ) | ( ";auth=" auth ) ] "@" ]
host [ ":" port ]
[ ( "/" urlpath ) | ( "?" query ) ] ]
|
This is a generalized URL syntax, and may not be exactly appropriate for any particular scheme.
Decodes an RFC 1738 encoded string, returning the decoded string
in allocated memory. If the string is not encoded, this degenerates to
a strdup().
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <mailutils/error.h>
#include <mailutils/errno.h>
#include <mailutils/url.h>
#include <mailutils/secret.h>
#define CAT2(a,b) a ## b
#define GET_AND_PRINT(field,u,buf,status) \
status = CAT2(mu_url_sget_,field) (u, &buf); \
if (status == MU_ERR_NOENT) \
buf = ""; \
else if (status) \
{ \
mu_error ("cannot get %s: %s", #field, mu_strerror (status)); \
exit (1); \
} \
printf ("\t" #field " <%s>\n", buf)
static void
print_fvpairs (mu_url_t url)
{
size_t fvc, i;
char **fvp;
int rc = mu_url_sget_fvpairs (url, &fvc, &fvp);
if (rc)
{
mu_error ("cannot get F/V pairs: %s", mu_strerror (rc));
exit (1);
}
if (fvc == 0)
return;
for (i = 0; i < fvc; i++)
printf ("\tparam[%lu] <%s>\n", (unsigned long) i, fvp[i]);
}
static void
print_query (mu_url_t url)
{
size_t qargc, i;
char **qargv;
int rc = mu_url_sget_query (url, &qargc, &qargv);
if (rc)
{
mu_error ("cannot get query: %s", mu_strerror (rc));
exit (1);
}
if (qargc == 0)
return;
for (i = 0; i < qargc; i++)
printf ("\tquery[%lu] <%s>\n", (unsigned long) i, qargv[i]);
}
int
main ()
{
char str[1024];
long port = 0;
mu_url_t u = NULL;
while (fgets (str, sizeof (str), stdin) != NULL)
{
int rc;
const char *buf;
mu_secret_t secret;
str[strlen (str) - 1] = '\0'; /* chop newline */
if (strspn (str, " \t") == strlen (str))
continue; /* skip empty lines */
if ((rc = mu_url_create (&u, str)) != 0)
{
fprintf (stderr, "mu_url_create %s ERROR: [%d] %s",
str, rc, mu_strerror (rc));
exit (1);
}
if ((rc = mu_url_parse (u)) != 0)
{
printf ("%s => FAILED: [%d] %s\n",
str, rc, mu_strerror (rc));
continue;
}
printf ("%s => SUCCESS\n", str);
GET_AND_PRINT (scheme, u, buf, rc);
GET_AND_PRINT (user, u, buf, rc);
rc = mu_url_get_secret (u, &secret);
if (rc == MU_ERR_NOENT)
printf ("\tpasswd <>\n");
else if (rc)
{
mu_error ("cannot get %s: %s", "passwd", mu_strerror (rc));
exit (1);
}
else
{
printf ("\tpasswd <%s>\n", mu_secret_password (secret));
mu_secret_password_unref (secret);
}
GET_AND_PRINT (auth, u, buf, rc);
GET_AND_PRINT (host, u, buf, rc);
rc = mu_url_get_port (u, &port);
if (rc)
{
mu_error ("cannot get %s: %s", "port", mu_strerror (rc));
exit (1);
}
printf ("\tport %ld\n", port);
GET_AND_PRINT (path, u, buf, rc);
print_fvpairs (u);
print_query (u);
mu_url_destroy (&u);
}
return 0;
}
|
|
|
The standard RFC 1524 (A User Agent Configuration Mechanism) suggests a file format to be used to inform a mail user agent about facilities for handling mail in various format. The configuration file is known also as mailcap and it is tipically found in UNIX platforms, a example of ‘/etc/mailcap’:
application/pgp; gpg < %s | metamail; needsterminal; \
test=test %{encapsulation}=entity ; copiousoutput
|
A mailcap file consists of a set of mailcap entries per line, lines beginning with ‘#’ are considered comments and ignored. Long mailcap entry may be continued on multiple lines if each line ends with a backslash character ‘\’, the multiline will be considered a single mailcap entry. The overall format in BNF:
Mailcap-File = *mailcap-line Mailcap-Line = comment | mailcap-entry Comment = newline | "#" * char newline Newline = <newline as defined by OS convention> |
Each mailcap entry consists of a number of fields, separated by semi-colons. The first two fields are required and must occur in the specified order, the remaining fields are optional.
Mailcap-Entry = typefield ";" view-command ";" *[ ";" field ] |
The mu_mailcap_t and mu_mailcap_entry_t objects
are used to hold information and it is an opaque data structure
to the user. Functions are provided to retrieve information
from the data structure.
mu_mailcap_t mu_mailcap_entry_t
-/etc/mailcap- +--->/------------------------\ +-->/------------------\
( alain ) | mu_mailcap_entry[0]*--|--+ | typefield |
| mu_mailcap_entry[1] | | view-command |
| ..... | | field[0] |
| mu_mailcap_entry[n] | | ..... |
\------------------------/ | field[n] |
\------------------/
|
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif
#include <stdlib.h>
#include <stdio.h>
#include <mailutils/mailcap.h>
#include <mailutils/stream.h>
#include <mailutils/error.h>
int
main (int argc, char **argv)
{
mu_stream_t stream = NULL;
int status = 0;
char *file = argc == 1 ? "/etc/mailcap" : argv[1];
mu_mailcap_t mailcap = NULL;
status = mu_file_stream_create (&stream, file, MU_STREAM_READ);
if (status)
{
mu_error ("cannot create file stream %s: %s",
file, mu_strerror (status));
exit (1);
}
status = mu_stream_open (stream);
if (status)
{
mu_error ("cannot open file stream %s: %s",
file, mu_strerror (status));
exit (1);
}
status = mu_mailcap_create (&mailcap, stream);
if (status == 0)
{
int i;
size_t count = 0;
char buffer[256];
mu_mailcap_entries_count (mailcap, &count);
for (i = 1; i <= count; i++)
{
size_t j;
mu_mailcap_entry_t entry = NULL;
size_t fields_count = 0;
printf ("entry[%d]\n", i);
mu_mailcap_get_entry (mailcap, i, &entry);
/* typefield. */
mu_mailcap_entry_get_typefield (entry, buffer,
sizeof (buffer), NULL);
printf ("\ttypefield: %s\n", buffer);
/* view-command. */
mu_mailcap_entry_get_viewcommand (entry, buffer,
sizeof (buffer), NULL);
printf ("\tview-command: %s\n", buffer);
/* fields. */
mu_mailcap_entry_fields_count (entry, &fields_count);
for (j = 1; j <= fields_count; j++)
{
int status = mu_mailcap_entry_get_field (entry, j, buffer,
sizeof (buffer), NULL);
if (status)
{
mu_error ("cannot retrieve field %lu: %s",
(unsigned long) j,
mu_strerror (status));
break;
}
printf ("\tfields[%lu]: %s\n", (unsigned long) j, buffer);
}
printf ("\n");
}
mu_mailcap_destroy (&mailcap);
}
return 0;
}
|
The function allocates, parses the buffer from the stream and initializes mailcap.
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETERmailcap is NULL or stream is invalid.
Release any resources from the mailcap object.
The function returns the number of entries found in the mailcap.
The return value is 0 on success and a code number on error conditions:
EINVALmailcap or count is NULL.
Returns in entry the mailcap entry of no.
The function returns the number of fields found in the entry.
The return value is 0 on success and a code number on error conditions:
EINVALentry or count is NULL.
Helper function saving in buffer, the argument of "compose" field.
Helper function saving in buffer, the argument of "composetyped" field.
Helper function saving in buffer, the argument of "edit" field.
Helper function saving in buffer, the argument of "textualnewlines" field.
Helper function saving in buffer, the argument of "test" field.
Helper function saving in buffer, the argument of "x11-bitmap" field.
Helper function saving in buffer, the argument of "description" field.
Helper function saving in buffer, the argument of "nametemplate" field.
Helper function saving in buffer, the argument of "notes" field.
Helper function. Returns *on != 0 if the flag needsterminal is in the record.
Helper function. Returns *on != 0 if the flag copiousoutput is in the record.
The functions from ‘libmailutils’ library get user information from the system user database. The library ‘libmu_auth’ extends this functionality, allowing ‘libmailutils’ functions to obtain information about a user from several places, like SQL database, etc. The method used is described in detail in authentication. This chapter contains a very succinct description of the underlying library mechanism.
This is a pointer to authentication or authorization data. It is defined as follows:
typedef int (*mu_auth_fp) (struct mu_auth_data **return_data,
void *key,
void *func_data,
void *call_data);
|
Its arguments are:
Upon successful return authorization handler leaves in this memory
location a pointer to the filled mu_auth_data structure
with the user's information.
For authentication handlers this argument is always NULL and
should be ignored.
The search key value. Its actual type depends upon type of the handler.
For authorization handlers it is const char* if the handler is called by
mu_get_auth_by_name() and uid_t * if it is called by
mu_get_auth_by_uid().
For authentication handlers it is always struct mu_auth_data*
representing the user's data obtained by a previous call to a
mu_get_auth_by_… function.
Any data associated with this handler.
Any call specific data. This argument is not used at the moment.
The mu_auth_data is used to return the information about the
user. It is similar to system struct passwd, except that it
is more mailutils-specific. Its definition is:
struct mu_auth_data {
/* These are from struct passwd */
char *name; /* user name */
char *passwd; /* user password */
uid_t uid; /* user id */
gid_t gid; /* group id */
char *gecos; /* real name */
char *dir; /* home directory */
char *shell; /* shell program */
/* */
char *mailbox; /* Path to the user's system mailbox */
int change_uid; /* Should the uid be changed? */
};
|
The mu_auth_module structure contains full information about a
libmu_auth module. It is declared as follows:
struct mu_auth_module {
char *name; /* Module name */
struct argp *argp; /* Corresponding argp structure */
mu_auth_fp authenticate; /* Authentication function ... */
void *authenticate_data; /* ... and its specific data */
mu_auth_fp auth_by_name; /* Get user info by user name */
void *auth_by_name_data; /* ... and its specific data */
mu_auth_fp auth_by_uid; /* Get user info by user id */
void *auth_by_uid_data; /* ... and its specific data */
};
|
This function registers the command line capability “auth”. It must be
called after registering ‘libmu_auth’ modules and before calling
mu_agrp_parse(). If an error occurs, this function prints
diagnostic message and aborts the program.
This macro registers all default modules and calls mu_auth_init().
Create a mu_auth_data structure and initialize it with the given
values. Returns 0 on success and 1 otherwise.
Free the mu_auth_data structure allocated by a call to
mu_auth_data_alloc().
Register the module defined by the mod argument.
The list is expected to contain mu_auth_fp pointers. Each of them
is dereferenced and executed until either the list is exhausted or any
of the functions returns non-zero, whichever occurs first. The
return_data and key arguments are passed as the first two
parameters to the function (see the definition of mu_auth_fp,
notice the footnote), the call_data is passed as its last
parameter.
The function returns 0 if none of the functions from list
succeeded, i.e. returned non-zero value. Otherwise it returns the
return code from the succeeded function.
Search the information about given user by its username. Similar to
system's getpwnam call).
Search the information about given user by its uid. Similar to
system's getpwuid call).
Authenticate the user whose data are in auth_data using password pass. Return 0 if the user is authenticated.
The “not-supported” module. Always returns ENOSYS.
This module is always registered even if ‘libmu_auth’ is not linked. It performs usual authentication using system user database (‘/etc/password’ et al.)
This module is always registered even if ‘libmu_auth’ is not linked.
Both its authorization handlers are mu_auth_nosupport. Its
authentication handler computes the MD5 or DES hash over the supplied
password with the seed taken from passwd member of its key
argument. Then it compares the obtained hash with the passwd
member itself and returns 1 if both strings match.
Implements PAM authentication. Both authorization handlers are
mu_auth_nosupport().
Implements authentication and authorization via MySQL database. The
credentials for accessing the database are taken from global variables
sql_host, sql_port, sql_user, sql_passwd
and sql_db. The SQL queries for retrieving user information
from global variables sql_getpwnam_query and
sql_getpwuid_query. The variable sql_getpass_query keeps
the query used for retrieving user's password. , for
information on command line options used to set these variables.
Implements mu_get_auth_by_name method using virtual mail domains.
Neither mu_get_auth_by_uid nor mu_authenticate is
implemented. This module must be used together with generic
module.
To link your program against ‘libmu_auth’, obtain loader arguments
by running mailutils-config as follows:
mailutils-config --link auth |
See section mailutils-config — Get the Information about the Mailutils Build, for more information about this utility.
Here is a sample Makefile fragment:
MU_LDFLAGS=`mailutils-config --link auth`
MU_INCLUDES=`mailutils-config --include`
myprog: myprog.c
$(CC) -omyprog $(CFLAGS) $(MU_INCLUDES) myprog.c $(MU_LDFLAGS)
|
If your program will be using only default modules provided by the
library, then it will suffice to call
MU_AUTH_REGISTER_ALL_MODULES() somewhere near the start of
your program. As an example, consider the following code fragment
(it is taken from the imap4d daemon):
int
main (int argc, char **argv)
{
struct group *gr;
int status = EXIT_SUCCESS;
state = STATE_NONAUTH; /* Starting state in non-auth. */
MU_AUTH_REGISTER_ALL_MODULES ();
mu_argp_parse (&argp, &argc, &argv, 0, imap4d_capa,
NULL, &daemon_param);
…
|
Otherwise, if your program will use it's own modules, first register
them with mu_auth_register_module and then call
mu_auth_init(), e.g.:
struct mu_auth_module radius_module = {
…
};
struct mu_auth_module ext_module = {
…
};
int
main (int argc, char **argv)
{
mu_auth_register_module (&radius_module);
mu_auth_register_module (&ext_module);
mu_auth_init ();
…
|
These two approaches may be combined, allowing you to use both your modules and the ones provided by Mailutils. Consider the example below:
int
main (int argc, char **argv)
{
mu_auth_register_module (&radius_module);
mu_auth_register_module (&ext_module);
MU_AUTH_REGISTER_ALL_MODULES ();
…
}
|
The library ‘libmu_scm’ provides an interface between Mailutils and Guile, allowing to access the Mailutils functionality from a Scheme program. For more information about Guile, refer to (guile)Top section `Overview' in The Guile Reference Manual. For information about Scheme programming language, See (r4rs)Top section `Top' in Revised(4) Report on the Algorithmic Language Scheme.
Return personal part of the numth email address from address.
Return comment part of the numth email address from address.
Return email part of the numth email address from address.
Return domain part of the numth email address from address.
Return local part of the numth email address from address.
Return number of parts in email address address.
Deduce user's email address from his username. If name is omitted, current username is assumed
If url is given, sets it as a name of the user's mail directory. Returns the current value of the mail directory.
If url is given, sets it as a name of the user's folder directory. Returns the current value of the folder directory.
Opens the mailbox specified by url. mode is a string, consisting of the characters described below, giving the access mode for the mailbox
| mode | Meaning |
|---|---|
| r | Open for reading. |
| w | Open for writing. |
| a | Open for appending to the end of the mailbox. |
| c | Create the mailbox if it does not exist. |
Closes mailbox mbox.
Returns url of the mailbox mbox.
Returns a port associated with the contents of the mbox. mode is a string defining operation mode of the stream. It may contain any of the two characters: ‘r’ for reading, ‘w’ for writing.
Retrieve from message #msgno from the mailbox mbox.
Returns number of messages in the mailbox mbox.
Expunges deleted messages from the mailbox mbox.
Appends message mesg to the mailbox mbox.
Creates an empty message.
Creates the copy of the message mesg.
Destroys the message mesg.
Sets new value to the header header of the message mesg. If header is already present in the message its value is replaced with the supplied one if the optional replace is #t. Otherwise, a new header is created and appended.
Returns the size of the message mesg .
Returns number of lines in the given message.
Returns email address of the sender of the message mesg.
Returns value of the header header from the message mesg.
Returns the list of headers in the message mesg. Optional argument headers gives a list of header names to restrict return value to.
Set the headers in the message mesg from list list is a list of conses (cons HEADER VALUE). The function sets these headers in the message mesg. Optional parameter replace specifies whether the new header values should replace the headers already present in the message.
Mark the message mesg as deleted. Optional argument flag allows to toggle
deletion mark. The message is deleted if it is #t and undeleted if
it is #f
Return value of the attribute flag of the message mesg.
Set the attribute flag of the message mesg. If optional value is #f, the attribute is unset.
Return the value of the user attribute flag from the message mesg.
Set the given user attribute flag in the message mesg. If optional argument value is ‘#f’, the attribute is unset.
Returns a port associated with the given mesg. mode is a string
defining operation mode of the stream. It may contain any of the
two characters: ‘r’ for reading, ‘w’ for writing.
If optional argument full is specified, it should be a boolean value.
If it is ‘#t’ then the returned port will allow access to any
part of the message (including headers). If it is #f then the port
accesses only the message body (the default).
Returns the message body for the message mesg.
Returns #t if mesg is a multipart MIME message.
Returns number of parts in a multipart MIME message. Returns
#f if the argument is not a multipart message.
Returns part #part from a multipart MIME message mesg.
Sends the message mesg. Optional mailer overrides default mailer settings in mu-mailer. Optional from and to give sender and receiver addresses.
Returns uid of the message mesg
Read next line from the body.
Append text to message body.
Creates a new MIME object. Both arguments are optional. flags specifies the type of the object to create (‘0’ is a reasonable value). mesg gives the message to create the MIME object from.
Returns #t if mime is a multipart object.
Returns number of parts in the MIME object mime.
Returns numth part from the MIME object mime.
Adds mesg to the MIME object mime.
Converts MIME object mime to a message.
Opens a connection to the system logger for Guile program. ident, option and facility have the same meaning as in openlog(3)
Distributes text via syslogd priority prio.
Closes the channel to the system logger opened by mu-openlog.
Registers desired mailutils formats. Any number of arguments can be given. Each argument must be one of the following strings:
| Argument | Meaning |
|---|---|
| ‘mbox’ | Regular UNIX mbox format |
| ‘mh’ | MH mailbox format |
| ‘maildir’ | Maildir mailbox format |
| ‘pop’ | POP mailbox format |
| ‘imap’ | IMAP mailbox format |
| ‘sendmail’ | sendmail mailer format |
| ‘smtp’ | SMTP mailer format |
If called without arguments, the function registers all available formats
Return the error message corresponding to err, which must be an integer value.
If you plan to link your program directly to ‘libguile’, it will probably make sense to link ‘libmu_scm’ directly as well. The arguments to the program loader may be obtained by running
mailutils-config --link guile |
See section mailutils-config — Get the Information about the Mailutils Build, for more information about this utility.
Here is a sample Makefile fragment:
MU_LDFLAGS=`mailutils-config --link guile`
MU_INCLUDES=`mailutils-config --include`
myprog: myprog.c
$(CC) -omyprog $(CFLAGS) $(MU_INCLUDES) myprog.c $(MU_LDFLAGS)
|
Dynamic linking is the preferred method of using ‘libmu_scm’. It uses Guile “use-modules” mechanism. An interface module ‘mailutils.scm’ is provided in order to facilitate using this method. This module is installed in the package data directory (by default it is ‘prefix/share/mailutils’). A sample use of this module is:
(set! %load-path (list "/usr/local/share/mailutils")) (use-modules (mailutils)) # Now you may use mailutils functions: (let ((mb (mu-mailbox-open "/var/spool/mail/gray" "r"))) ... |
Note, that you should explicitly modify the %load-path
before calling use-modules, otherwise Guile will not be able to
find ‘mailutils.scm’.
Libmu_sieve is GNU implementation of the mail filtering
language Sieve. The library is built around a Sieve Machine — an
abstract computer constructed specially to handle mail filtering tasks.
This computer has two registers: program counter and numeric accumulator;
a runtime stack of unlimited depth and the code segment. A set of
functions is provided for creating and destroying instances of Sieve
Machine, manipulating its internal data, compiling and executing a
sieve program.
The following is a typical scenario of using libmu_sieve:
mu_sieve_compile function is called to translate
the Sieve source into an equivalent program executable by the
Machine
keep are marked with the delete
flag. Thus, running mailbox_expunge upon the mailbox finishes
the job, leaving in the mailbox only those messages that were preserved
by the filter.
The following sections describe in detail the functions from the Sieve Library.
This is an opaque data type representing a pointer to an instance of
sieve machine. The sieve_machine_t keeps all information necessary
for compiling and executing the script.
It is created by sieve_machine_create() and destroyed by
sieve_machine_destroy(). The functions for manipulating this data
type are described in Manipulating the Sieve Machine.
This enumeration keeps the possible types of sieve data. These are:
SVT_VOIDNo datatype.
SVT_NUMBERNumeric type.
SVT_STRINGCharacter string.
SVT_STRING_LISTA mu_list_t. Each item in this list represents a character string.
SVT_TAGA sieve tag. See mu_sieve_runtime_tag_t below.
SVT_IDENTA character string representing an identifier.
SVT_VALUE_LISTA mu_list_t. Each item in this list is of mu_sieve_value_t type.
SVT_POINTERAn opaque pointer.
The mu_sieve_value_t keeps an instance of sieve data. It is defined
as follows:
typedef struct
{
mu_sieve_data_type type; /* Type of the data */
union {
char *string; /* String value or identifier */
size_t number; /* Numeric value */
mu_list_t list; /* List value */
mu_sieve_runtime_tag_t *tag; /* Tag value */
void *ptr; /* Pointer value */
} v;
}
mu_sieve_value_t;
|
Depending on the value of type member, following members of the
union v keep the actual value:
SVT_VOIDNever appears.
SVT_NUMBERThe numeric value is kept in number member.
SVT_STRINGThe string is kept in string member.
SVT_STRING_LISTSVT_VALUE_LISTThe list itself is pointed to by list member
SVT_TAGThe tag value is pointed to by tag member.
SVT_IDENTThe string member points to the identifier name.
SVT_POINTERThe data are pointed to by ptr member.
This structure represents a definition of a tagged (optional) argument to a sieve action or test. It is defined as follows:
typedef struct
{
char *name; /* Tag name */
mu_sieve_data_type argtype; /* Type of tag argument. */
}
mu_sieve_tag_def_t;
|
The name member points to the tag's name without leading
colon. The argtype is set to SVT_VOID if the tag does
not take argument, or to the type of the argument otherwise.
This structure represents the tagged (optional) argument at a runtime. It is defined as:
struct mu_sieve_runtime_tag
{
char *tag; /* Tag name */
mu_sieve_value_t *arg; /* Tag argument (if any) */
};
|
The arg member is NULL if the tag does not take an argument.
Objects of this type represent a location in the Sieve source file:
typedef struct
{
const char *source_file;
size_t source_line;
}
mu_sieve_locus_t;
|
This is a pointer to function handler for a sieve action or test. It is defined as follows:
typedef int (*mu_sieve_handler_t) (mu_sieve_machine_t mach,
mu_list_t args,
mu_list_t tags);
|
The arguments to the handler have the following meaning:
Sieve machine being processed.
A list of required arguments to the handler
A list of optional arguments (tags).
A pointer to a diagnostic output function. It is defined as follows:
typedef int (*mu_sieve_printf_t) (void *data,
const char *fmt, va_list ap);
|
A pointer to application specific data. These data are passed as
second argument to mu_sieve_machine_init().
Printf-like format string.
Other arguments.
This data type is declared as follows:
typedef int (*mu_sieve_parse_error_t) (void *data,
const char *filename,
int lineno,
const char *fmt,
va_list ap);
|
It is used to declare error handlers for parsing errors. The application-specific data are passed in the data argument. Arguments filename and line indicate the location of the error in the source text, while fmt and ap give verbose description of the error.
A pointer to the application-specific logging function:
typedef void (*mu_sieve_action_log_t) (void *data,
const mu_sieve_locus_t *locus,
size_t msgno,
mu_message_t msg,
const char *action,
const char *fmt,
va_list ap);
|
Application-specific data.
Location in the Sieve source file.
Name of the sieve script being executed.
Ordinal number of the message in mailbox, if appropriate. When execution
is started using sieve_message(), this argument is zero.
The message this action is executed upon.
The name of the action.
These two arguments give the detailed description of the action.
typedef int (*mu_sieve_relcmp_t) (int, int); typedef int (*mu_sieve_relcmpn_t) (size_t, size_t); |
typedef int (*mu_sieve_comparator_t) (const char *, const char *); |
A pointer to the comparator handler function. The function compares
its two operands and returns 1 if they are equal, and 0 otherwise.
Notice, that the sense of the return value is inverted
in comparison with most standard libc functions like stcmp(), etc.
typedef int (*mu_sieve_retrieve_t) (void *item, void *data, int idx,
char **pval);
|
A pointer to generic retriever function. See description of
mu_sieve_vlist_compare() for details of its usage.
typedef void (*mu_sieve_destructor_t) (void *data); |
A pointer to destructor function. The function frees any resources
associated with data. See the description of
mu_sieve_machine_add_destructor() for more information.
typedef int (*mu_sieve_tag_checker_t) (const char *name,
mu_list_t tags,
mu_list_t args)
|
A pointer to tag checker function. The purpose of the function is to perform compilation-time consistency test on tags. Its arguments are:
Name of the test or action whose tags are being checked.
A list of mu_sieve_runtime_tag_t representing tags.
A list of mu_sieve_value_t representing required arguments to
name.
The function is allowed to make any changes in tags and args. It should return 0 if the syntax is correct and non-zero otherwise. It is responsible for issuing the diagnostics in the latter case. [FIXME: describe how to do that]
This subsection describes functions used to create an instance of the sieve machine, read or alter its internal fields and destroy it.
The mu_sieve_machine_init() function creates an instance of a sieve
machine. A pointer to the instance itself is returned in the argument
mach. The user-specific data to be associated with the new machine
are passed in data argument. The function returns 0 on success,
non-zero error code otherwise,
This function destroys the instance of sieve machine pointed to by
mach parameter. After execution of mu_sieve_machine_destroy()
pmach contains NULL. The destructors registered with
mu_sieve_machine_add_destructor() are executed in LIFO
order.
This function registers a destructor function dest. The purpose
of the destructor is to free any resources associated with the item
ptr. The destructor function takes a single argument — a
pointer to the data being destroyed. All registered destructors are
called in reverse order upon execution of
mu_sieve_machine_destroy(). Here's a short example of the use
of this function:
static void
free_regex (void *data)
{
regfree ((regex_t*)data);
}
int
match_part_checker (const char *name, list_t tags, list_t args)
{
regex_t *regex;
/* Initialise the regex: */
regex = mu_sieve_malloc (mach, sizeof (*regex));
/* Make sure it will be freed when necessary */
mu_sieve_machine_add_destructor (sieve_machine, free_regex, regex);
.
.
.
}
|
This function returns the application-specific data associated with
the instance of sieve machine. See mu_sieve_machine_init().
This function returns the current message.
This function returns the current message number in the mailbox.
If there are no mailbox, i.e. the execution of the sieve code is started
with mu_sieve_message, this function returns 1.
Returns the debug level set for this instance of sieve machine.
Returns the authentication ticket for this machine.
Returns the mailer.
Returns the locus in the Sieve source file corresponding to the code pointer where the Sieve machine currently is.
This function returns the daemon email associated with this instance of sieve machine. The daemon email is an email address used in envelope from addresses of automatic reply messages. By default its local part is ‘<MAILER-DAEMON>’ and the domain part is the machine name.
This function sets the error printer function for the machine. If it is not set, the default error printer will be used. It is defined as follows:
int
_sieve_default_error_printer (void *unused, const char *fmt,
va_list ap)
{
return mu_verror (fmt, ap);
}
|
This function sets the parse error printer function for the machine. If it is not set, the default parse error printer will be used. It is defined as follows:
int
_sieve_default_parse_error (void *unused,
const char *filename, int lineno,
const char *fmt, va_list ap)
{
if (filename)
fprintf (stderr, "%s:%d: ", filename, lineno);
vfprintf (stderr, fmt, ap);
fprintf (stderr, "\n");
return 0;
}
|
This function sets the debug printer function for the machine. If it is
not set, the default debug printer is NULL which means no
debugging information will be displayed.
This function sets the debug level for the given instance of sieve
machine. The dbg argument is the mu_debug_t object to be
used with mailutils library, the level argument specifies the
debugging level for the sieve library itself. It is a bitwise or of
the following values:
MU_SIEVE_DEBUG_TRACETrace the execution of the sieve script.
MU_SIEVE_DEBUG_INSTR Print the sieve machine instructions as they are executed.
MU_SIEVE_DEBUG_DISASDump the disassembled code of the sieve machine. Do not run it.
MU_SIEVE_DRY_RUNDo not executed the actions, only show what would have been done.
This function sets the logger function. By default the logger function
is NULL, which means that the executed actions are not logged.
This function sets the authentication ticket to be used with this machine.
This function sets the mailer. The default mailer is "sendmail:".
This functions sets the daemon email for reject and
redirect actions.
The mu_sieve_is_dry_run() returns 1 if the machine is in dry
run state, i.e. it will only log the actions that would have been
executed without actually executing them. The dry run state is set
by calling mu_sieve_set_debug_level() if its last argument has
the MU_SIEVE_DRY_RUN bit set.
Returns the string representation for the given sieve data type. The return value is a pointer to a static constant string.
Format and output an error message using error printer of the machine mach.
Format and output a debug message using debug printer of the machine mach.
Log a sieve action using logger function associated with the machine mach.
Immediately abort the execution of the script.
Find a register object describing the test name. Returns
NULL if no such test exists.
Find a register object describing the action name. Returns
NULL if no such action exists.
The following functions act as their libc counterparts. The allocated
memory is associated with the mach argument and is automatically
freed upon the call to mu_sieve_machine_destroy (mach).
Allocates size bytes and returns a pointer to the allocated memory.
This function returns a pointer to a new string which is a duplicate of the string str.
Changes the size of the memory block pointed to by ptr to
size bytes. The contents will be unchanged to the minimum of the
old and new sizes; newly allocated memory will be uninitialized. If
ptr is NULL, the call is equivalent to
mu_sieve_malloc(mach, size); if size is equal to
zero, the call is equivalent to mu_sieve_mfree(ptr). Unless
ptr is NULL, it must have been returned by an earlier
call to mu_sieve_malloc() or mu_sieve_mrealloc().
mu_sieve_mfree() frees the memory space pointed to by ptr and
detaches it from the destructor list of mach. The ptr must
have been returned by a previous call to mu_sieve_malloc() or
mu_sieve_mrealloc(). Otherwise, or if mu_sieve_mfree(ptr)
has already been called before, undefined behaviour occurs.
If ptr is NULL, no operation is performed.
Compile the sieve script from the file name.
Execute the code from the given instance of sieve machine mach over each message in the mailbox mbox.
Execute the code from the given instance of sieve machine mach over the message.
Dump the disassembled code of the sieve machine mach.
This section contains an example of how to write external loadable commands for GNU libmu_sieve.
/* This is an example on how to write extension tests for GNU sieve.
It provides test "numaddr".
Syntax: numaddr [":over" / ":under"] <header-names: string-list>
<limit: number>
The "numaddr" test counts Internet addresses in structured headers
that contain addresses. It returns true if the total number of
addresses satisfies the requested relation:
If the argument is ":over" and the number of addresses is greater than
the number provided, the test is true; otherwise, it is false.
If the argument is ":under" and the number of addresses is less than
the number provided, the test is true; otherwise, it is false.
If the argument is empty, ":over" is assumed. */
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif
#include <stdlib.h>
#include <mailutils/sieve.h>
struct val_ctr { /* Data passed to the counter function */
mu_header_t hdr; /* Headers of the current message */
size_t limit; /* Limit for the number of addresses */
size_t count; /* Number of addresses counted so far */
};
/* Count addresses in a single header value.
Input:
ITEM is the name of the header to scan.
DATA is a pointer to the val_ctr structure
Return value:
non-zero if the limit on the number of addresses has been reached. */
static int
_count_items (void *item, void *data)
{
char *name = item;
struct val_ctr *vp = data;
char *val;
mu_address_t addr;
size_t count = 0;
if (mu_header_aget_value (vp->hdr, name, &val))
return 0;
if (mu_address_create (&addr, val) == 0)
{
mu_address_get_count (addr, &count);
mu_address_destroy (&addr);
vp->count += count;
}
free (val);
return vp->count >= vp->limit;
}
/* Handler for the numaddr test */
static int
numaddr_test (mu_sieve_machine_t mach, mu_list_t args, mu_list_t tags)
{
mu_sieve_value_t *h, *v;
struct val_ctr vc;
int rc;
if (mu_sieve_get_debug_level (mach) & MU_SIEVE_DEBUG_TRACE)
{
mu_sieve_locus_t locus;
mu_sieve_get_locus (mach, &locus);
mu_sieve_debug (mach, "%s:%lu: NUMADDR\n",
locus.source_file,
(unsigned long) locus.source_line);
}
/* Retrieve required arguments: */
/* First argument: list of header names */
h = mu_sieve_value_get (args, 0);
if (!h)
{
mu_sieve_error (mach, "numaddr: can't get argument 1");
mu_sieve_abort (mach);
}
/* Second argument: Limit on the number of addresses */
v = mu_sieve_value_get (args, 1);
if (!v)
{
mu_sieve_error (mach, "numaddr: can't get argument 2");
mu_sieve_abort (mach);
}
/* Fill in the val_ctr structure */
mu_message_get_header (mu_sieve_get_message (mach), &vc.hdr);
vc.count = 0;
vc.limit = v->v.number;
/* Count the addresses */
rc = mu_sieve_vlist_do (h, _count_items, &vc);
/* Here rc >= 1 iff the counted number of addresses is greater or equal
to vc.limit. If `:under' tag was given we reverse the return value */
if (mu_sieve_tag_lookup (tags, "under", NULL))
rc = !rc;
return rc;
}
/* Syntactic definitions for the numaddr test */
/* Required arguments: */
static mu_sieve_data_type numaddr_req_args[] = {
SVT_STRING_LIST,
SVT_NUMBER,
SVT_VOID
};
/* Tagged arguments: */
static mu_sieve_tag_def_t numaddr_tags[] = {
{ "over", SVT_VOID },
{ "under", SVT_VOID },
{ NULL }
};
static mu_sieve_tag_group_t numaddr_tag_groups[] = {
{ numaddr_tags, NULL },
{ NULL }
};
/* Initialization function. It is the only function exported from this
module. */
int
SIEVE_EXPORT(numaddr,init) (mu_sieve_machine_t mach)
{
return mu_sieve_register_test (mach, "numaddr", numaddr_test,
numaddr_req_args, numaddr_tag_groups, 1);
}
|
The input language understood by the GNU Sieve Library is a superset of the Sieve language as described in RFC 3028.
Comments are semantically equivalent to whitespace and can be used anyplace that whitespace is (with one exception in multi-line strings, as described below).
There are two kinds of comments: hash comments, that begin with a ‘#’ character that is not contained within a string and continue until the next newline, and C-style or bracketed comments, that are delimited by ‘/*’ and ‘*/’ tokens. The bracketed comments may span multiple lines. E.g.:
if size :over 100K
{ # this is a comment
discard;
}
if size :over 100K
{ /* this is a comment
this is still a comment */ discard /* this is a comment again
*/ ;
}
|
Like in C, bracketed comments do not nest.
The basic lexical entities are identifiers and literals.
An identifier is a sequence of letters, digits and underscores,
that begins with a letter or underscore. For example, header and
check_822_again are valid identifiers, whereas 1st is not.
A special form of identifier is tag: it is an identifier prefixed
with a colon (‘:’), e.g.: :comparator.
A literal is a data that is not executed, merely evaluated “as is”, to be used as arguments to commands. There are four kinds of literals:
Numbers are given as ordinary unsigned decimal numbers. An optional suffix may be used to indicate a multiple of a power of two. The suffixes are: ‘K’ specifying “kibi-”, or 1,024 (2^10) times the value of the number; ‘M’ specifying “mebi-”, or 1,048,576 (2^20) times the value of the number; and ‘G’ specifying “tebi-”, or 1,073,741,824 (2^30) times the value of the number.
The numbers have 32 bits of magnitude.
text: followed by a newline and ends with a dot
(‘.’) on a newline by itself. Any characters between these two
markers are taken verbatim. For example:
text: ** This is an automatic response from my message ** ** filtering program. ** I can not attend your message right now. However it will be saved, and I will read it as soon as I am back. Regards, Fred . |
Notice that a hashed comment or whitespace may occur between
text: and the newline. However, when used inside the multiline
string a hash sign looses its special meaning (except in one case, see
below) and is taken as is, as well as bracketed comment delimiters.
In other words, no comments are allowed within a multiline string. E.g.:
text: # This is a comment Sample text # This line is taken verbatim /* And this line too */ . |
The only exception to this rule is that preprocessor include
statement is expanded as usual when found within a multiline string
(see section Preprocessor), e.g.:
text: #include <myresponse.txt> . |
This results in the contents of file ‘myresponse.txt’ being read and interpreted as the contents of the multiline string.
GNU libmu_sieve extends the described syntax as follows. If the keyword
text: is immediately followed by a dash (‘-’), then all
leading tab characters are stripped from input lines and the line
containing delimiter (‘.’). This allows multiline strings within
scripts to be indented in a natural fashion.
Furthermore, if the text: (optionally followed by ‘-’) is
immediately followed by a word, this word will be used as ending
delimiter of multiline string instead of the default dot. For
example:
if header "from" "me@example.com"
{
reject text:-EOT
I do not accept messages from
this address.
.
.
EOT
# Notice that this the multiline string ends here.
# The single dots above will be part of it.
;
}
|
A string list is a comma-delimited list of quoted strings, enclosed in a pair of square brackets, e.g.:
["me@example.com", "me00@landru.example.edu"] |
For convenience, in any context where a list of strings is appropriate, a single string is allowed without being a member of a list: it is equivalent to a list with a single member. For example, the following two statements are equivalent:
exists "To"; exists ["To"]; |
Being designed for the sole purpose of filtering mail, Sieve has a very simple syntax.
The basic syntax element is a command. It is defined as follows:
command-name [tags] args |
where command-name is an identifier representing the name of the command, tags is an optional list of optional or tagged arguments and args is a list of required or positional arguments.
Positional arguments are literals delimited with whitespace. They provide the command with the information necessary to its proper functioning. Each command has a fixed number of positional arguments. It is an error to supply more arguments to the command or to give it fewer arguments than it accepts.
Optional arguments allow to modify the behaviour of the command, like command line options in UNIX do. They are a list of tags (see section Lexical Structure) separated by whitespace. An optional argument may have at most one parameter.
Each command understands a set of optional arguments. Supplying it tags that it does not understand results in an error.
For example, consider the following command
header :mime :comparator "i;octet" ["to", "from"] "bug-mailutils@gnu.org" |
Here, given that header takes two positional arguments:
header is command name, the list ["to", "from"] is first
positional argument and the string "bug-mailutils@gnu.org" is second
positional argument. There are two optional arguments: :mime and
:comparator. The latter has a string "i;octet" as its
parameter.
An action is a Sieve command that performs some operation over a message. Actions do the main job in any Sieve program. Syntactically, an action is a command terminated with semicolon, e.g.:
keep; fileinto "mbox"; |
GNU Sieve provides the full set of actions described in RFC 3028. It also allows to extend this set using loadable actions. See section Actions, for detailed discussion of actions.
The only control flow statement Sieve has is if statement. In its
simplest form it is:
if |
The effect of this statement is that the sequence of actions between the
curly braces is executed only if the condition evaluates to
true.
A more elaborate form of this statement allows to execute two different sets of actions depending on whether the condition is true or not:
if |
The most advanced form of the “if” statement allows to select an action depending on what condition from the set of conditions is met.
if |
There may be any number of “elsif” branches in an “if” statement. However it may have at most one “else” branch. Notes for C programmers:
Here's an example of “if” statement:
if header :contains "from" "coyote"
{
discard;
}
elsif header :contains ["subject"] ["$$$"]
{
discard;
}
else
{
fileinto "INBOX";
}
|
The following section describes in detail conditions used in “if” statements.
Tests are Sieve commands that return boolean value. E.g. the test
header :contains "from" "coyote" |
returns true only if the header “From” of the current message contains substring “coyote”.
The tests shipped with the GNU Sieve are described in Tests.
Condition is a Sieve expression that evaluates to true or
false. In its simplest form, condition is just a Sieve test.
To reverse the sense of a condition use keyword not, e.g.:
not header :contains "from" "coyote" |
The results of several conditions may be joined together by logical
and and or operations. The special form allof
takes several tests as its arguments and computes the logical and
of their results. Similarly, the form anyof performs logical
or over the results of its arguments. E.g.:
if anyof (not exists ["From", "Date"],
header :contains "from" "fool@example.edu")
{
discard;
}
|
Preprocessor statements are a GNU extension to the Sieve language.
The syntax for a preprocessor statement is similar to that used in
C programming language, i.e. a pound character (‘#’)
followed by a preprocessor directive and its arguments. Any amount of
whitespace can be inserted between the ‘#’ and the directive.
Currently implemented directives are include and searchpath.
The #include directive reads in the contents of the given file.
The contents is “inserted” into the text being parsed starting at the
line where the directive appears. The directive takes two forms:
#include "filename"The filename is taken relative to the current directory.
#include <filename>"The filename is searched in the list of include directories as specified by the ‘-I’ command line options.
If filename starts with a directory separator character (‘/’) both forms have the same effect.
The #searchpath directive adds its argument to the list of
directories searched for loadable modules. It has the same effect
as library-path Sieve configuration statement
(see library-path).
Syntax: require string;
require string-list;
|
The require statement informs the parser that a script makes use of a certain extension. Multiple capabilities can be declared using the second form of the statement. The actual handling of a capability name depends on its suffix.
If the name starts with ‘comparator-’, it is understood as a request to use the specified comparator. The comparator name consists of the characters following the suffix.
If the name starts with ‘test-’, it means a request to use the given test. The test name consists of the characters following the suffix.
Otherwise, the capability is understood as a name of an action to be used.
The require statement, if present, must be used before any other
statement that is using the required capability. As an extension, the GNU
sieve allows the require and any other statements to be
interspersed.
By default the following actions and comparators need not be explicitly required:
Example:
require ["fileinto", "reject"]; require "fileinto"; require "comparator-i;ascii-numeric"; |
When processing arguments for require statement, GNU libmu_sieve
uses the following algorithm:
#searchpath directive.
LTDL_LIBRARY_PATH.
LD_LIBRARY_PATH).
The value of LTDL_LIBRARY_PATH and LD_LIBRARY_PATH must be a
colon-separated list of absolute directories, for example,
‘"/usr/lib/mypkg:/lib/foo"’.
In any of these directories, libmu_sieve first attempts to find
and load the given filename. If this fails, it tries to append the
following suffixes to the file name:
libmu_sieve executes its
initialization function (see below) and again looks up the name
in the symbol table. If found, search terminates successfully.
libmu_sieve then
issues the following diagnostic message:
source for the required action NAME is not available |
GNU libmu_sieve supports the following built-in comparators:
i;octetThis comparator simply compares the two arguments octet by octet
i;ascii-casemapIt treats uppercase and lowercase characters in the ASCII subset of UTF-8 as the same. This is the default comparator.
i;ascii-numericTreats the two arguments as ASCII representation of decimal numbers and compares their numeric values. This comparator must be explicitly required prior to use.
This section describes the built-in tests supported by GNU libmu_sieve. In the discussion below the following macro-notations are used:
This tag specifies the matching type to be used with the test. It can be one of the following:
:isThe :is match type describes an absolute match; if the contents of
the first string are absolutely the same as the contents of the
second string, they match. Only the string “frobnitzm” is the string
“frobnitzm”. The null key “:is” and only “:is” the null value.
This is the default match-type.
:containsThe :contains match type describes a substring match. If the value
argument contains the key argument as a substring, the match is true.
For instance, the string “frobnitzm” contains “frob” and “nit”, but
not “fbm”. The null key “” is contained in all values.
:matchesThe :matches version specifies a wildcard match using the
characters ‘*’ and ‘?’. ‘*’ matches zero or more
characters, and ‘?’ matches a single character. ‘?’ and
‘*’ may be escaped as ‘\\?’ and ‘\\*’ in strings to match
against themselves. The first backslash escapes the second backslash;
together, they escape the ‘*’.
:regexThe :regex version specifies a match using POSIX Extended Regular
Expressions.
:value relationThe :value match type does a relational comparison between
strings. Valid values for relation are:
Equal
Not Equal
Greater Than
Greater than or Equal
Less Than
Less than or Equal
:count relationThis match type first determines the number of the specified entities (headers, addresses, etc.) in the message and does a relational comparison of the number of entities to the values specified in the test expression. The test expression must be a list of one element.
A comparator syntax item is defined as follows:
:comparator "comparator-name" |
It instructs sieve to use the given comparator with the test. If comparator-name is not one of ‘i;octet’, ‘i;ascii-casemap’ it must be required prior to using it. For example:
require "comparator-i;ascii-numeric";
if header :comparator "i;ascii-numeric" :is "X-Num" "10"
{
...
|
This syntax item is used when testing structured Internet addresses. It specifies which part of an address must be used in comparisons. Exactly one of the following tags may be used:
:allUse the whole address. This is the default.
:localpartUse local part of the address.
:domainUse domain part of the address.
Notice, that match-type modifiers interact with
comparators. Some comparators are not suitable for matching with
:contains or :matches. If this occurs, sieve issues
an appropriate error message. For example, the statement:
if header :matches :comparator "i;ascii-numeric" |
would result in the following error message:
comparator `i;ascii-numeric' is incompatible with match type `:matches' in call to `header' |
GNU Sieve supports two kinds of tests. Built-in tests are
defined within the library and do not require any external files.
External tests are loadable modules that can be linked in at run
time using the require statement (see section Require Statement).
This test always evaluates to “false”.
This test always evaluates to “true”.
Tagged arguments:
Selects the address part to compare. Default is the whole email address
(:all).
Specifies the comparator to be used instead of the default i;ascii-casemap.
Specifies the match type to be used instead of the default :is.
Required arguments:
A list of header names.
A list of address values.
The address test matches Internet addresses in structured headers
that contain addresses. It returns true if any header contains any
key in the specified part of the address, as modified by
comparator and match-type optional arguments.
This test returns true if any combination of the
header-names and key-list arguments match.
The address primitive never acts on the phrase part of an email
address, nor on comments within that address. Use the header test
instead. It also never acts on group names, although it does act on the
addresses within the group construct.
Example:
if address :is :all "from" "tim@example.com"
{
discard;
}
|
The size test deals with the size of a message. The required
argument limit represents the size of the message in bytes. It
may be suffixed with the following quantifiers:
The number is expressed in kilobytes.
The number is expressed in megabytes.
The number is expressed in gigabytes.
If the tagged argument is ‘:over’, and the size of the message is greater than number, the test is true; otherwise, it is false.
If the argument is ‘:under’, and the size of the message is less than the number, the test is true; otherwise, it is false.
Otherwise, the test is true only if the size of the message equals exactly number. This is a GNU extension.
The size of a message is defined to be the number of octets from the initial header until the last character in the message body.
Tagged arguments:
Selects the address part to compare. Default is the whole email address
(:all).
Specifies the comparator to be used instead of the default i;ascii-casemap.
Specifies the match type to be used instead of the default :is.
Required arguments:
A list of envelope parts to operate upon.
A list of address values.
The envelope test is true if the specified part of the SMTP
envelope matches the specified key.
If the envelope-part strings is (case insensitive) ‘from’,
then matching occurs against the FROM address used in the
SMTP MAIL command.
Notice, that due to the limitations imposed by SMTP envelope structure the use of any other values in envelope-parts header is meaningless.
Required arguments:
List of message header names.
The exists test is true if the headers listed in
header-names argument exist within the message. All of the headers
must exist or the test is false.
The following example throws out mail that doesn't have a From header and a Date header:
if not exists ["From","Date"]
{
discard;
}
|
Tagged arguments:
Specifies the comparator to be used instead of the default i;ascii-casemap.
Specifies the match type to be used instead of the default :is.
This tag instructs header to search through the mime headers in
multipart messages as well.
Required arguments:
A list of header names.
A list of header values.
The header test evaluates to true if any header name matches any
key. The type of match is specified by the optional match argument,
which defaults to ":is" if not explicitly given.
The test returns true if any combination of the header-names
and key-list arguments match.
If a header listed in header-names exists, it contains the null key (‘""’). However, if the named header is not present, it does not contain the null key. So if a message contained the header
X-Caffeine: C8H10N4O2 |
these tests on that header evaluate as follows:
header :is ["X-Caffeine"] [""] ⇒ false header :contains ["X-Caffeine"] [""] ⇒ true |
Synopsis:
require "test-numaddr";
…
if numaddr args
{
…
}
|
Description:
This test is provided as an example of loadable extension tests. You must use ‘require "test-numaddr"’ statement before actually using it.
The numaddr test counts Internet addresses in structured headers
that contain addresses. It returns true if the total number of
addresses satisfies the requested relation.
If the tagged argument is ‘:over’ and the number of addresses is greater than count, the test is true; otherwise, it is false.
If the tagged argument is ‘:under’ and the number of addresses is less than count, the test is true; otherwise, it is false.
If the tagged argument is not given, ‘:over’ is assumed.
Synopsis:
require "test-spamd";
…
if spamd args
{
# This is spam
…
}
|
Description:
This test is an interface to SpamAssassin filter. It connects to the
spamd daemon using connection parameters specified by tagged
arguments :host and :port (if the daemon is listening on
an INET socket), or :socket (if the daemon is listening on a
UNIX socket) and returns true, if SpamAssassin qualifies the message
as spam. Tagged argument limit alters the default behavior. Its
value is a string representation of a floating point number. If
the tag :over is used, then the test returns true if the spam
score returned from SpamAssassin is greater than limit.
Otherwise, if :under is used, the test returns true if the spam
score is less than limit. The comparison takes into account
three decimal digits.
Tagged argument :user allows to select a specific user profile.
If it is not given, the user name is determined using the effective
UID.
Before returning, the spamd test adds the following headers to
the message:
‘YES’ or ‘NO’, depending on whether the message is qualified as spam or ham.
Actual spam score value.
Spam score threshold, as configured in SpamAssassin settings.
Comma-separated list of keywords, describing the spam checks that succeeded for this message.
Example:
request "test-spamd";
if spamd :host 127.0.0.1 :port 3333
{
discard;
}
|
Synopsis:
require "test-list";
if list args
{
…
}
|
Description:
The list test evaluates to true if any of headers match any
key from keys. Each header is regarded as containing a list of
keywords. By default, comma is assumed as list separator. This can be
overridden by specifying the :delim tag, whose value is a
string consisting of valid list delimiter characters.
Example:
This test can be used in conjunction with the spamd test
described above:
require ["fileinto", "test-spamd", "test-list"];
if spamd :host 127.0.0.1 :port 3333
{
if list :matches :delim " ,"
"X-Spamd-Keywords" [ "HTML_*", "FORGED_*" ]
{
fileinto "~/mail/spam";
}
else
{
discard;
}
}
|
Synopsis:
require "test-timestamp";
if timestamp arg
{
…
}
|
Description:
The timestamp test compares the value of a structured date header
field (header) with the given date (date).
If the tagged argument is :after and the date from the header is
after the specified date the result is true, otherwise, if the header
date is before the given date, the result is false.
If the tagged argument is :before and the date from the header is
before the specified date the result is true, otherwise, if the header
date is after the given date, the result is false.
If no tagged argument is supplied, :after is assumed.
Almost any date format is understood. See section Date Input Formats, for a detailed information on date formats.
Example:
The test below succeeds if the date in ‘X-Expire-Timestamp’ header is more than 5 days older than the current date:
require "test-timestamp";
if timestamp :before "X-Expire-Timestamp" "now - 5 days"
{
discard;
}
|
There are two groups of GNU Sieve actions: built-in actions,
which are defined within the library, and external actions, i.e.
loadable modules that can be linked in at run time using the
require statement (see section Require Statement).
The GNU libmu_sieve supports the following built-in actions:
Among them the first three actions do not need to be explicitly required
by a require statement, while the others do.
These actions are described in detail below.
The stop action ends all processing. If no actions have been
executed, then the keep action is taken.
The effect of this action is to preserve the current message in the mailbox. This action is executed if no other action has been executed.
Discard silently throws away the current message. No notification
is returned to the sender, the message is deleted from the mailbox.
Example:
if header :contains ["from"] ["idiot@example.edu"]
{
discard;
}
|
Required arguments:
A string representing the folder name
Tagged arguments:
:permissions modeSpecifies the permissions to use, if the mailbox is created.
The fileinto action delivers the message into the specified
folder. If the folder is local, it is created using permissions
‘0600’, for regular files, and ‘0700’ for directories. This
default can be changed by using the :permissions tag. Its
argument is a mode specification, similar to that used by
chmod shell utility. It is a list of permissions settings
separated by commas. Each setting begins with one of the following
letters:
Set permissions for the users in the file group.
Set permissions for users not in the file's group.
This letter must be followed by either ‘+’ or ‘=’ and the list of permissions to be set. This latter list is a string containing any one or both of the following characters:
Grant permission to read.
Grant permission to write.
For example, the following instruction creates the mailbox ‘~/shared’ which will be world readable and writable for the group:
fileinto :permissions "g=rw,o=r" "~/shared" |
Notice that:
:permissions setting are affected by the current umask
value.
r and w permissions can be set, since other
permissions do not seem to be useful for mailboxes. However, for
mailboxes that have a directory structure (such as maildir and MH),
any settings in ‘g’ and ‘o’ sets imply setting the
executable bit.
:permissions settings apply only to local mailboxes. They
are ignored for remote mailboxes.
The optional reject action refuses delivery of a message by sending
back a message delivery notification to the sender. It resends the
message to the sender, wrapping it in a “reject” form, noting that it
was rejected by the recipient. The required argument reason is
a string specifying the reason for rejecting the message.
Example:
If the message contained
Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST) From: coyote@desert.example.org To: roadrunner@acme.example.com Subject: I have a present for you I've got some great birdseed over here at my place. Want to buy it? |
and the user's script contained:
if header :contains "from" "coyote@desert.example.org"
{
reject "I am not taking mail from you, and I don't want
your birdseed, either!";
}
|
then the original sender <coyote@desert.example.org> would receive the following notification:
To: <coyote@desert.example.org> X-Authentication-Warning: roadrunner set sender using -f flag Content-Type: multipart/mixed; boundary=----- =_aaaaaaaaaa0 MIME-Version: 1.0 ----- =_aaaaaaaaaa0 The original message was received at Tue, 1 Apr 1997 09:07:15 -0800 from coyote@desert.example.org. Message was refused by recipient's mail filtering program. Reason given was as follows: I am not taking mail from you, and I don't want your birdseed, either! ----- =_aaaaaaaaaa0 Content-Type: message/delivery-status Reporting-UA: sieve; GNU Mailutils 0.1.3 Arrival-Date: Tue, 1 Apr 1997 09:07:15 -0800 Final-Recipient: RFC822; roadrunner@acme.example.com Action: deleted Disposition: automatic-action/MDN-sent-automatically;deleted Last-Attempt-Date: Tue, 1 Apr 1997 09:07:15 -0800 ----- =_aaaaaaaaaa0 Content-Type: message/rfc822 From: coyote@desert.example.org To: roadrunner@acme.example.com Subject: I have a present for you I've got some great birdseed over here at my place. Want to buy it? ----- =_aaaaaaaaaa0 |
If the reason argument is rather long, the common approach is
to use the combination of the text: and #include keywords,
e.g.:
if header :mime :matches "Content-Type"
[ "*application/msword;*", "*audio/x-midi*" ]
{
reject text:
#include "nomsword.txt"
.
;
}
|
The redirect action is used to send the message to another user at
a supplied address, as a mail forwarding feature does. This action
makes no changes to the message body or existing headers, but it may add
new headers. It also modifies the envelope recipient.
The redirect command performs an MTA-style “forward” — that
is, what you get from a ‘.forward’ file using sendmail under
UNIX. The address on the SMTP envelope is replaced with the one on
the redirect command and the message is sent back
out. Notice, that it differs from the MUA-style forward, which
creates a new message with a different sender and message ID, wrapping
the old message in a new one.
(The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised.)
GNU Mailutils is shipped with a set of external Sieve actions. These actions are compiled as loadable modules and must be required prior to use (see section Require Statement).
Synopsis:
require "moderator" moderator args; |
Description:
This action is a moderator robot for Mailman-driven mail archives. A Mailman moderation request is a MIME message consisting of the following three parts:
| N | Content-Type | Description |
|---|---|---|
| 1 | text/plain | Introduction for the human reader. |
| 2 | message/rfc822 | Original submission. |
| 3 | message/rfc822 | Mailman control message. |
Replying to part 3 (keeping the subject intact) instructs Mailman to discard the original submission.
Replying to part 3 while adding an `Approved:' header with the list password in it approves the submission.
The moderator action spawns an inferior Sieve machine and
filters the original submission (part 2) through it. If the inferior
machine marks the message as deleted, the action replies to the
control message, thereby causing the submission to be discarded. The
‘From:’ address of the reply can be modified using
:address tag. After discarding the message, moderator
marks it as deleted, unless it is given :keep tag.
The argument of :source tag, if given, specifies the Sieve
source file to be used on the message. If :tag is not present,
moderator will create and use a copy of the existing Sieve machine.
The action checks the message structure: it will bail out if the message does not have exactly 3 MIME parts, or if parts 2 and 3 are not of ‘message/rfc822’ type. It is the responsibility of the caller to make sure the message is actually a valid Mailman moderation request (see the example below).
Example:
if allof(header :is "Sender" "mailman-bounces@gnu.org",
header :is "X-List-Administrivia" "yes")
{
moderator :source "~/.sieve/mailman.sv";
}
|
Synopsis:
require "pipe";
if pipe args
{
…
}
|
Description:
The pipe action sends executes a command specified by its
argument and sends the entire message to its standard input. The
command argument supplies the command line.
The envelope of the message is included, if the :envelope tag
is given.
Example:
The example below uses the maidag utility
(see section maidag) to forward the message to user ‘gray’ on
the machine ‘mail.gnu.org’.
require "pipe"; pipe "/usr/sbin/maidag --url smtp://gray@mail.gnu.org" |
Syntax:
require "vacation"; vacation args; |
Description:
The vacation action returns a message with reply-text to
the sender. It is intended to inform the sender that the recipient is
not currently reading his mail.
If the :subject tag is given, its argument sets the subject of
the message. Otherwise, the subject is formed by prefixing original
subject with ‘Re:’, or prefix, given with the
:reply_prefix tag. Before prefixing, any original prefixes
matching extended regular expression expr (:reply_regex
tag) are stripped from the subject line. If :reply_regex is not
specified, the default regexp is ‘^re: *’.
The :aliases tag instructs vacation to handle messages
for any address in addrlist in the same manner as those received
for the user's principal email.
Before processing, vacation compares the sender address with
its address exclusion list. Elements of this list are extended
case-insensitive regular expressions. If the sender address matches
any of these expressions, the message will not be replied. The default
exclusion list is:
.*-REQUEST@.*
.*-RELAY@.*
.*-OWNER@.*
^OWNER-.*
^postmaster@.*
^UUCP@.*
^MAILER@.*
^MAILER-DAEMON@.*
|
New entries can be added to this list using :addresses tag.
The :days tag sets the reply interval. A reply is sent to
each sender once in ndays days. GNU Sieve keeps track of
sender addresses and dates in a DBM file ‘.vacation’ stored in
the user's home directory. This tag is available only if Mailutils is
compiled with DBM support.
This section summarizes the GNU extensions to the sieve language
GNU libmu_sieve understands the following multiline string syntax:
text:[-][delimiter] .... delimiter |
The meaning of optional flags is the same as in shell “here document” construct: the dash strips all leading tab characters from the string body, thus allowing it to be indented in a natural fashion; delimiter introduces the new end-of-text delimiter instead of the default dot. If delimiter starts with a backslash, no preprocessing will be performed within a string.
require statement.
require appears
after a command other than require. The GNU sieve library allows
interspersing the require and other statements. The only
requirement is that require must occur before a statement that is
using the required capability (see section Require Statement).
header test
The header takes an optional argument :mime, meaning to
scan the headers from each part of a multipart message.
size test
The size test allows to omit the optional argument
(:over|:under). In this case exact equality is assumed.
envelope test
The only value that can be meaningfully used as the first required
argument of an envelope test is ‘from’. This limitation
may disappear from the subsequent releases.
fileinto action
The fileinto action allows to specify permissions on the mailbox,
in case it is created (see fileinto).
Along with the usual :is, :matches and contains
matching type, GNU sieve library understands :regex type. This
matching type toggles POSIX Extended Regular Expression matching.
Email bug reports to bug-mailutils@gnu.org.
As the purpose of bug reporting is to improve software, please be sure to include maximum information when reporting a bug. The information needed is:
The archives of bug-mailutils mailing list are available from http://mail.gnu.org/mailman/listinfo/bug-mailutils.
The two places to look for any news regarding GNU Mailutils are the Mailutils homepage at http://www.gnu.org/software/mailutils, and the project page at http://savannah.gnu.org/projects/mailutils.
The updated versions of this manual are available online from http://www.gnu.org/software/mailutils/manual.
In no particular order,
First, a quote:
Our units of temporal measurement, from seconds on up to months, are so complicated, asymmetrical and disjunctive so as to make coherent mental reckoning in time all but impossible. Indeed, had some tyrannical god contrived to enslave our minds to time, to make it all but impossible for us to escape subjection to sodden routines and unpleasant surprises, he could hardly have done better than handing down our present system. It is like a set of trapezoidal building blocks, with no vertical or horizontal surfaces, like a language in which the simplest thought demands ornate constructions, useless particles and lengthy circumlocutions. Unlike the more successful patterns of language and science, which enable us to face experience boldly or at least level-headedly, our system of temporal calculation silently and persistently encourages our terror of time.
… It is as though architects had to measure length in feet, width in meters and height in ells; as though basic instruction manuals demanded a knowledge of five different languages. It is no wonder then that we often look into our own immediate past or future, last Tuesday or a week from Sunday, with feelings of helpless confusion. …
— Robert Grudin, Time and the Art of Living.
This section describes the textual date representations that GNU
programs accept. These are the strings you, as a user, can supply as
arguments to the various programs. The C interface (via the
get_date function) is not described here.
A date is a string, possibly empty, containing many items separated by whitespace. The whitespace may be omitted when no ambiguity arises. The empty string means the beginning of today (i.e., midnight). Order of the items is immaterial. A date string may contain many flavors of items:
We describe each of these item types in turn, below.
A few ordinal numbers may be written out in words in some contexts. This is most useful for specifying day of the week items or relative items (see below). Among the most commonly used ordinal numbers, the word ‘last’ stands for -1, ‘this’ stands for 0, and ‘first’ and ‘next’ both stand for 1. Because the word ‘second’ stands for the unit of time there is no way to write the ordinal number 2, but for convenience ‘third’ stands for 3, ‘fourth’ for 4, ‘fifth’ for 5, ‘sixth’ for 6, ‘seventh’ for 7, ‘eighth’ for 8, ‘ninth’ for 9, ‘tenth’ for 10, ‘eleventh’ for 11 and ‘twelfth’ for 12.
When a month is written this way, it is still considered to be written numerically, instead of being “spelled in full”; this changes the allowed strings.
In the current implementation, only English is supported for words and abbreviations like ‘AM’, ‘DST’, ‘EST’, ‘first’, ‘January’, ‘Sunday’, ‘tomorrow’, and ‘year’.
The output of the date command
is not always acceptable as a date string,
not only because of the language problem, but also because there is no
standard meaning for time zone items like ‘IST’. When using
date to generate a date string intended to be parsed later,
specify a date format that is independent of language and that does not
use time zone items other than ‘UTC’ and ‘Z’. Here are some
ways to do this:
$ LC_ALL=C TZ=UTC0 date Mon Mar 1 00:21:42 UTC 2004 $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ' 2004-03-01 00:21:42Z $ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension. 2004-02-29 16:21:42,692722128-0800 $ date --rfc-2822 # a GNU extension Sun, 29 Feb 2004 16:21:42 -0800 $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension. 2004-02-29 16:21:42 -0800 $ date +'@%s.%N' # %s and %N are GNU extensions. @1078100502.692722128 |
Alphabetic case is completely ignored in dates. Comments may be introduced between round parentheses, as long as included parentheses are properly nested. Hyphens not followed by a digit are currently ignored. Leading zeros on numbers are ignored.
Invalid dates like ‘2005-02-29’ or times like ‘24:00’ are rejected. In the typical case of a host that does not support leap seconds, a time like ‘23:59:60’ is rejected even if it corresponds to a valid leap second.
A calendar date item specifies a day of the year. It is specified differently, depending on whether the month is specified numerically or literally. All these strings specify the same calendar date:
1972-09-24 # ISO 8601.
72-9-24 # Assume 19xx for 69 through 99,
# 20xx for 00 through 68.
72-09-24 # Leading zeros are ignored.
9/24/72 # Common U.S. writing.
24 September 1972
24 Sept 72 # September has a special abbreviation.
24 Sep 72 # Three-letter abbreviations always allowed.
Sep 24, 1972
24-sep-72
24sep72
|
The year can also be omitted. In this case, the last specified year is used, or the current year if none. For example:
9/24 sep 24 |
Here are the rules.
For numeric months, the ISO 8601 format ‘year-month-day’ is allowed, where year is any positive number, month is a number between 01 and 12, and day is a number between 01 and 31. A leading zero must be present if a number is less than ten. If year is 68 or smaller, then 2000 is added to it; otherwise, if year is less than 100, then 1900 is added to it. The construct ‘month/day/year’, popular in the United States, is accepted. Also ‘month/day’, omitting the year.
Literal months may be spelled out in full: ‘January’, ‘February’, ‘March’, ‘April’, ‘May’, ‘June’, ‘July’, ‘August’, ‘September’, ‘October’, ‘November’ or ‘December’. Literal months may be abbreviated to their first three letters, possibly followed by an abbreviating dot. It is also permitted to write ‘Sept’ instead of ‘September’.
When months are written literally, the calendar date may be given as any of the following:
day month year day month month day year day-month-year |
Or, omitting the year:
month day |
A time of day item in date strings specifies the time on a given day. Here are some examples, all of which represent the same time:
20:02:00.000000 20:02 8:02pm 20:02-0500 # In EST (U.S. Eastern Standard Time). |
More generally, the time of day may be given as ‘hour:minute:second’, where hour is a number between 0 and 23, minute is a number between 0 and 59, and second is a number between 0 and 59 possibly followed by ‘.’ or ‘,’ and a fraction containing one or more digits. Alternatively, ‘:second’ can be omitted, in which case it is taken to be zero. On the rare hosts that support leap seconds, second may be 60.
If the time is followed by ‘am’ or ‘pm’ (or ‘a.m.’ or ‘p.m.’), hour is restricted to run from 1 to 12, and ‘:minute’ may be omitted (taken to be zero). ‘am’ indicates the first half of the day, ‘pm’ indicates the second half of the day. In this notation, 12 is the predecessor of 1: midnight is ‘12am’ while noon is ‘12pm’. (This is the zero-oriented interpretation of ‘12am’ and ‘12pm’, as opposed to the old tradition derived from Latin which uses ‘12m’ for noon and ‘12pm’ for midnight.)
The time may alternatively be followed by a time zone correction, expressed as ‘shhmm’, where s is ‘+’ or ‘-’, hh is a number of zone hours and mm is a number of zone minutes. The zone minutes term, mm, may be omitted, in which case the one- or two-digit correction is interpreted as a number of hours. You can also separate hh from mm with a colon. When a time zone correction is given this way, it forces interpretation of the time relative to Coordinated Universal Time (UTC), overriding any previous specification for the time zone or the local time zone. For example, ‘+0530’ and ‘+05:30’ both stand for the time zone 5.5 hours ahead of UTC (e.g., India). This is the best way to specify a time zone correction by fractional parts of an hour. The maximum zone correction is 24 hours.
Either ‘am’/‘pm’ or a time zone correction may be specified, but not both.
A time zone item specifies an international time zone, indicated by a small set of letters, e.g., ‘UTC’ or ‘Z’ for Coordinated Universal Time. Any included periods are ignored. By following a non-daylight-saving time zone by the string ‘DST’ in a separate word (that is, separated by some white space), the corresponding daylight saving time zone may be specified. Alternatively, a non-daylight-saving time zone can be followed by a time zone correction, to add the two values. This is normally done only for ‘UTC’; for example, ‘UTC+05:30’ is equivalent to ‘+05:30’.
Time zone items other than ‘UTC’ and ‘Z’ are obsolescent and are not recommended, because they are ambiguous; for example, ‘EST’ has a different meaning in Australia than in the United States. Instead, it's better to use unambiguous numeric time zone corrections like ‘-0500’, as described in the previous section.
If neither a time zone item nor a time zone correction is supplied, time stamps are interpreted using the rules of the default time zone (see section Specifying time zone rules).
The explicit mention of a day of the week will forward the date (only if necessary) to reach that day of the week in the future.
Days of the week may be spelled out in full: ‘Sunday’, ‘Monday’, ‘Tuesday’, ‘Wednesday’, ‘Thursday’, ‘Friday’ or ‘Saturday’. Days may be abbreviated to their first three letters, optionally followed by a period. The special abbreviations ‘Tues’ for ‘Tuesday’, ‘Wednes’ for ‘Wednesday’ and ‘Thur’ or ‘Thurs’ for ‘Thursday’ are also allowed.
A number may precede a day of the week item to move forward supplementary weeks. It is best used in expression like ‘third monday’. In this context, ‘last day’ or ‘next day’ is also acceptable; they move one week before or after the day that day by itself would represent.
A comma following a day of the week item is ignored.
Relative items adjust a date (or the current date if none) forward or backward. The effects of relative items accumulate. Here are some examples:
1 year 1 year ago 3 years 2 days |
The unit of time displacement may be selected by the string ‘year’ or ‘month’ for moving by whole years or months. These are fuzzy units, as years and months are not all of equal duration. More precise units are ‘fortnight’ which is worth 14 days, ‘week’ worth 7 days, ‘day’ worth 24 hours, ‘hour’ worth 60 minutes, ‘minute’ or ‘min’ worth 60 seconds, and ‘second’ or ‘sec’ worth one second. An ‘s’ suffix on these units is accepted and ignored.
The unit of time may be preceded by a multiplier, given as an optionally signed number. Unsigned numbers are taken as positively signed. No number at all implies 1 for a multiplier. Following a relative item by the string ‘ago’ is equivalent to preceding the unit by a multiplier with value -1.
The string ‘tomorrow’ is worth one day in the future (equivalent to ‘day’), the string ‘yesterday’ is worth one day in the past (equivalent to ‘day ago’).
The strings ‘now’ or ‘today’ are relative items corresponding to zero-valued time displacement, these strings come from the fact a zero-valued time displacement represents the current time when not otherwise changed by previous items. They may be used to stress other items, like in ‘12:00 today’. The string ‘this’ also has the meaning of a zero-valued time displacement, but is preferred in date strings like ‘this thursday’.
When a relative item causes the resulting date to cross a boundary where the clocks were adjusted, typically for daylight saving time, the resulting date and time are adjusted accordingly.
The fuzz in units can cause problems with relative items. For example, ‘2003-07-31 -1 month’ might evaluate to 2003-07-01, because 2003-06-31 is an invalid date. To determine the previous month more reliably, you can ask for the month before the 15th of the current month. For example:
$ date -R Thu, 31 Jul 2003 13:02:39 -0700 $ date --date='-1 month' +'Last month was %B?' Last month was July? $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!' Last month was June! |
Also, take care when manipulating dates around clock changes such as
daylight saving leaps. In a few cases these have added or subtracted
as much as 24 hours from the clock, so it is often wise to adopt
universal time by setting the TZ environment variable to
‘UTC0’ before embarking on calendrical calculations.
The precise interpretation of a pure decimal number depends on the context in the date string.
If the decimal number is of the form yyyymmdd and no other calendar date item (see section Calendar date items) appears before it in the date string, then yyyy is read as the year, mm as the month number and dd as the day of the month, for the specified calendar date.
If the decimal number is of the form hhmm and no other time of day item appears before it in the date string, then hh is read as the hour of the day and mm as the minute of the hour, for the specified time of day. mm can also be omitted.
If both a calendar date and a time of day appear to the left of a number in the date string, but no relative item, then the number overrides the year.
If you precede a number with ‘@’, it represents an internal time stamp as a count of seconds. The number can contain an internal decimal point (either ‘.’ or ‘,’); any excess precision not supported by the internal representation is truncated toward minus infinity. Such a number cannot be combined with any other date item, as it specifies a complete time stamp.
Internally, computer times are represented as a count of seconds since an epoch—a well-defined point of time. On GNU and POSIX systems, the epoch is 1970-01-01 00:00:00 UTC, so ‘@0’ represents this time, ‘@1’ represents 1970-01-01 00:00:01 UTC, and so forth. GNU and most other POSIX-compliant systems support such times as an extension to POSIX, using negative counts, so that ‘@-1’ represents 1969-12-31 23:59:59 UTC.
Traditional Unix systems count seconds with 32-bit two's-complement integers and can represent times from 1901-12-13 20:45:52 through 2038-01-19 03:14:07 UTC. More modern systems use 64-bit counts of seconds with nanosecond subcounts, and can represent all the times in the known lifetime of the universe to a resolution of 1 nanosecond.
On most hosts, these counts ignore the presence of leap seconds. For example, on most hosts ‘@915148799’ represents 1998-12-31 23:59:59 UTC, ‘@915148800’ represents 1999-01-01 00:00:00 UTC, and there is no way to represent the intervening leap second 1998-12-31 23:59:60 UTC.
Normally, dates are interpreted using the rules of the current time
zone, which in turn are specified by the TZ environment
variable, or by a system default if TZ is not set. To specify a
different set of default time zone rules that apply just to one date,
start the date with a string of the form ‘TZ="rule"’. The
two quote characters (‘"’) must be present in the date, and any
quotes or backslashes within rule must be escaped by a
backslash.
For example, with the GNU date command you can
answer the question “What time is it in New York when a Paris clock
shows 6:30am on October 31, 2004?” by using a date beginning with
‘TZ="Europe/Paris"’ as shown in the following shell transcript:
$ export TZ="America/New_York" $ date --date='TZ="Europe/Paris" 2004-10-31 06:30' Sun Oct 31 01:30:00 EDT 2004 |
In this example, the ‘--date’ operand begins with its own
TZ setting, so the rest of that operand is processed according
to ‘Europe/Paris’ rules, treating the string ‘2004-10-31
06:30’ as if it were in Paris. However, since the output of the
date command is processed according to the overall time zone
rules, it uses New York time. (Paris was normally six hours ahead of
New York in 2004, but this example refers to a brief Halloween period
when the gap was five hours.)
A TZ value is a rule that typically names a location in the
‘tz’ database.
A recent catalog of location names appears in the
TWiki Date and Time Gateway. A few non-GNU hosts require a colon before a
location name in a TZ setting, e.g.,
‘TZ=":America/New_York"’.
The ‘tz’ database includes a wide variety of locations ranging
from ‘Arctic/Longyearbyen’ to ‘Antarctica/South_Pole’, but
if you are at sea and have your own private time zone, or if you are
using a non-GNU host that does not support the ‘tz’
database, you may need to use a POSIX rule instead. Simple
POSIX rules like ‘UTC0’ specify a time zone without
daylight saving time; other rules can specify simple daylight saving
regimes. See (libc)TZ Variable section `Specifying the Time Zone with TZ' in The GNU C Library.
get_date get_date was originally implemented by Steven M. Bellovin
(smb@research.att.com) while at the University of North Carolina
at Chapel Hill. The code was later tweaked by a couple of people on
Usenet, then completely overhauled by Rich $alz (rsalz@bbn.com)
and Jim Berets (jberets@bbn.com) in August, 1990. Various
revisions for the GNU system were made by David MacKenzie, Jim Meyering,
Paul Eggert and others.
This chapter was originally produced by François Pinard (pinard@iro.umontreal.ca) from the ‘getdate.y’ source code, and then edited by K. Berry (kb@cs.umb.edu).
Running prog --help displays the short usage summary
for prog utility (see section Options That are Common for All Utilities.). This summary is
organized by groups of semantically close options. The options
within each group are printed in the following order: a short option,
eventually followed by a list of corresponding long option names,
followed by a short description of the option. For example, here is an
excerpt from the actual sieve --help output:
-c, --compile-only Compile script and exit -d, --debug[=FLAGS] Debug flags -e, --email=ADDRESS Override user email address
The exact visual representation of the help output is configurable via
ARGP_HELP_FMT environment variable. The value of this variable
is a comma-separated list of format variable assignments. There
are two kinds of format variables. An offset variable keeps the
offset of some part of help output text from the leftmost column on
the screen. A boolean variable is a flag that toggles some
output feature on or off. Depending on the type of the corresponding
variable, there are two kinds of assignments:
The assignment to an offset variable has the following syntax:
variable=value |
where variable is the variable name, and value is a numeric value to be assigned to the variable.
To assign true value to a variable, simply put this variable name. To
assign false value, prefix the variable name with ‘no-’. For
example:
# Assign |
Following variables are declared:
If true, arguments for an option are shown with both short and long options, even when a given option has both forms, for example:
-e ADDRESS, --email=ADDRESS Override user email address |
If false, then if an option has both short and long forms, the argument is only shown with the long one, for example:
-e, --email=ADDRESS Override user email address |
and a message indicating that the argument is applicable to both
forms is printed below the options. This message can be disabled
using dup-args-note (see below).
The default is false.
If this variable is true, which is the default, the following notice is displayed at the end of the help output:
Mandatory or optional arguments to long options are also mandatory or optional for any corresponding short options.
Setting no-dup-args-note inhibits this message. Normally, only
one of variables dup-args or dup-args-note should be set.
Column in which short options start. Default is 2.
$ sieve --help|grep ADDRESS
-e, --email=ADDRESS Override user email address
$ ARGP_HELP_FMT=short-opt-col=6 sieve --help|grep ARCHIVE
-e, --email=ADDRESS Override user email address
|
Column in which long options start. Default is 6. For example:
$ sieve --help|grep ADDRESS -e, --email=ADDRESS Override user email address $ ARGP_HELP_FMT=long-opt-col=16 sieve --help|grep ADDRESS -e, --email=ADDRESS Override user email address |
Column in which doc options start. A doc option isn't actually
an option, but rather an arbitrary piece of documentation that is
displayed in much the same manner as the options. For example, in
the output of folder --help:
Usage: folder [OPTION...] [action] [msg]
GNU MH folder
Actions are:
--list List the contents of the folder stack
...
the string ‘Actions are:’ is a doc option. Thus, if you set ARGP_HELP_FMT=doc-opt-col=6 the above part of the help output will look as follows:
Usage: folder [OPTION...] [action] [msg]
GNU MH folder
Actions are:
--list List the contents of the folder stack
...
Column in which option description starts. Default is 29.
$ sieve --help|grep ADDRESS
-e, --email=ADDRESS Override user email address
$ ARGP_HELP_FMT=opt-doc-col=19 sieve --help|grep ADDRESS
-e, --email=ADDRESS Override user email address
$ ARGP_HELP_FMT=opt-doc-col=9 sieve --help|grep -i ADDRESS
-e, --email=ADDRESS
Override user email address
|
Notice, that the description starts on a separate line if
opt-doc-col value is too small.
Column in which group headers are printed. A group header is a descriptive text preceding an option group. For example, in the following text:
Sieve options
-I, --includedir=DIR Append directory DIR to the
list of include directories
the text ‘Sieve options’ is a group header.
The default value is 1.
Indentation of wrapped usage lines. Affects ‘--usage’ output. Default is 12.
Right margin of the text output. Used for wrapping.
Version 1.2, November 2002
Copyright © 2000, 2001, 2002, 2010 Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. |
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. |
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this:
with the Invariant Sections being list their titles, with
the Front-Cover Texts being list, and with the Back-Cover Texts
being list.
|
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
This is an alphabetical list of all Mailutils functions.
| Jump to: | A B C D E F G H I K L M N O P Q R S T U V W Y |
|---|
| Jump to: | A B C D E F G H I K L M N O P Q R S T U V W Y |
|---|
| Jump to: | A B C D E F H I K L M N O P Q R S T U V X |
|---|
| Jump to: | A B C D E F H I K L M N O P Q R S T U V X |
|---|
| Jump to: | !
#
:
=
?
|
~
A B C D E F G H I K L M N O P Q R S T U V W X Z |
|---|
| Jump to: | !
#
:
=
?
|
~
A B C D E F G H I K L M N O P Q R S T U V W X Z |
|---|
| Jump to: | C F G I M P R S |
|---|
| Jump to: | C F G I M P R S |
|---|
This is a general index of all issues discussed in this manual
| Jump to: | A B C D E F G H I L M N O P Q R S T U |
|---|
| Jump to: | A B C D E F G H I L M N O P Q R S T U |
|---|
Rmail does not use this feature
The exact location is determined at
configuration time by setting environment variable
DEFAULT_CUPS_CONFDIR. On most sites running
./configure DEFAULT_CUPS_CONFDIR=/etc/cups |
should be recommended.
This document was generated by Sergey Poznyakoff on December, 14 2010 using texi2html 1.78.
The buttons in the navigation panels have the following meaning:
| Button | Name | Go to | From 1.2.3 go to |
|---|---|---|---|
 |
Back | Previous section in reading order | 1.2.2 |
 |
Forward | Next section in reading order | 1.2.4 |
 |
FastBack | Beginning of this chapter or previous chapter | 1 |
 |
Up | Up section | 1.2 |
 |
FastForward | Next chapter | 2 |
 |
Contents | Table of contents | |
 |
Index | Index | |
| [ ? ] | About | About (help) |
where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.