START-INFO-DIR-ENTRY
* mailutils: (mailutils). API for mailboxes and mail protocols
END-INFO-DIR-ENTRY
START-INFO-DIR-ENTRY
* comsatd: (mailutils)comsatd. Comsat daemon
* frm: (mailutils)frm. List headers from a mailbox
* guimb: (mailutils)guimb. Mailbox scanning and processing language
* imap4d: (mailutils)imap4d. IMAP4 daemon
* mail.local: (mailutils)mail.local. Deliver mail to the local mailbox
* mail: (mailutils)mail. Send and receive mail
* messages: (mailutils)messages. Count the number of messages in a mailbox
* pop3d: (mailutils)pop3d. POP3 daemon
* readmsg: (mailutils)readmsg. Extract messages from a folder
* sieve: (mailutils)sieve. Mail filtering utility
* mailutils-config: (mailutils)mailutils-config. Get the information about the Mailutils build.
END-INFO-DIR-ENTRY
This file documents Mailutils, library API.
Published by the Free Software Foundation, 59 Temple Place - Suite
330 Boston, MA 02111-1307, USA
Copyright 1999, 2000 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.
...Short Contents...
This document was produced for version 0.2 of GNU Mailutils.
Introduction
************
GNU Mailutils offers a general purpose library whose aim is to
provide a rich set of functions for accessing different mailbox formats
and mailers.
References
==========
For more information on,
* SMTP
- `RFC 2821: Simple Mail Transfer Protocol'
- `RFC 2368: The mailto URL scheme'
* POP3
- `RFC 1939: Post Office Protocol - Version 3'
- `RFC 1734: POP3 AUTHentication command'
- `RFC 1957: Some Observations on Implementations of the Post
Office Protocol (POP3)'
- `RFC 2449: POP3 Extension Mechanism'
- `RFC 2384: POP URL Scheme'
* IMAP4
- `RFC 2060: INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1'
- `RFC 2088: IMAP4 non-synchronizing literals'
- `RFC 2193: IMAP4 Mailbox Referrals'
- `RFC 2221: IMAP4 Login Referrals'
- `RFC 2342: IMAP4 Namespace'
- `RFC 2192: IMAP URL Scheme'
- `RFC 1731: IMAP4 Authentication Mechanisms'
- `RFC 2245: Anonymous SASL Mechanism'
* message formats
- `RFC 2822: Internet Message Format'
- `RFC 2045: Multipurpose Internet Mail Extensions (MIME) Part
One: Format of Internet Message Bodies'
- `RFC 2046: Multipurpose Internet Mail Extensions (MIME) Part
Two: Media Types'
- `RFC 2047: Multipurpose Internet Mail Extensions (MIME) Part
Three: Message Header Extensions for Non-ASCII Text'
- `RFC 2049: Multipurpose Internet Mail Extensions (MIME) Part
Five: Conformance Criteria and Examples'
- `RFC 2111: Content-ID and Message-ID Uniform Resource
Locators'
* miscellaneous related topics
- `RFC 3028: Sieve: A Mail Filtering Language'
- `RFC 2298: An Extensible Message Format for Message
Disposition Notifications'
- `RFC 1738: Uniform Resource Locators (URL)'
- `Internet Email Protocols: A Developer's Guide, by Kevin
Johnson'
Framework
*********
Wherever the mail is and whatever format it is stored in, it is
operated upon using the same set of functions. To unified the C API,
GNU Mailutils offers a heteroclite set of objects that work in
aggregation to do operations on emails. Each object does a specific
task and delegates non-related tasks to others. The object comes alive
by specifying a _URL_ parameter when created, it will indicate the
storage format or protocol (POP3, IMAP4, MH, MAILDIR, etc ..).
folder_t url_t
-/var/mail- +- .. ->+-----------------+ +-->+------------+
( alain *-)-+ | | url_t *-|---+ | port |
----------- | | |-----------------| | hostname |
( jakob *-)-+--+ | auth_t *-|---+ | file |
----------- | |-----------------| | | ... |
( jeff *-)-+ | stream_t | | +------------+
----------- | |-----------------| |
( shaleh*-)-+ | ..... | | auth_t
---------- |-----------------| +-->+------------+
+---|-* mailbox_t[] | | ticket_t |
mailbox_t | +-----------------+ +------------+
+----------------+<-+
| locker_t *--|-------------+
|----------------| |
| url_t | | locker_t
|----------------| +-------->+---------+
| stream_t | | lock |
|----------------| | unlock |
| message_t[] *-|-------+ +---------+
+----------------+ | envelope_t
| +-------->+-----------+
message_t | | | date |
+----------------+<------+ | | from |
| envelope_t *-|------------------+ | to |
|----------------| header_t +-----------+
| header_t *-|------------>+--------------+
|----------------| | stream_t |
| body_t *-|----+ +--------------+
+----------------+ | body_t
+-->+--------------+
| 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.
/* sfrom, Simple From */
#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>
#include <string.h>
#include <mailutils/mailutils.h>
int
main (int argc, const char **argv)
{
char *from;
char *subject;
mailbox_t mbox;
int status;
size_t msgno, total = 0;
/* Register the type of mailbox. IMAP4, POP3 and local format */
{
list_t registrar;
registrar_get_list (®istrar);
list_append (registrar, imap_record);
list_append (registrar, path_record);
list_append (registrar, pop_record);
}
status = mailbox_create_default (&mbox, argv[1]);
if (status != 0)
{
fprintf (stderr, "mailbox_create: %s\n", mu_errstring (status));
exit (EXIT_FAILURE);
}
status = mailbox_open (mbox, MU_STREAM_READ);
if (status != 0)
{
fprintf (stderr, "mailbox_open: %s\n", mu_errstring (status));
exit (EXIT_FAILURE);
}
mailbox_messages_count (mbox, &total);
for (msgno = 1; msgno <= total; msgno++)
{
message_t msg;
header_t hdr;
if ((status = mailbox_get_message (mbox, msgno, &msg)) != 0
|| (status = message_get_header (msg, &hdr)) != 0)
{
fprintf (stderr, "Error message: %s\n",
mu_errstring (status));
exit (EXIT_FAILURE);
}
if (header_aget_value (hdr, MU_HEADER_FROM, &from))
from = strdup ("(NO FROM)");
if (header_aget_value (hdr, MU_HEADER_SUBJECT, &subject))
subject = strdup("(NO SUBJECT)");
printf ("%s\t%s\n", from, subject);
free (from);
free (subject);
}
mailbox_close (mbox);
mailbox_destroy (&mbox);
return 0;
}
Here is a sample output produced by this program:
% MAIL=pop://alain@localhost ./sfrom
Passwd: xxxx
Jim Meyering <meyering@foo.org> fetish(shellutils) beta
Franc,ois Pinard <pinard@bar.org> recode new alpha
...
Folder
======
`/* Prefix _folder__ is reserve */'
`#include <mailutils/folder.h>'
folder_t url_t
-/var/mail- +---//---->/-----------------\ +-->/-----------\
( alain *-)-+ | | url_t *-|----+ | port |
----------- | | |-----------------+ | hostname |
( jakob *-)-+--+ | observer_t *-| | file |
----------- | |-----------------+ | ... |
( jeff *-)-+ | stream_t | \-----------/
----------- | |-----------------|
( sean *-)-+ | auth_t |
---------- |-----------------|
| mailbox_t(1) |
|-----------------|
| mailbox_t(2) |
| ...... |
| mailbox_t(n) |
\-----------------/
- Function: int folder_create (folder_t *, const char *URL)
- Function: void folder_destroy (folder_t *)
- Function: int folder_open (folder_t, int FLAG)
- Function: int folder_close (folder_t)
- Function: int folder_delete (folder_t, const char *MAILBOX)
- Function: int folder_rename (folder_t, const char *, const char
*MAILBOX)
- Function: int folder_subscribe (folder_t, const char *MAILBOX)
- Function: int folder_unsubscribe (folder_t, const char *MAILBOX)
- Function: int folder_list (folder_t, const char *REF, const char
*WCARD, iterator_t *)
- Function: int folder_lsub (folder_t, const char *REF, const char
*WCAR, iterator_t *)
- Function: int folder_get_stream (folder_t, stream_t *)
- Function: int folder_set_stream (folder_t, stream_t)
- Function: int folder_get_observable (folder_t, observable_t *)
- Function: int folder_get_debug (folder_t, debug_t *)
- Function: int folder_set_debug (folder_t, debug_t)
- Function: int folder_get_authority (folder_t, authority_t *)
- Function: int folder_set_authority (folder_t, authority_t)
- Function: int folder_get_url (folder_t, url_t *)
- Function: int folder_set_url (folder_t, url_t)
Mailbox
=======
`/* Prefix _mailbox__ is reserved */'
`#include <mailutils/mailbox.h>'
- Data Type: mailbox_t
The `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.
mailbox_t url_t
-/var/mail- +---//---->/-----------------\ +-->/-----------\
( alain ) | | url_t *-|----+ | port |
----------- | |-----------------+ | hostname |
( jakob *-)----+ | observer_t *-| | file |
----------- |-----------------+ | ... |
( jeff ) | stream_t | \-----------/
----------- |-----------------|
( sean ) | locker_t |
---------- |-----------------|
| message_t(1) |
|-----------------|
| message_t(2) |
| ...... |
| message_t(n) |
\-----------------/
- Function: int mailbox_append_message (mailbox_t MBOX, message_t
MESSAGE)
The MESSAGE is appended to the mailbox MBOX.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null or MESSAGE is invalid.
- Function: int mailbox_close (mailbox_t MBOX)
The stream attach to MBOX is closed.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
- Function: int mailbox_create (mailbox_t *PMBOX, const char *NAME)
The function `mailbox_create' allocates and initializes PMBOX.
The concrete mailbox type instantiate is based on the scheme of
the url NAME.
The return value is `0' on success and a code number on error
conditions:
`MU_ERR_OUT_PTR_NULL'
The pointer PMBOX supplied is NULL.
`MU_ERR_NO_HANDLER'
The url NAME supplied is invalid or not supported.
`EINVAL'
`ENOMEM'
Not enough memory to allocate resources.
- Function: int mailbox_create_default (mailbox_t *PMBOX, const char
*NAME)
Create a mailbox with `mailbox_create ()' based on the environment
variable _$MAIL_ or the string formed by __PATH_MAILDIR_/USER" or
_$LOGNAME_ if USER is null,
- Function: void mailbox_destroy (mailbox_t *PMBOX)
Destroys and releases resources held by PMBOX.
- Function: int mailbox_expunge (mailbox_t MBOX)
All messages marked for deletion are removed.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
- Function: int mailbox_get_folder (mailbox_t MBOX, folder_t *FOLDER)
Get the FOLDER.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
- Function: int mailbox_get_debug (mailbox_t MBOX, debug_t *DEBUG)
Get a debug object. The return value is `0' on success and a code
number on error conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
`ENOMEM'
- Function: int mailbox_get_locker (mailbox_t MBOX, locker_t *PLOCKER)
Return the LOCKER object.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
- Function: int mailbox_get_message (mailbox_t MBOX, size_t MSGNO,
message_t *PMESSAGE)
Retrieve message number MSGNO, PMESSAGE is allocated and
initialized.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null or MSGNO is invalid.
`ENOMEM'
Not enough memory.
- Function: int mailbox_get_observable (mailbox_t mbox MBOX,
observable_t*OBSERVABLE)
Get the observable object.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
`ENOMEM'
Not enough memory.
- Function: int mailbox_get_property (mailbox_t MBOX, property_t
*PROPERTY)
Get the property object. The return value is `0' on success and a
code number on error conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
`ENOMEM'
- Function: int mailbox_get_size (mailbox_t MBOX, off_t *PSIZE)
Gives the MBOX size.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
- Function: int mailbox_get_stream (mailbox_t MBOX, stream_t *PSTREAM)
The mailbox stream is put in PSTREAM.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is invalid or PSTREAM is NULL.
- Function: int mailbox_get_ticket (mailbox_t MBOX, ticket_t TICKET)
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
- Function: int mailbox_get_url (mailbox_t MBOX, url_t *PURL)
Gives the constructed URL.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
- Function: int mailbox_is_modified (mailbox_t MBOX)
Check if the mailbox been modified by an external source.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
- Function: int mailbox_message_unseen (mailbox_t MBOX, size_t
*PNUMBER);
Give the number of first unseen message in MBOX.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
- Function: int mailbox_messages_count (mailbox_t MBOX, size_t
*PNUMBER);
Give the number of messages in MBOX.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
- Function: int mailbox_messages_recent (mailbox_t MBOX, size_t
*PNUMBER);
Give the number of recent messages in MBOX.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
- Function: int mailbox_open (mailbox_t MBOX, int FLAG)
A connection is open, if no stream was provided, a stream is
created based on the MBOX type. The FLAG can be OR'ed. See
`stream_create' for FLAG's description.
The return value is `0' on success and a code number on error
conditions:
`EAGAIN'
`EINPROGRESS'
Operation in progress.
`EBUSY'
Resource busy.
`MU_ERROR_INVALID_PARAMETER'
MBOX is null or flag is invalid.
`ENOMEM'
Not enough memory.
- Function: int mailbox_scan (mailbox_t MBOX, size_t MSGNO, size_t
*PCOUNT);
Scan the mailbox for new messages starting at message MSGNO.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
`ENOMEM'
Not enough memory.
- Function: int mailbox_set_locker (mailbox_t MBOX, locker_t LOCKER)
Set the type of locking done by the MBOX.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
- Function: int mailbox_set_stream (mailbox_t MBOX, stream_t STREAM)
Set the STREAM connection to use for the mailbox.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX or STREAM is NULL.
- Function: int mailbox_set_ticket (mailbox_t MBOX, ticket_t TICKET)
The TICKET will be set on the `auth_t' object on creation.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
- Function: int mailbox_uidnext (mailbox_t MBOX, size_t *PNUMBER);
Give the next predicted uid for MBOX.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
- Function: int mailbox_uidvalidity (mailbox_t MBOX, size_t *PNUMBER);
Give the uid validity of MBOX.
The return value is `0' on success and a code number on error
conditions:
`MU_ERROR_INVALID_PARAMETER'
MBOX is null.
Mailer
======
`/* Prefix _mailer__ is reserved */'
`#include <mailutils/mailer.h>'
The API is still changing.
- Function: int mailer_create (mailer_t *, const char *)
- Function: void mailer_destroy (mailer_t *)
- Function: int mailer_open (mailer_t, int flags)
- Function: int mailer_close (mailer_t)
- Function: int mailer_send_message (mailer_t MAILER, message_t MSG,
address_t FROM, address_t TO);
If from is not NULL, it must contain a single fully qualified
RFC2822 email address which will be used as the envelope from
address. This is the address to which delivery status notifications
are sent, so it never matters what it is set to until it REALLY
matters. This is equivalent to sendmail's -F flag.
The default for FROM is provided by the specific mailer.
If to is not NULL, then the message will be sent to the list of
addresses that it specifies.
The default for TO is to use the contents of the standard "To:",
"Cc:", and "Bcc:" fields, this is equivalent to sendmail's -T flag.
Note: the previous implementation of mailer_send_message() was
equivalent to having both FROM and TO be NULL.
- Function: int mailer_get_property (mailer_t, property_t *)
- Function: int mailer_get_stream (mailer_t, stream_t *)
- Function: int mailer_set_stream (mailer_t, stream_t)
- Function: int mailer_get_debug (mailer_t, debug_t *)
- Function: int mailer_set_debug (mailer_t, debug_t)
- Function: int mailer_get_observable (mailer_t, observable_t *)
- Function: int mailer_get_url (mailer_t, url_t *)
Some usage notes.
-----------------
Some possible use cases the API must support are:
- original submission
1 - fill in header addresses
2 - mailer_send_message(mailer, msg, NULL, NULL);
- from will be filled in if missing,
- bcc's will be deleted before delivery to a non-bcc address,
- message-id and date will be added, if missing,
- a to: or apparently-to: will be added if non is present (for RFC
compliance)
- MTA-style .forward ( and sieve-style redirect )
1 - get the envelope from of the message to be forwarded
2 - mailer_send_message(mailer, msg, from, to)
- MUA-style bounce
1 - add Resent-[to,from,....]
2 - mailer_send_message(mailer, msg, NULL, to)
- DSN "bounce"
1 - compose DSN
2 - mailer_deliver(mailer, msg, address_t( "<>" ), to)
Don't want mail loops, so the null but valid SMTP address of <> is
the envelope from.
The sendmail mailer.
--------------------
/sbin/sendmail isn't always sendmail... sometimes its 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).
Note: 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 mailer_send_message() when sendmail returns 1? 1 maps to
EPERM, which is less than descriptive!
The SMTP mailer.
----------------
This mailer does NOT canonicalize the message. This must be done
before sending the message, or it may be assumed that the MTA will do
so.
It does blind out the Bcc: header before sending, though.
Note: mutt always puts the recipient addresses on the command line,
even bcc ones, do we strip the bcc before forwarding with SMTP?
Non-RFC822 addresses.
---------------------
An address that has no domain is not and RFC822 email address. What
do I do with them? Should the user of the API be responsible for
determining what is mean by email to "john" means? Or should the be
able to configure sendmail to decide globally what this means. If so, we
can pass the address to sendmail, but we have to decide for SMTP! So,
right now these addresses are rejected. This could be changed.
Message
=======
`#include <mailutils/message.h>'
`/* Prefix _message__ is reserve */'
The `message_t' object is a convenient way to manipulate messages.
It encapsulates the `envelope_t', the `header_t' and the `body_t'.
mailbox_t
__________ message_t
(message[1]) +------>+-----------------------+
---------- | | envelope_t |
(message[2]) | |-----------------------|
---------- | | header_t |
(message[3])--------+ |-----------------------|
---------- | body_t |
(message[n]) |-----------------------|
---------- | attribute_t |
|-----------------------|
| stream_t |
+-----------------------+
- Function: void message_create (message_t *MSG, void *OWNER)
- Function: void message_destroy (message_t *MSG, void *OWNER)
The resources allocate for MSG are freed.
- Function: int message_get_header (message_t MSG, header_t *PHEADER)
Retrieve MSG header.
- Function: int message_set_header (message_t MSG, header_t HEADER,
void *OWNER)
- Function: int message_get_body (message_t MSG, body_t *PBODY)
- Function: int message_set_body (message_t MSG, body_t BODY, void
*OWNER)
- Function: int message_is_multipart (message_t MSG, int *PMULTI)
Set *PMULTI to non-zero value if MSG is multi-part.
- Function: int message_get_num_parts (message_t MSG, size_t *nparts)
- Function: int message_get_part (message_t MSG, size_t part,
message_t *msg)
- Function: int message_get_stream (message_t MSG, stream_t *PSTREAM)
- Function: int message_set_stream (message_t MSG, stream_t
STREAM,void *OWNER )
- Function: int message_get_attribute (message_t MSG, attribute_t
*PATTRIBUTE)
- Function: int message_set_attribute (message_t MSG, attribute_t
ATTRIBUTE, void *owner)
- Function: int message_get_envelope (message_t MSG, envelope_t
*penvelope)
- Function: int message_set_envelope (message_t MSG, envelope_t
envelope, void *OWNER)
- Function: int message_get_uid (message_t MSG, size_t *UID)
- Function: int message_get_uidl (message_t MSG, char *BUFFER, size_t
BUFLEN, size_t *PWRITEN)
- Function: int message_set_uidl (message_t MSG, int
(*_GET_UIDL)(message_t, char *, size_t, size_t *), void
*OWNER)
- Function: int message_get_observable (message_t MSG, observable_t
*OBSERVABLE)
- Function: int message_create_attachment (const char *CONTENT_TYPE,
const char *ENCODING, const char *FILENAME, message_t *NEWMSG)
- Function: int message_save_attachment (message_t MSG, const char
*FILENAME, void **DATA)
- Function: int message_encapsulate (message_t MSG, message_t *NEWMSG,
void **DATA)
- Function: int message_unencapsulate (message_t MSG, message_t
*NEWMSG, void **DATA);
Envelope
========
`/* Prefix _envelope__ is reserved */'
`#include <mailutils/envelope.h>'
- Function: int envelope_date (envelope_t, char *, size_t, size_t *);
Get the date that the message was delivered to the mailbox, in
something close to ANSI ctime() format: Mon Jul 05 13:08:27 1999.
- Function: int envelope_sender (envelope_t, char *, size_t, size_t *);
Get the address that this message was reportedly received from.
This would be the "mail from" argument if the message was delivered
or received via SMTP, for example.
- Function: int envelope_get_message (envelope_t, message_t *);
- Function: int envelope_create (envelope_t *, void *);
Primarily for internal use.
- Function: void envelope_destroy (envelope_t *, void *);
Primarily for internal use.
- Function: int envelope_set_sender (envelope_t, int (*_sender) __P
((envelope_t, char *, size_t, size_t*)), void *);
Primarily for internal use. The implementation of envelope_t
depends on the mailbox type, this allows the function which
actually gets the sender to be set by the creator of an envelope_t.
- Function: int envelope_set_date (envelope_t, int (*_date) __P
((envelope_t, char *, size_t, size_t *)), void *);
Primarily for internal use. The implementation of envelope_t
depends on the mailbox type, this allows the function which
actually gets the date to be set by the creator of an envelope_t.
Headers
=======
`/* Prefix _header__ is reserved */'
`#include <mailutils/header.h>'
So far we plan support for RFC822 and plan for RFC1522. with RFC1522
non ASCII characters will be encoded.
- Function: int header_create (header_t *HDR, const char *BLURB,
size_t LEN, void *OWNER)
Initialize a HDR to a supported type. If BLURB is not NULL, it is
parsed.
- Function: void header_destroy (header_t *HDR, void *OWNER)
The resources allocated for HDR are freed.
- Function: int header_set_value (header_t HDR, const char *FN, const
char *FV, size_t n, int REPLACE)
Set the field-name FN to field-value FV of size N in HDR. If
REPLACE is non-zero the initial value is replaced, if zero it is
appended.
Some basic macros are already provided for rfc822.
`MU_HEADER_RETURN_PATH'
Return-Path
`MU_HEADER_RECEIVED'
Received
`MU_HEADER_DATE'
Date
`MU_HEADER_FROM'
From
`MU_HEADER_RESENT_FROM'
Resent-From
`MU_HEADER_SUBJECT'
Subject
`MU_HEADER_SENDER'
Sender
`MU_HEADER_RESENT_SENDER'
Resent-SENDER
`MU_HEADER_TO'
To
`MU_HEADER_RESENT_TO'
Resent-To
`MU_HEADER_CC'
Cc
`MU_HEADER_RESENT_CC'
Resent-Cc
`MU_HEADER_BCC'
Bcc
`MU_HEADER_RESENT_BCC'
Resent-Bcc
`MU_HEADER_REPLY_TO'
Reply-To
`MU_HEADER_RESENT_REPLY_TO'
Resent-Reply-To
`MU_HEADER_MESSAGE_ID'
Message-ID
`MU_HEADER_RESENT_MESSAGE_ID'
Resent-Message-ID
`MU_HEADER_IN_REPLY_TO'
In-Reply-To
`MU_HEADER_ENCRYPTED'
Encrypted
`MU_HEADER_PRECEDENCE'
Precedence
`MU_HEADER_STATUS'
Status
`MU_HEADER_CONTENT_LENGTH'
Content-Length
`MU_HEADER_CONTENT_TYPE'
Content-Type
`MU_HEADER_MIME_VERSION'
MIME-Version
- Function: int header_get_value (header_t HDR, const char *FN, char
*FV, size_t LEN, size_t *N)
Value of field-name FN is returned in buffer FV of size LEN. The
number of bytes written is put in N.
- Function: int header_aget_value (header_t HDR, const char *FN, char
**FV)
The value is allocated.
- Function: int header_get_stream (header_t HDR, stream_t *PSTREAM)
- Function: int header_set_size (header_t HDR, size_t *SIZE)
- Function: int header_set_lines (header_t HDR, size_t *LPINES)
Body
====
`/* Prefix _body__ is reserved */'
`#include <mailutils/body.h>'
- Function: int body_create (body_t *BODY, void *OWNER)
Initialize an object BDY.
- Function: void body_destroy (body_t *PBODY)
The resources allocate are release.
- Function: int body_get_stream (body_t BODY, stream_t *PSTREAM)
- Function: int body_set_stream (body_t BODY, stream_t STREAM, void
*OWNER)
- Function: int body_get_filename __P ((body_t BODY, char *BUFFER,
size_tBUFLEN, size_t *PWRITEN)
- Function: int body_set_filename (body_t BODY, const char*BUFFER)
- Function: int body_size (body_t BODY, size_t*PSIZE)
- Function: int body_lines (body_t BODY, size_t *PLINES)
Attribute
=========
`/* Prefix _attribute__ is reserved */'
`#include <mailutils/attribute.h>'
- Function: int attribute_create (attribute_t *PATTRIBUTE)
- Function: void attribute_destroy (attribute_t *PATTRIBUTE)
- Function: int attribute_is_seen (attribute_t ATTRIBUTE)
- Function: int attribute_is_answered (attribute_t ATTRIBUTE)
- Function: int attribute_is_flagged (attribute_t ATTRIBUTE)
- Function: int attribute_is_deleted (attribute_t ATTRIBUTE)
- Function: int attribute_is_draft (attribute_t ATTRIBUTE)
- Function: int attribute_is_recent (attribute_t ATTRIBUTE)
- Function: int attribute_is_read (attribute_t ATTRIBUTE)
- Function: int attribute_set_seen (attribute_t ATTRIBUTE)
- Function: int attribute_set_answered (attribute_t ATTRIBUTE)
- Function: int attribute_set_flagged (attribute_t ATTRIBUTE)
- Function: int attribute_set_deleted (attribute_t ATTRIBUTE)
- Function: int attribute_set_draft (attribute_t ATTRIBUTE)
- Function: int attribute_set_recent (attribute_t ATTRIBUTE)
- Function: int attribute_set_read (attribute_t ATTRIBUTE)
- Function: int attribute_unset_seen (attribute_t ATTRIBUTE)
- Function: int attribute_unset_answered (attribute_t ATTRIBUTE)
- Function: int attribute_unset_flagged (attribute_t ATTRIBUTE)
- Function: int attribute_unset_deleted (attribute_t ATTRIBUTE)
- Function: int attribute_unset_draft (attribute_t ATTRIBUTE)
- Function: int attribute_unset_recent (attribute_t ATTRIBUTE)
- Function: int attribute_unset_read (attribute_t ATTRIBUTE)
- Function: int attribute_is_equal (attribute_t ATT1, attribute_t ATT2)
- Function: int attribute_copy (attribute_t DST, attribute_t SRC)
- Function: int string_to_attribute (const char *BUF, attribute_t
*PATTR)
- Function: int attribute_to_string (attribute_t ATTR, char *BUF,
size_t LEN, size_t *PWRITEN)
Stream
======
`#include <mailutils/stream.h>'
These generic flags are interpreted as appropriate to the specific
streams.
`MU_STREAM_READ'
The stream is open read only.
`MU_STREAM_WRITE'
The stream is open write only.
`MU_STREAM_RDWR'
The stream is open read and write.
`MU_STREAM_APPEND'
The stream is open in append mode for writing.
`MU_STREAM_CREAT'
The stream open will create the underlying resource (such as a
file) if it doesn't exist already.
`MU_STREAM_NONBLOCK'
The stream is set non blocking.
`MU_STREAM_NO_CHECK'
Stream is destroyed without checking for the owner.
`MU_STREAM_NO_CLOSE'
Stream doesn't close it's underlying resource when it is closed or
destroyed.
- Function: int file_stream_create (stream_t *PSTREAM, const char
*FILENAME, int FLAGS)
- Function: int tcp_stream_create (stream_t *PSTREAM, const char
*HOST, int PORT, int FLAGS)
- Function: int mapfile_stream_create (stream_t *PSTREAM, const char
*FILENAME, int FLAGS)
- Function: int memory_stream_create (stream_t *PSTREAM, const char
*FILENAME, int FLAGS)
- Function: int encoder_stream_create (stream_t *PSTREAM, stream_t
IOSTREAM, const char *ENCODING)
- Function: int decoder_stream_create (stream_t *PSTREAM, stream_t
IOSTREAM, const char *ENCODING)
- Function: int stdio_stream_create (stream_t *PSTREAM, FILE* STDIO,
int FLAGS)
If MU_STREAM_NO_CLOSE is specified, fclose() will not be called on
STDIO when the stream is closed.
- Function: void stream_destroy (stream_t *PSTREAM, void *OWNER)
- Function: int stream_open (stream_t STREAM)
- Function: int stream_close (stream_t STREAM)
- Function: int stream_is_seekable (stream_t STREAM)
- Function: int stream_get_fd (stream_t STREAM, int *PFD)
- Function: int stream_read (stream_t STREAM, char *BUFFER, size_t
BUFLEN, off_t OFFSET, size_t *PWRITEN)
- Function: int stream_readline (stream_t STREAM, char *BUFFER, size_t
BUFLEN, off_t OFFSET, size_t *PWRITEN)
- Function: int stream_size (stream_t STREAM, off_t *PSIZE)
- Function: int stream_truncate (stream_t STREAM, off_t SIZE)
- Function: int stream_write (stream_t STREAM, const char *BUFFER,
size_t BUFLEN, off_t OFFSET, size_t *PWRITEN)
- Function: int stream_setbufsiz (stream_t STREAM, size_t SIZE)
- Function: int stream_flush (stream_t STREAM)
These functions will typically only be useful to implementors of
streams.
- Function: int stream_create (stream_t *PSTREAM, int FLAGS, void
*OWNER)
Used to implement a new kind of stream.
- Function: int stream_get_flags (stream_t STREAM, int *PFLAGS)
- Function: int stream_get_state (stream_t STREAM, int *PSTATE)
`MU_STREAM_STATE_OPEN'
Last action was `stream_open'.
`MU_STREAM_STATE_READ'
Last action was `stream_read' or `stream_readline'.
`MU_STREAM_STATE_WRITE'
Last action was `stream_write'.
`MU_STREAM_STATE_CLOSE'
Last action was `stream_close'.
An example using `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 */
#include <stdlib.h>
#include <stdio.h>
#include <errno.h>
#include <string.h>
#include <unistd.h>
#include <mailutils/mailutils.h>
const char *wbuf = "GET / HTTP/1.0\r\n\r\n";
char rbuf[1024];
int
main ()
{
int ret, off = 0, fd;
stream_t stream;
size_t nb;
fd_set fds;
ret = tcp_stream_create (&stream, "www.gnu.org", 80, MU_STREAM_NONBLOCK);
if (ret != 0)
{
mu_error ( "tcp_stream_create: %s\n", mu_errstring (ret));
exit (EXIT_FAILURE);
}
connect_again:
ret = stream_open (stream);
if (ret != 0)
{
if (ret == EAGAIN)
{
ret = stream_get_fd (stream, &fd);
if (ret != 0)
{
mu_error ( "stream_get_fd: %s\n", mu_errstring (ret));
exit (EXIT_FAILURE);
}
FD_ZERO (&fds);
FD_SET (fd, &fds);
select (fd + 1, NULL, &fds, NULL, NULL);
goto connect_again;
}
mu_error ( "stream_open: %s\n", mu_errstring (ret));
exit (EXIT_FAILURE);
}
ret = stream_get_fd (stream, &fd);
if (ret != 0)
{
mu_error ( "stream_get_fd: %s\n", mu_errstring (ret));
exit (EXIT_FAILURE);
}
write_again:
ret = stream_write (stream, wbuf + off, strlen (wbuf), 0, &nb);
if (ret != 0)
{
if (ret == EAGAIN)
{
FD_ZERO (&fds);
FD_SET (fd, &fds);
select (fd + 1, NULL, &fds, NULL, NULL);
off += nb;
goto write_again;
}
mu_error ( "stream_write: %s\n", mu_errstring (ret));
exit (EXIT_FAILURE);
}
if (nb != strlen (wbuf))
{
mu_error ( "stream_write: %s\n", "nb != wbuf length");
exit (EXIT_FAILURE);
}
do
{
ret = stream_read (stream, rbuf, sizeof (rbuf), 0, &nb);
if (ret != 0)
{
if (ret == EAGAIN)
{
FD_ZERO (&fds);
FD_SET (fd, &fds);
select (fd + 1, &fds, NULL, NULL, NULL);
}
else
{
mu_error ( "stream_read: %s\n", mu_errstring (ret));
exit (EXIT_FAILURE);
}
}
write (2, rbuf, nb);
}
while (nb || ret == EAGAIN);
ret = stream_close (stream);
if (ret != 0)
{
mu_error ( "stream_close: %s\n", mu_errstring (ret));
exit (EXIT_FAILURE);
}
stream_destroy (&stream, NULL);
exit (EXIT_SUCCESS);
}
Iterator
========
`/* Prefix _iterator__ is reserved */'
`#include <mailutils/iterator.h>'
- Function: int iterator_create (iterator_t *)
- Function: void iterator_destroy (iterator_t *)
- Function: int iterator_first (iterator_t)
- Function: int iterator_next (iterator_t)
- Function: int iterator_current (iterator_t, void **pitem)
- Function: int iterator_is_done (iterator_t)
Authenticator
=============
`/* Prefix _auth__ is reserved */'
`#include <mailutils/auth.h>'
There are many ways to authenticate to a server. To be flexible the
authentication process is provided by two objects `auth_t' and
`ticket_t'. The `auth_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 `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
`auth_authenticate' which will get the _user_ and _passwd_ if not set,
this function can be overridden by a custom method.
- Function: int auth_create (auth_t *PAUTH, void *OWNER)
- Function: void auth_destroy (auth_t *PAUTH, void *OWNER)
- Function: int auth_prologue (auth_t AUTH)
- Function: int auth_authenticate (auth_t AUTH, char **USER, char
**PASSWD)
- Function: int auth_epilogue (auth_t AUTH)
A simple example of an authenticate function:
#include <mailutils/auth.h>
#include <stdio.h>
#include <string.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;
}
Address
=======
`/* Prefix _address__ is reserved */'
`#include <mailutils/address.h>'
The Internet address format is defined in RFC 822. RFC 822 has been
updated, and is now superceeded by RFC 2822, which makes some
corrections and clarifications. References to RFC 822 here apply
equally to RFC 2822.
The RFC 822 format is more flexible than many people realize, here
is a quick summary of the syntax this parser implements, see RFC 822
for the details. "[]" pairs mean "optional", "/" means "one or the
other", and double-quoted characters are literals.
addr-spec = local-part "d"omain
mailbox = addr-spec ["(" display-name ")"] /
[display-name] "<" [route] addr-spec ">"
mailbox-list = mailbox ["," mailbox-list]
group = display-name ":" [mailbox-list] ";"
address = mailbox / group / unix-mbox
address-list = address ["," address-list]
unix-mbox is a non-standard extension meant to deal with the common
practice of using user names as addresses in mail utilities. It allows
addresses such as "root" to be parsed correctly. These are NOT valid
internet email addresses, they must be qualified before use.
Several address functions have a set of common arguments with
consistent semantics, these are described here to avoid repetition.
Since an address-list may contain multiple addresses, they are
accessed by a *one-based* index number, NO. The index is one-based
because pop, imap, and other message stores commonly use one-based
counts to access messages and attributes of messages.
If LEN is greater than `0' it is the length of the buffer BUF, and
as much of the component as possible will be copied into the buffer.
The buffer will be null terminated.
The size of a particular component may be queried by providing `0'
for the LEN of the buffer, in which case the buffer is optional. In
this case, if N is provided *N is assigned the length of the component
string.
- Data Type: address_t
The `address_t' object is used to hold information about a parsed
RFC822 address list, and is an opaque data structure to the user.
Functions are provided to retrieve information about an address in
the address list.
- Function: int address_create (address_t *ADDR, const char *STRING)
This function allocates and initializes ADDR by parsing the RFC822
address-list STRING.
The return value is `0' on success and a code number on error
conditions:
`EINVAL'
Invalid usage, usually a required argument was `null'.
`ENOMEM'
Not enough memory to allocate resources.
`ENOENT'
Invalid RFC822 syntax, parsing failed.
- Function: int address_createv (address_t *ADDR, const char *SV,
size_t LEN)
This function allocates and initializes ADDR by parsing the array
of pointers to RFC822 address-lists in SV. If LEN is `-1', then SV
must be null-terminated in the fashion of ARGV, otherwise LEN is
the length of the array.
The return value is `0' on success and a code number on error
conditions:
`EINVAL'
Invalid usage, usually a required argument was `null'.
`ENOMEM'
Not enough memory to allocate resources.
`ENOENT'
Invalid RFC822 syntax, parsing failed.
- Function: void address_destroy (address_t *ADDR)
The ADDR is destroyed.
- Function: int address_get_email (address_t *ADDR, size_t NO, char*
BUF, size_t LEN, size_t* N)
Accesses the NOth email address component of the address list. This
address is the plain email address, correctly quoted, suitable for
using in an smtp dialog, for example, or as the address part of a
contact book entry.
Note that the entry may be valid, but be a group name. In this
case success is returned, but the length of the address is `0'.
The return value is `0' on success and a code number on error
conditions:
`EINVAL'
Invalid usage, usually a required argument was `null'.
`ENOENT'
The index NO is outside of the range of available addresses.
- Function: int address_aget_email (address_t *ADDR, size_t NO, char**
BUFP)
As above, but mallocs the email address, if present,
and write a pointer to it into BUFP. BUFP will be `NULL' if there
is no email address to return.
The return value is `0' on success and a code number on error
conditions:
`EINVAL'
Invalid usage, usually a required argument was `null'.
`ENOENT'
The index NO is outside of the range of available addresses.
- Function: int address_get_personal (address_t *ADDR, size_t NO,
char* BUF, size_t LEN, size_t* N)
Accesses the display-name describing the NOth email address. This
display-name is optional, so may not be present. If it is not
present, but there is an RFC822 comment after the address, that
comment will be returned as the personal phrase, as this is a
common usage of the comment even though it is not defined in the
internet mail standard.
A group is a kind of a special case. It has a display-name,
followed by an optional mailbox-list. The display-name will be
allocated an address all it's own, but all the other elements
(local-part, domain, etc.) will be zero-length. So "a group: ;" is
valid, will have a count of 1, but address_get_email(), and all
the rest, will return zero-length output.
The return value is `0' on success and a code number on error
conditions:
`EINVAL'
Invalid usage, usually a required argument was `null'.
`ENOENT'
The index NO is outside of the range of available addresses.
- Function: int address_get_comments (address_t *ADDR, size_t NO,
char* BUF, size_t LEN, size_t* N)
Accesses the comments extracted while parsing the NOth email
address. These comments have no defined meaning, and are not
currently collected.
The return value is `0' on success and a code number on error
conditions:
`EINVAL'
Invalid usage, usually a required argument was `null'.
`ENOENT'
The index NO is outside of the range of available addresses.
- Function: int address_get_email (address_t *ADDR, size_t NO, char*
BUF, size_t LEN, size_t* N)
Accesses the email addr-spec extracted while parsing the NOth
email address. This will be `0' length for a unix-mbox.
The return value is `0' on success and a code number on error
conditions:
`EINVAL'
Invalid usage, usually a required argument was `null'.
`ENOENT'
The index NO is outside of the range of available addresses.
- Function: int address_get_local_part (address_t *ADDR, size_t NO,
char* BUF, size_t LEN, size_t* N)
Accesses the local-part of an email addr-spec extracted while
parsing the NOth email address.
The return value is `0' on success and a code number on error
conditions:
`EINVAL'
Invalid usage, usually a required argument was `null'.
`ENOENT'
The index NO is outside of the range of available addresses.
- Function: int address_get_domain (address_t *ADDR, size_t NO, char*
BUF, size_t LEN, size_t* N)
Accesses the domain of an email addr-spec extracted while parsing
the NOth email address. This will be `0' length for a unix-mbox.
The return value is `0' on success and a code number on error
conditions:
`EINVAL'
Invalid usage, usually a required argument was `null'.
`ENOENT'
The index NO is outside of the range of available addresses.
- Function: int address_get_route (address_t *ADDR, size_t NO, char*
BUF, size_t LEN, size_t* N)
Accesses the route of an email addr-spec extracted while parsing
the NOth email address. This is a rarely used RFC822 address
syntax, but is legal in SMTP as well. The entire route is returned
as a string, those wishing to parse it should look at
<mailutils/parse822.h>.
The return value is `0' on success and a code number on error
conditions:
`EINVAL'
Invalid usage, usually a required argument was `null'.
`ENOENT'
The index NO is outside of the range of available addresses.
- Function: int address_is_group (address_t *ADDR, size_t NO, size_t
LEN, int* YES)
Sets *YES to `1' if this address is just the name of a group, `0'
otherwise. This is faster than checking if the address has a
non-zero length personal, and a zero-length local_part and domain.
YES can be `null', though that doesn't serve much purpose other
than determining that NO refers to an address.
Currently, there is no way to determine the end of the group.
The return value is `0' on success and a code number on error
conditions:
`EINVAL'
Invalid usage, usually a required argument was `null'.
`ENOENT'
The index NO is outside of the range of available addresses.
- Function: int address_to_string (address_t *ADDR, char* BUF, size_t
LEN, size_t* N)
Returns the entire address list as a single RFC822 formatted
address list.
The return value is `0' on success and a code number on error
conditions:
`EINVAL'
Invalid usage, usually a required argument was `null'.
`ENOMEM'
Not enough memory to allocate resources.
- Function: int address_get_count (address_t ADDR, size_t* COUNT)
Returns a count of the addresses in the address list.
If ADDR is `null', the count is `0'. If COUNT is not `null', the
count will be written to *COUNT.
The return value is `0'.
Example
=======
#include <stdio.h>
#include <errno.h>
#include <string.h>
#include <mailutils/address.h>
#include <mailutils/errno.h>
#include <mailutils/mutil.h>
#define EPARSE ENOENT
static int
parse (const char *str)
{
size_t no = 0;
size_t pcount = 0;
int status;
char buf[BUFSIZ];
address_t address = NULL;
mu_set_user_email_domain ("localhost");
status = address_create (&address, str);
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++)
{
size_t got = 0;
int isgroup;
address_is_group (address, no, &isgroup);
printf ("%lu ", (unsigned long) no);
if (isgroup)
{
address_get_personal (address, no, buf, sizeof (buf), &got);
printf ("group <%s>\n", buf);
}
else
{
address_get_email (address, no, buf, sizeof (buf), 0);
printf ("email <%s>\n", buf);
}
address_get_personal (address, no, buf, sizeof (buf), &got);
if (got && !isgroup)
printf (" personal <%s>\n", buf);
address_get_comments (address, no, buf, sizeof (buf), &got);
if (got)
printf (" comments <%s>\n", buf);
address_get_local_part (address, no, buf, sizeof (buf), &got);
if (got)
{
printf (" local-part <%s>", buf);
address_get_domain (address, no, buf, sizeof (buf), &got);
if (got)
printf (" domain <%s>", buf);
printf ("\n");
}
address_get_route (address, no, buf, sizeof (buf), &got);
if (got)
printf (" route <%s>\n", buf);
}
address_destroy (&address);
printf ("\n");
return 0;
}
static int
parseinput (void)
{
char buf[BUFSIZ];
while (fgets (buf, sizeof (buf), stdin) != 0)
{
buf[strlen (buf) - 1] = 0;
parse (buf);
}
return 0;
}
int
main (int argc, const char *argv[])
{
argc = 1;
if (!argv[argc])
{
return parseinput ();
}
for (; argv[argc]; argc++)
{
if (strcmp (argv[argc], "-") == 0)
{
parseinput ();
}
else
{
parse (argv[argc]);
}
}
return 0;
}
Locker
======
`/* Prefix _locker__ is reserved */'
`#include <mailutils/locker.h>'
- Function: int locker_create (locker_t * PLOCKER, char *FILENAME,
size_t LEN, int FLAGS)
- Function: void locker_destroy (locker_t * PLOCKER)
- Function: int locker_lock (locker_t LOCKER, int FLAG)
`MU_LOCKER_RDLOCK'
`MU_LOCKER_WRLOCK'
`MU_LOCKER_PID'
`MU_LOCKER_FCNTL'
`MU_LOCKER_TIME'
- Function: int locker_touchlock (locker_t LOCKER)
- Function: int locker_unlock (locker_t LOCKER)
URL
===
A mailbox or a mailer can be described in a URL, the string will
contain the necessary information to initialize `mailbox_t', or
`mailer_t' properly.
POP3
----
The POP URL scheme contains a POP server, optional port number and
the authentication mechanism. The general form is
<pop://[<user>[;AUTH=<auth>]@]<host>[:<port>]>
or
<pop://[<user>[:<passwd>]@]<host>[:<port>]>
If _:port_ is omitted the default value is 110. Different forms of
authentication can be specified with _;AUTH=type_. The special string
_;AUTH=*_ indicates that the client will use a default scheme base on
the capability of the server.
<pop://obelix@gaulois.org>
<pop://asterix;AUTH=*@france.com>
<pop://falbala;AUTH=+APOP@france.com>
<pop://obelix;AUTH=+APOP@village.gaulois.org:2000>
<pop://obelix:menhir@village.gaulois.org:2000>
For more complete information see `rfc2368'.
IMAP
----
The IMAP URL scheme contains an IMAP server, optional port number
and the authentication mechanism. The general form is
<imap://[<user>[;AUTH=<type>]]@<host>[:port][/<mailbox>]>
or
<imap://[<user>[:<passwd>]]@<host>[:port][/<mailbox>]>
If _:port_ is omitted the default value is 220. Different forms of
authentication can be specified with _;AUTH=type_. The special string
_;AUTH=*_ indicates that the client will use a default scheme base on
the capability of the server.
<imap://obelix@imap.gaulois.org>
<imap://asterix;AUTH=*@imap.france.com>
<imap://asterix:potion@imap.france.com>
For more complete information see `rfc2192'.
File
----
Local folder should be handle by this URL. It is preferable to let
the mailbox recognize the type of mailbox and take the appropriate
action.
<file://path>
<file://var/mail/user>
<file://home/obelix/Mail>
For MMDF, MH local mailboxes URLs are provided, but it is
preferable to use <file://path> and let the library figure out which
one.
<mmdf://path>
<mh://path>
Mailto
------
After setting a mailer, <mailto:> is used to tell the mailer where
and to whom the message is for.
<mailto://hostname>
Mailto can be used to generate short messages, for example to
subscribe to mailing lists.
<mailto://bug-mailutils@gnu.org?body=subscribe>
<mailto://bug-mailutils@gnu.org?Subject=hello&body=subscribe>
For more complete information see `rfc2368'.
URL functions
-------------
Helper functions are provided to retrieve and set the _URL_ fields.
- Function: int url_create (url_t *URL, const char *NAME)
Create and the URL data structure, but do not parse it.
- Function: void url_destroy (url_t *)
Destroy the url and free it's resources.
- Function: int url_parse (url_t URL)
Parses the url, after calling this the get functions can be called.
The syntax, condensed from RFC 1738, and extended with the ;auth=
of RFC 2384 (for POP) and RFC 2192 (for IMAP) is:
url =
scheme ":" [ "//"
[ user [ ( ":" password ) | ( ";auth=" auth ) ] "]"
host [ ":" port ]
[ ( "/" urlpath ) | ( "?" query ) ] ]
This is a generalized URL syntax, and may not be exactly
appropriate for any particular scheme.
- Function: const char* url_to_string (const url_t URL)
- Function: int url_get_scheme (const url_t URL, char *SCHEM, size_t
LEN, size_t *N)
- Function: int url_get_user (const url_t URL, char *USR, size_t LEN,
size_t *N)
- Function: int url_get_passwd (const url_t URL, char *PASSWD, size_t
LEN, size_t *N)
- Function: int url_get_host (const url_t URL, char *HOST, size_t LEN,
size_t *N)
- Function: int url_get_port (const url_t URL, long *PORT)
- Function: int url_get_path (const url_t URL, char *PATH, size_t LEN,
size_t *N)
- Function: int url_get_query (const url_t URL, char *QUERY,
size_tlen, size_t *N)
- Function: char* url_decode (const char* STRING)
Decodes an RFC 1738 % encoded string, returning the decoded string
in allocated memory. If the string is not encoded, this
degenerates to a strdup().
Example
=======
#include <stdio.h>
#include <string.h>
#include <mailutils/errno.h>
#include <mailutils/url.h>
int
main ()
{
char str[1024];
char buffer[1024];
long port = 0;
int len = sizeof (buffer);
url_t u = NULL;
while (fgets (str, sizeof (str), stdin) != NULL)
{
int rc;
str[strlen (str) - 1] = '\0'; /* chop newline */
if (strspn (str, " \t") == strlen (str))
continue; /* skip empty lines */
if ((rc = url_create (&u, str)) != 0)
{
fprintf (stderr, "url_create %s ERROR: [%d] %s",
str, rc, mu_errstring (rc));
exit (1);
}
if ((rc = url_parse (u)) != 0)
{
printf ("%s => FAILED: [%d] %s\n",
str, rc, mu_errstring (rc));
continue;
}
printf ("%s => SUCCESS\n", str);
url_get_scheme (u, buffer, len, NULL);
printf ("\tscheme <%s>\n", buffer);
url_get_user (u, buffer, len, NULL);
printf ("\tuser <%s>\n", buffer);
url_get_passwd (u, buffer, len, NULL);
printf ("\tpasswd <%s>\n", buffer);
url_get_auth (u, buffer, len, NULL);
printf ("\tauth <%s>\n", buffer);
url_get_host (u, buffer, len, NULL);
printf ("\thost <%s>\n", buffer);
url_get_port (u, &port);
printf ("\tport %ld\n", port);
url_get_path (u, buffer, len, NULL);
printf ("\tpath <%s>\n", buffer);
url_get_query (u, buffer, len, NULL);
printf ("\tquery <%s>\n", buffer);
url_destroy (&u);
}
return 0;
}
Parse822 -- Functions for Parsing RFC 822 Headers
=================================================
`/* Prefix _parse822__ is reserved */'
`#include <mailutils/parse822.h>'
Internet Message Format, see Address node for the discussion.
- Function: int parse822_address_list (address_t* a, const char* s)
- Function: int parse822_mail_box (const char** p, const char* e,
address_t* a)
- Function: int parse822_group (const char** p, const char* e,
address_t* a)
- Function: int parse822_address (const char** p, const char* e,
address_t* a)
- Function: int parse822_route_addr (const char** p, const char* e,
address_t* a)
- Function: int parse822_route (const char** p, const char* e, char**
route)
- Function: int parse822_addr_spec (const char** p, const char* e,
address_t* a)
- Function: int parse822_unix_mbox (const char** p, const char* e,
address_t* a)
- Function: int parse822_local_part (const char** p, const char* e,
char** local_part)
- Function: int parse822_domain (const char** p, const char* e, char**
domain)
- Function: int parse822_sub_domain (const char** p, const char* e,
char** sub_domain)
- Function: int parse822_domain_ref (const char** p, const char* e,
char** domain_ref)
- Function: int parse822_domain_literal (const char** p, const char*
e, char** domain_literal)
- Function: int parse822_quote_string (char** quoted, const char* raw)
- Function: int parse822_quote_local_part (char** quoted, const char*
raw)
- Function: int parse822_field_body (const char** p, const char *e,
char** fieldbody)
- Function: int parse822_field_name (const char** p, const char *e,
char** fieldname)
Authentication Library
**********************
The functions from `libmailbox' library get user information from
the system user database. The library `libmuauth' extends this
functionality, allowing `libmailbox' functions to obtain information
about a user from several places, like SQL database, etc. The method
used is described in detail in *Note authentication::. This chapter
contains a very succinct description of the underlying library
mechanism.
Data Types
==========
- Data Type: mu_auth_fp
This is a pointer to authentication or authorization data. It is
defined as follows:
typedef int (*mu_auth_fp) (void *RETURN_DATA,
void *KEY,
void *FUNC_DATA,
void *CALL_DATA);
Its arguments are:
RETURN_DATA
(1). Upon successful return authorization handler leaves in
this memory location a pointer to the filled `mu_auth_data'
structure with the user's information.
For authentication handlers this argument is always `NULL' and
should be ignored.
KEY
The search key value. Its actual type depends upon type of
the handler.
For authorization handlers it is `const char*' if the handler
is called by `mu_get_auth_by_name()' and `uid_t *' if it is
called by `mu_get_auth_by_uid()'.
For authentication handlers it is always `struct
mu_auth_data*' representing the user's data obtained by a
previous call to a `mu_get_auth_by_...' function.
FUNC_DATA
Any data associated with this handler.
CALL_DATA
Any call specific data. This argument is not used at the
moment.
- Data Type: mu_auth_data
The `mu_auth_data' is used to return the information about the
user. It is similar to system `struct passwd', except that it is
more mailutils-specific. Its definition is:
struct mu_auth_data {
/* These are from struct passwd */
char *name; /* user name */
char *passwd; /* user password */
uid_t uid; /* user id */
gid_t gid; /* group id */
char *gecos; /* real name */
char *dir; /* home directory */
char *shell; /* shell program */
/* */
char *mailbox; /* Path to the user's system mailbox */
int change_uid; /* Should the uid be changed? */
};
- Data Type: mu_auth_module
The `mu_auth_module' structure contains full information about a
libmuauth module. It is declared as follows:
struct mu_auth_module {
char *name; /* Module name */
struct argp *argp; /* Corresponding argp structure */
mu_auth_fp authenticate; /* Authentication function ... */
void *authenticate_data; /* ... and its specific data */
mu_auth_fp auth_by_name; /* Get user info by user name */
void *auth_by_name_data; /* ... and its specific data */
mu_auth_fp auth_by_uid; /* Get user info by user id */
void *auth_by_uid_data; /* ... and its specific data */
};
---------- Footnotes ----------
(1) Actually it shoud have been `struct mu_auth_data** return_data'.
This will be fixed in the next release
Initializing the libmuauth
==========================
- Function: void mu_auth_init (void)
This function registers the command line capability "auth". It
must be called after registering `libmuauth' modules and before
calling `mu_agrp_parse()'. If an error occurs, this function prints
diagnostic message and aborts the program.
- Function: void MU_AUTH_REGISTER_ALL_MODULES (void)
This macro registers all default modules and calls
`mu_auth_init()'.
Module Creation and Destruction
===============================
- Function: int mu_auth_data_alloc (struct mu_auth_data **ptr, const
char *name, const char *passwd, uid_t uid, gid_t gid, const
char *gecos, const char *dir, const char *shell, const char
*mailbox, int change_uid)
Create a `mu_auth_data' structure and initialize it with the given
values. Returns 0 on success and 1 otherwise.
- Function: void mu_auth_data_free (struct mu_auth_data *PTR)
Free the `mu_auth_data' structure allocated by a call to
`mu_auth_data_alloc()'.
- Function: void mu_auth_register_module (struct mu_auth_module *MOD)
Register the module defined by the MOD argument.
Obtaining Authorization Information
===================================
- Function: int mu_auth_runlist (list_t FLIST, void *RETURN_DATA, void
*KEY, void *CALL_DATA);
The list is expected to contain `mu_auth_fp' pointers. Each of them
is dereferenced and executed until either the list is exhausted or
any of the functions returns non-zero, whichever occurs first. The
RETURN_DATA and KEY arguments are passed as the first two
parameters to the function (see the definition of `mu_auth_fp',
notice the footnote), the `call_data' is passed as its last
parameter.
The function returns 0 if none of the functions from `list'
succeeded, i.e. returned non-zero value. Otherwise it returns the
return code from the succeeded function.
- Function: struct mu_auth_data * mu_get_auth_by_name (const char
*USERNAME)
Search the information about given user by its username. Similar to
system's `getpwnam' call).
- Function: struct mu_auth_data * mu_get_auth_by_uid (uid_t UID)
Search the information about given user by its uid. Similar to
system's `getpwuid' call).
- Function: int mu_authenticate (struct mu_auth_data *AUTH_DATA, char
*PASS)
Authenticate the user whose data are in AUTH_DATA using password
PASS. Return 0 if the user is authenticated.
Existing Modules
================
- Function: int mu_auth_nosupport (void *return_data, void *key, void
*func_data, void *call_data);
The "not-supported" module. Always returns `ENOSYS'.
- Variable: mu_auth_system_module
This module is always registered even if `libmuauth' is not linked.
It performs usual authentication using system user database
(`/etc/password' et al.)
- Variable: mu_auth_generic_module
This module is always registered even if `libmuauth' is not linked.
Both its authorization handlers are `mu_auth_nosupport'. Its
authentication handler computes the MD5 or DES hash over the
supplied password with the seed taken from `passwd' member of its
KEY argument. Then it compares the obtained hash with the `passwd'
member itself and returns 1 if both strings match.
- Variable: mu_auth_pam_module
Implements PAM authentication. Both authorization handlers are
`mu_auth_nosupport()'.
- Variable: mu_auth_sql_module
Implements authentication and authorization via MySQL database. The
credentials for accessing the database are taken from global
variables `sql_host', `sql_port', `sql_user', `sql_passwd' and
`sql_db'. The SQL queries for retrieving user information from
global variables `sql_getpwnam_query' and `sql_getpwuid_query'.
The variable `sql_getpass_query' keeps the query used for
retrieving user's password. *Note auth::, for information on
command line options used to set these variables.
- Variable: mu_auth_virtual_module
Implements `mu_get_auth_by_name' method using virtual mail domains.
Neither `mu_get_auth_by_uid' nor `mu_authenticate' is implemented.
This module must be used together with `generic' module.
Using Libmuauth in Your Programs
================================
To link your program against `libmuauth', obtain loader arguments by
running `mailutils-config' as follows:
mailutils-config --link auth
*Note mailutils-config::, for more information about this utility.
Here is a sample Makefile fragment:
MU_LDFLAGS=`mailutils-config --link auth`
MU_INCLUDES=`mailutils-config --include`
myprog: myprog.c
$(CC) -omyprog $(CFLAGS) $(MU_INCLUDES) myprog.c $(MU_LDFLAGS)
If your program will be using only default modules provided by the
library, then it will suffice to call `MU_AUTH_REGISTER_ALL_MODULES()'
somewhere near the start of your program. As an example, consider the
following code fragment (it is taken from the `imap4d' daemon):
int
main (int argc, char **argv)
{
struct group *gr;
int status = EXIT_SUCCESS;
state = STATE_NONAUTH; /* Starting state in non-auth. */
MU_AUTH_REGISTER_ALL_MODULES ();
mu_argp_parse (&argp, &argc, &argv, 0, imap4d_capa,
NULL, &daemon_param);
...
Otherwise, if your program will use it's own modules, first register
them with `mu_auth_register_module' and then call `mu_auth_init()',
e.g.:
struct mu_auth_module radius_module = {
...
};
struct mu_auth_module ext_module = {
...
};
int
main (int argc, char **argv)
{
mu_auth_register_module (&radius_module);
mu_auth_register_module (&ext_module);
mu_auth_init ();
...
These two approaches may be combined, allowing you to use both your
modules and the ones provided by Mailutils. Consider the example below:
int
main (int argc, char **argv)
{
mu_auth_register_module (&radius_module);
mu_auth_register_module (&ext_module);
MU_AUTH_REGISTER_ALL_MODULES ();
...
}
Mailutils to Scheme interface
*****************************
The library `libmu_scm' provides an interface between Mailutils and
Guile, allowing to access the Mailutils functionality from a Scheme
program. For more information about Guile, refer to *Note Overview:
(guile)Top. For information about Scheme programming language, *Note
Top: (r4rs)Top.
Address Functions
=================
- Scheme Function: mu-address-get-personal ADDRESS NUM
Return personal part of an email address.
- Scheme Function: mu-address-get-comments ADDRESS NUM
- Scheme Function: mu-address-get-email ADDRESS NUM
Return email part of an email address.
- Scheme Function: mu-address-get-domain ADDRESS NUM
Return domain part of an email address
- Scheme Function: mu-address-get-local ADDRESS NUM
Return local part of an email address.
- Scheme Function: mu-address-get-count ADDRESS
Return number of parts in email address.
Mailbox Functions
=================
- Scheme Function: mu-mailbox-open URL MODE
Opens a mailbox specified by URL.
- Scheme Function: mu-mailbox-close MBOX
Closes mailbox MBOX
- Scheme Function: mu-mailbox-get-url MBOX
Returns the URL of the mailbox.
- Scheme Function: mu-mailbox-get-port MBOX MODE
Returns a port associated with the contents of the MBOX. MODE is
a string defining operation mode of the stream. It may contain any
of the two characters: `r' for reading, `w' for writing.
- Scheme Function: mu-mailbox-get-message MBOX MSGNO
Retrieve from MBOX message # MSGNO.
- Scheme Function: mu-mailbox-messages-count MBOX
Returns number of messages in the mailbox.
- Scheme Function: mu-mailbox-expunge MBOX
Expunges deleted messages from the mailbox.
- Scheme Function: mu-mailbox-url MBOX
Returns the URL of the mailbox
- Scheme Function: mu-mailbox-append-message MBOX MESG
Appends the message to the mailbox
Message Functions
=================
- Scheme Function: mu-message-copy MESG
Creates the copy of the given message.
- Scheme Function: mu-message-set-header MESG HEADER VALUE REPLACE
Sets new VALUE to the header HEADER of the message MESG. If the
HEADER is already present in the message its value is replaced
with the supplied one if the optional REPLACE is #t. Otherwise new
header is created and appended.
- Scheme Function: mu-message-get-size MESG
Returns the size of the given message.
- Scheme Function: mu-message-get-lines MESG
Returns number of lines in the given message.
- Scheme Function: mu-message-get-sender MESG
Returns the sender email address for the message MESG.
- Scheme Function: mu-message-get-header MESG HEADER
Returns the header value of the HEADER in the MESG.
- Scheme Function: mu-message-get-header-fields MESG HEADERS
Returns the list of headers in the MESG. If optional HEADERS is
specified it should be a list of header names to restrict return
value to.
- Scheme Function: mu-message-set-header-fields MESG LIST REPLACE
Set the headers in the message MESG from LIST LIST is a list of
(cons HEADER VALUE) Optional parameter REPLACE specifies whether
the new header values should replace the headers already present
in the message.
- Scheme Function: mu-message-delete MESG FLAG
Mark given message as deleted. Optional FLAG allows to toggle
deleted mark The message is deleted if it is #t and undeleted if
it is #f
- Scheme Function: mu-message-get-flag MESG FLAG
Return value of the attribute FLAG.
- Scheme Function: mu-message-set-flag MESG FLAG VALUE
Set the given attribute of the message. If optional VALUE is #f,
the attribute is unset.
- Scheme Function: mu-message-get-user-flag MESG FLAG
Returns value of the user attribute FLAG.
- Scheme Function: mu-message-set-user-flag MESG FLAG VALUE
Set the given user attribute of the message. If optional VALUE is
#f, the attribute is unset.
- Scheme Function: mu-message-get-port MESG MODE FULL
Returns a port associated with the given MESG. MODE is a string
defining operation mode of the stream. It may contain any of the
two characters: `r' for reading, `w' for writing. If optional
FULL argument specified, it should be a boolean value. If it is
#t then the returned port will allow access to any part of the
message (including headers). If it is #f then the port accesses
only the message body (the default).
- Scheme Function: mu-message-get-body MESG
Returns the message body for the message MESG.
- Scheme Function: mu-message-send MESG MAILER
Sends the message MESG. Optional MAILER overrides default mailer
settings in mu-mailer.
MIME Functions
==============
- Scheme Function: mu-mime-create FLAGS MESG
Creates a new MIME object.
- Scheme Function: mu-mime-multipart? MIME
Returns #t if MIME is a multipart object.
- Scheme Function: mu-mime-get-num-parts MIME
Returns number of parts in a MIME object.
- Scheme Function: mu-mime-get-part MIME PART
Returns part number PART from a MIME object.
- Scheme Function: mu-mime-add-part MIME MESG
Adds MESG to the MIME object.
- Scheme Function: mu-mime-get-message MIME
Converts MIME object to a message.
Log Functions
=============
- Scheme Function: mu-openlog IDENT OPTION FACILITY
Opens a connection to the system logger for Guile program.
- Scheme Function: mu-logger PRIO TEXT
Generates a log message to be distributed via syslogd.
- Scheme Function: mu-closelog
Closes the channel to the system logger open by mu-openlog.
Direct Linking
==============
If you plan to link your program directly to `libguile', it will
probably make sense to link `libmu_scm' directly as well. The arguments
to the program loader may be obtained by running
mailutils-config --link guile
*Note mailutils-config::, for more information about this utility.
Here is a sample Makefile fragment:
MU_LDFLAGS=`mailutils-config --link guile`
MU_INCLUDES=`mailutils-config --include`
myprog: myprog.c
$(CC) -omyprog $(CFLAGS) $(MU_INCLUDES) myprog.c $(MU_LDFLAGS)
Dynamic Linking
===============
Dynamic linking is the preferred method of using `libmu_scm'. It
uses Guile "use-modules" mechanism. An interface module `mailutils.scm'
is provided in order to facilitate using this method. This module is
installed in the package data directory (by default it is
PREFIX/share/mailutils). A sample use of this module is:
(set! %load-path (list "/usr/local/share/mailutils"))
(use-modules (mailutils))
# Now you may use mailutils functions:
(let ((mb (mu-mailbox-open "/var/spool/mail/gray" "r")))
...
_Note_, that you should explicitly modify the `%load-path' before
calling `use-modules', otherwise Guile will not be able to find
`mailutils.scm'.
Sieve Library
*************
This chapter describes GNU Sieve library.
Library Description
===================
`Libsieve' is GNU implementation of the mail filtering language
Sieve.
The library is built around a "Sieve Machine" -- an abstract
computer constructed specially to handle mail filtering tasks. This
computer has two registers: program counter and numeric accumulator; a
runtime stack of unlimited depth and the code segment. A set of
functions is provided for creating and destroying instances of Sieve
Machine, manipulating its internal data, compiling and executing a
sieve program.
The following is a typical scenario of using `libsieve':
1. Application program creates the instance of sieve machine.
2. Then `sieve_compile' function is called to translate the Sieve
source into an equivalent program executable by the Machine
3. A mailbox is opened and associated with the Machine
4. The Machine executes the program over the mailbox
5. When the execution of the program is finished, all messages upon
which an action was executed other than `keep' are marked with the
delete flag. Thus, running `mailbox_expunge' upon the mailbox
finishes the job, leaving in the mailbox only those messages that
were preserved by the filter.
6. Finally, the instance of Sieve Machine is destroyed and the
resources allocated for it are reclaimed.
The following sections describe in detail the functions from the
Sieve Library.
Sieve Data Types
----------------
- Data Type: sieve_machine_t
This is an opaque data type representing a pointer to an instance
of sieve machine. The sieve_machine_t keeps all information
necessary for compiling and executing the script.
It is created by `sieve_machine_create()' and destroyed by
`sieve_machine_destroy()'. The functions for manipulating this data
type are described in *Note Manipulating the Sieve Machine::.
- Data Type: sieve_data_type
This enumeration keeps the possible types of sieve data. These are:
`SVT_VOID'
No datatype.
`SVT_NUMBER'
Numeric type.
`SVT_STRING'
Character string.
`SVT_STRING_LIST'
A `list_t'. Each item in this list represents a character
string.
`SVT_TAG'
A sieve tag. See `sieve_runtime_tag_t' below.
`SVT_IDENT'
A character string representing an identifier.
`SVT_VALUE_LIST'
A `list_t'. Each item in this list is of `sieve_value_t'.
`SVT_POINTER'
An opaque pointer.
- Data Type: sieve_value_t
The `sieve_value_t' keeps an instance of sieve data. It is defined
as follows:
typedef struct {
sieve_data_type type; /* Type of the data */
union {
char *string; /* String value or identifier */
size_t number; /* Numeric value */
list_t list; /* List value */
sieve_runtime_tag_t *tag; /* Tag value */
void *ptr; /* Pointer value */
} v;
} sieve_value_t;
Depending on the value of `type' member, following members of the
union `v' keep the actual value:
`SVT_VOID'
Never appears.
`SVT_NUMBER'
The numeric value is kept in `number' member.
`SVT_STRING'
The string is kept in `string' member.
`SVT_STRING_LIST'
`SVT_VALUE_LIST'
The list itself is pointed to by `list' member
`SVT_TAG'
The tag value is pointed to by `tag' member.
`SVT_IDENT'
The `string' member points to the identifier name.
`SVT_POINTER'
The data are pointed to by `ptr' member.
- Data Type: sieve_tag_def_t
This structure represents a definition of a tagged (optional)
argument to a sieve action or test. It is defined as follows:
typedef struct {
char *name; /* Tag name */
sieve_data_type argtype; /* Type of tag argument. */
} sieve_tag_def_t;
The `name' member points to the tag's name _without leading
colon_. The `argtype' is set to `SVT_VOID' if the tag does not
take argument, or to the type of the argument otherwise.
- Data Type: sieve_runtime_tag_t
This structure represents the tagged (optional) argument at a
runtime. It is defined as:
struct sieve_runtime_tag {
char *tag; /* Tag name */
sieve_value_t *arg; /* Tag argument (if any) */
};
The `arg' member is `NULL' if the tag does not take an argument.
- Data Type: sieve_handler_t
This is a pointer to function handler for a sieve action or test.
It is defined as follows:
typedef int (*sieve_handler_t) (sieve_machine_t MACH,
list_t ARGS, list_t TAGS);
The arguments to the handler have the following meaning:
MACH
Sieve machine being processed.
ARGS
A list of required arguments to the handler
TAGS
A list of optional arguments (tags).
- Data Type: sieve_printf_t
A pointer to a diagnostic output function. It is defined as
follows:
typedef int (*sieve_printf_t) (void *DATA, const char *FMT, va_list AP);
DATA
A pointer to application specific data. These data are passed as
second argument to `sieve_machine_init()'.
FMT
Printf-like format string.
AP
Other arguments.
- Data Type: sieve_parse_error_t
This data type is declared as follows:
typedef int (*sieve_parse_error_t) (void *DATA,
const char *FILENAME, int LINENO,
const char *FMT, va_list AP);
It is used to declare error handlers for parsing errors. The
application-specific data are passed in the DATA argument. Arguments
FILENAME and LINE indicate the location of the error in the source
text, while FMT and AP give verbose description of the error.
- Data Type: sieve_action_log_t
A pointer to the application-specific logging function:
typedef void (*sieve_action_log_t) (void *DATA,
const char *SCRIPT,
size_t MSGNO, message_t MSG,
const char *ACTION,
const char *FMT, va_list AP);
DATA
Application-specific data.
SCRIPT
Name of the sieve script being executed.
MSGNO
Ordinal number of the message in mailbox, if appropriate. When
execution is started using `sieve_message()', this argument is
zero.
MSG
The message this action is executed upon.
ACTION
The name of the action.
FMT
VAR
These two arguments give the detailed description of the action.
- Data Type: sieve_comparator_t
typedef int (*sieve_comparator_t) (const char *, const char *);
A pointer to the comparator handler function. The function compares
its two operands and returns 1 if they are equal, and 0 otherwise.
_Notice_, that the sense of the return value is inverted in
comparison with most standard libc functions like `stcmp()', etc.
- Data Type: sieve_retrieve_t
typedef int (*sieve_retrieve_t) (void *item, void *data, int idx,
char **pval);
A pointer to generic retriever function. See description of
`sieve_vlist_compare()' for details of its usage.
- Data Type: sieve_destructor_t
typedef void (*sieve_destructor_t) (void *data);
A pointer to destructor function. The function frees any resources
associated with `data'. See the description of
`sieve_machine_add_destructor()' for more information.
- Data Type: sieve_tag_checker_t
typedef int (*sieve_tag_checker_t) (const char *NAME,
list_t TAGS,
list_t ARGS)
A pointer to tag checker function. The purpose of the function is
to perform compilation-time consistency test on tags. Its
arguments are:
NAME
Name of the test or action whose tags are being checked.
TAGS
A list of `sieve_runtime_tag_t' representing tags.
ARGS
A list of `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]
Manipulating the Sieve Machine
------------------------------
This subsection describes functions used to create an instance of the
sieve machine, read or alter its internal fields and destroy it.
- Function: int sieve_machine_init (sieve_machine_t *MACH, void *DATA)
The `sieve_machine_init()' function creates an instance of a sieve
machine. A pointer to the instance itself is returned in the
argument MACH. The user-specific data to be associated with the
new machine are passed in DATA argument. The function returns 0 on
success, non-zero error code otherwise,
- Function: void sieve_machine_destroy (sieve_machine_t *PMACH)
This function destroys the instance of sieve machine pointed to by
MACH parameter. After execution of `sieve_machine_destroy()' PMACH
contains `NULL'. The destructors registered with
`sieve_machine_add_destructor()' are executed in LIFO order.
- Function: int sieve_machine_add_destructor (sieve_machine_t MACH,
sieve_destructor_t DESTR, void *PTR);
This function registers a destructor function DEST. The purpose of
the destructor is to free any resources associated with the item
PTR. The destructor function takes a single argument -- a pointer
to the data being destroyed. All registered destructors are called
in reverse order upon execution of `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 = sieve_malloc (mach, sizeof (*regex));
/* Make sure it will be freed when necessary */
sieve_machine_add_destructor (sieve_machine, free_regex, regex);
.
.
.
}
- Function: void *sieve_get_data (sieve_machine_t MACH)
This function returns the application-specific data associated with
the instance of sieve machine. See `sieve_machine_init()'.
- Function: message_t sieve_get_message (sieve_machine_t MACH)
This function returns the current message.
- Function: size_t sieve_get_message_num (sieve_machine_t MACH);
This function returns the current message number in the mailbox.
If there are no mailbox, i.e. the execution of the sieve code is
started with `sieve_message', this function returns 1.
- Function: int sieve_get_debug_level (sieve_machine_t MACH)
Returns the debug level set for this instance of sieve machine.
- Function: ticket_t sieve_get_ticket (sieve_machine_t MACH)
Returns the authentication ticket for this machine.
- Function: mailer_t sieve_get_mailer (sieve_machine_t MACH)
Returns the mailer.
- Function: char * sieve_get_daemon_email __P((sieve_machine_t MACH)
This function returns the "daemon email" associated with this
instance of sieve machine. The daemon email is an email address
used in envelope from addresses of automatic reply messages. By
default its local part is `<MAILER-DAEMON>' and the domain part is
the machine name.
- Function: void sieve_set_error (sieve_machine_t MACH, sieve_printf_t
ERROR_PRINTER)
This function sets the error printer function for the machine. If
it is not set, the default error printer will be used. It is
defined as follows:
int
_sieve_default_error_printer (void *unused, const char *fmt,
va_list ap)
{
return mu_verror (fmt, ap);
}
- Function: void sieve_set_parse_error (sieve_machine_t MACH,
sieve_parse_error_t P)
This function sets the parse error printer function for the
machine. If it is not set, the default parse error printer will be
used. It is defined as follows:
int
_sieve_default_parse_error (void *unused,
const char *filename, int lineno,
const char *fmt, va_list ap)
{
if (filename)
fprintf (stderr, "%s:%d: ", filename, lineno);
vfprintf (stderr, fmt, ap);
fprintf (stderr, "\n");
return 0;
}
- Function: void sieve_set_debug (sieve_machine_t MACH, sieve_printf_t
DEBUG));
This function sets the debug printer function for the machine. If
it is not set, the default debug printer is `NULL' which means no
debugging information will be displayed.
- Function: void sieve_set_debug_level (sieve_machine_t MACH,
mu_debug_t DBG, int LEVEL)
This function sets the debug level for the given instance of sieve
machine. The DBG argument is the `mu_debug_t' object to be used
with mailutils library, the LEVEL argument specifies the debugging
level for the sieve library itself. It is a bitwise or of the
following values:
`MU_SIEVE_DEBUG_TRACE'
Trace the execution of the sieve script.
`MU_SIEVE_DEBUG_INSTR'
Print the sieve machine instructions as they are executed.
`MU_SIEVE_DEBUG_DISAS'
Dump the disassembled code of the sieve machine. Do not run
it.
`MU_SIEVE_DRY_RUN'
Do not executed the actions, only show what would have been
done.
- Function: void sieve_set_logger (sieve_machine_t MACH,
sieve_action_log_t LOGGER)
This function sets the logger function. By default the logger
function is `NULL', which means that the executed actions are not
logged.
- Function: void sieve_set_ticket (sieve_machine_t MACH, ticket_t
TICKET)
This function sets the authentication ticket to be used with this
machine.
- Function: void sieve_set_mailer (sieve_machine_t MACH, mailer_t
MAILER)
This function sets the mailer. The default mailer is `"sendmail:"'.
- Function: void sieve_set_daemon_email (sieve_machine_t MACH, const
char *EMAIL)
This functions sets the "daemon email" for `reject' and `redirect'
actions.
- Function: int sieve_is_dry_run (sieve_machine_t MACH)
The `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 `sieve_set_debug_level()' if its last argument has the
`MU_SIEVE_DRY_RUN' bit set.
- Function: const char * sieve_type_str (sieve_data_type TYPE)
Returns the string representation for the given sieve data type.
The return value is a pointer to a static constant string.
Logging and Diagnostic Functions
--------------------------------
- Function: void sieve_error (sieve_machine_t MACH, const char *FMT,
...)
Format and output an error message using error printer of the
machine MACH.
- Function: void sieve_debug (sieve_machine_t MACH, const char *FMT,
...)
Format and output a debug message using debug printer of the
machine MACH.
- Function: void sieve_log_action (sieve_machine_t MACH, const char
*ACTION, const char *FMT, ...)
Log a sieve action using logger function associated with the
machine MACH.
- Function: void sieve_abort (sieve_machine_t MACH)
Immediately abort the execution of the script.
Symbol Space Functions
----------------------
- Function: sieve_register_t * sieve_test_lookup (sieve_machine_t
MACH, const char *NAME)
Find a register object describing the test NAME. Returns `NULL' if
no such test exists.
- Function: sieve_register_t * sieve_action_lookup (sieve_machine_t
MACH, const char *NAME)
Find a register object describing the action NAME. Returns `NULL'
if no such action exists.
- Function: int sieve_register_test (sieve_machine_t MACH, const char
*NAME, sieve_handler_t HANDLER, sieve_data_type *ARG_TYPES,
sieve_tag_group_t *TAGS, int REQUIRED)
- Function: int sieve_register_action (sieve_machine_t MACH, const
char *NAME, sieve_handler_t HANDLER, sieve_data_type
*ARG_TYPES, sieve_tag_group_t *TAGS, int REQUIRED)
- Function: int sieve_register_comparator (sieve_machine_t MACH, const
char *NAME, int REQUIRED, sieve_comparator_t IS,
sieve_comparator_t CONTAINS, sieve_comparator_t MATCHES,
sieve_comparator_t REGEX)
- Function: int sieve_tag_lookup (list_t TAGLIST, char *NAME,
sieve_value_t **ARG)
- Function: int sieve_load_ext (sieve_machine_t MACH, const char *NAME)
Memory Allocation
-----------------
The following functions act as their libc counterparts. The allocated
memory is associated with the MACH argument and is automatically freed
upon the call to `sieve_machine_destroy (MACH)'.
- Function: void * sieve_malloc (sieve_machine_t MACH, size_t SIZE)
Allocates SIZE bytes and returns a pointer to the allocated memory.
- Function: char * sieve_mstrdup (sieve_machine_t MACH, const char
*STR)
This function returns a pointer to a new string which is a
duplicate of the string STR.
- Function: void * sieve_mrealloc (sieve_machine_t MACH, void *PTR,
size_t SIZE)
Changes the size of the memory block pointed to by PTR to SIZE
bytes. The contents will be unchanged to the minimum of the old
and new sizes; newly allocated memory will be uninitialized. If
PTR is `NULL', the call is equivalent to `sieve_malloc(MACH,
SIZE)'; if SIZE is equal to zero, the call is equivalent to
`sieve_mfree(PTR)'. Unless PTR is `NULL', it must have been
returned by an earlier call to `sieve_malloc()' or
`sieve_mrealloc()'.
- Function: void sieve_mfree (sieve_machine_t MACH, void *PTR)
`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 `sieve_malloc()' or
`sieve_mrealloc()'. Otherwise, or if `sieve_mfree(PTR)' has
already been called before, undefined behaviour occurs.
If PTR is `NULL', no operation is performed.
Compiling and Executing the Script
----------------------------------
- Function: int sieve_compile (sieve_machine_t MACH, const char *NAME)
Compile the sieve script from the file NAME.
- Function: int sieve_mailbox (sieve_machine_t MACH, mailbox_t MBOX)
Execute the code from the given instance of sieve machine MACH
over each message in the mailbox MBOX.
- Function: int sieve_message (sieve_machine_t MACH, message_t MESSAGE)
Execute the code from the given instance of sieve machine MACH
over the MESSAGE.
- Function: int sieve_disass (sieve_machine_t MACH)
Dump the disassembled code of the sieve machine MACH.
Input Language
==============
The input language understood by the GNU Sieve Library is a superset
of the Sieve language as described in RFC 3028.
Lexical Structure
-----------------
Whitespace and Comments
-----------------------
Comments are semantically equivalent to whitespace and can be used
anyplace that whitespace is (with one exception in multi-line strings,
as described below).
There are two kinds of comments: hash comments, that begin with a
`#' character that is not contained within a string and continue until
the next newline, and C-style or bracketed comments, that are delimited
by `/*' and `*/' tokens. The bracketed comments may span multiple
lines. E.g.:
if size :over 100K
{ # this is a comment
discard;
}
if size :over 100K
{ /* this is a comment
this is still a comment */ discard /* this is a comment again
*/ ;
}
Like in C, bracketed comments do not nest.
Lexical Tokens
--------------
The basic lexical entities are "identifiers" and "literals".
An "identifier" is a sequence of letters, digits and underscores,
started with a letter or underscore. For example, `header' and
`check_822_again' are valid identifiers, whereas `1st' is not. A
special form of identifier is "tag": it is an identifier prefixed with
a colon (`:'), e.g.: `:comparator'.
A "literal" is a data that is not executed, merely evaluated "as
is", to be used as arguments to commands. There are four kinds of
literals:
* Number
"Numbers" are given as ordinary unsigned decimal numbers. An
optional suffix may be used to indicate a multiple of a power of
two. The suffixes are: `K' specifying "kibi-", or 1,024 (2^10)
times the value of the number; `M' specifying "mebi-", or 1,048,576
(2^20) times the value of the number; and `G' specifying "tebi-",
or 1,073,741,824 (2^30) times the value of the number.
The numbers have 32 bits of magnitude.
* String
A "string" is any sequence of characters enclosed in double quotes
(`"'). A string cannot contain newlines and double quote
characters. This limitation will disappear in future releases.
* Multiline Strings
A "multiline string" is used to represent large blocks of text
with embedded newlines and special characters. It starts with the
keyword `text:' followed by a newline and ends with a dot (`.') on
a newline by itself. Any characters between these two markers are
taken verbatim. For example:
text:
** This is an authomatic response from my message **
** filtering program. **
I can not attend your message right now. However it
will be saved, and I will read it as soon as I am back.
Regards,
Fred
.
Notice that a hashed comment or whitespace may occur between
`text:' and the newline. However, when used inside the multiline
string a hash sign looses its special meaning (except in one case,
see below) and is taken as is, as well as bracketed comment
delimiters. In other words, no comments are allowed within a
multiline string. E.g.:
text: # This is a comment
Sample text
# This line is taken verbatim
/* And this line too */
.
The only exception to this rule is that preprocessor `include'
statement is expanded as usual when found within a multiline string
(*note #include::), 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.
* String Lists
A "string list" is a comma-delimited list of quoted strings,
enclosed in a pair of square brackets, e.g.:
["me@example.com", "me00@landru.example.edu"]
For convenience, in any context where a list of strings is
appropriate, a single string is allowed without being a member of
a list: it is equivalent to a list with a single member. For
example, the following two statements are equivalent:
exists "To";
exists ["To"];
Syntax
------
Being designed for the sole purpose of filtering mail, Sieve has a
very simple syntax.
Commands
........
The basic syntax element is a "command". It is defined as follows:
COMMAND-NAME [TAGS] ARGS
where COMMAND-NAME is an identifier representing the name of the
command, TAGS is an optional list of "optional" or "tagged arguments"
and ARGS is a list of "required" or "positional arguments".
Positional arguments are literals delimited with whitespace. They
provide the command with the information necessary to its proper
functioning. Each command has a fixed number of positional arguments. It
is an error to supply more arguments to the command or to give it fewer
arguments than it accepts.
Optional arguments allow to modify the behaviour of the command, like
command line options in UNIX do. They are a list of "tags" (*note
Lexical Structure::) separated by whitespace. An optional argument may
have at most one parameter.
Each command understands a set of optional arguments. Supplying it
tags that it does not understand results in an error.
For example, consider the following command
header :mime :comparator "i;octet" ["to", "from"] "bug-mailutils@gnu.org"
Here, given that `header' takes two positional arguments: `header' is
command name, the list `["to", "from"]' is first positional argument
and the string `"bug-mailutils@gnu.org"' is second positional argument.
There are two optional arguments: `:mime' and `:comparator'. The latter
has a string `"i;octet"' as its parameter.
Actions Described
.................
An "action" is a Sieve command that performs some operation over the
message. Actions do the main job in any Sieve program. Syntactically,
an action is a command terminated with semicolon, e.g.:
keep;
fileinto "mbox";
GNU Sieve provides the full set of actions described in RFC 3028.
It also allows to extend this set using loadable actions. *Note
Actions::, for detailed discussion of actions.
Control Flow
............
The only control flow statement Sieve has is "if" statement. In its
simplest form it is:
if `condition' { ... }
The effect of this statement is that the sequence of actions between
the curly braces is executed only if the `condition' evaluates to
`true'.
A more elaborate form of this statement allows to execute two
different sets of actions depending on whether the condition is true or
not:
if `condition' { ... } else { ... }
The most advanced form of the "if" statement allows to select an
action depending on what condition from the set of conditions is met.
if `cond1' { ... } elsif `cond2' { ... } else { ... }
There may be any number of "elsif" branches in an "if" statement.
However it may have at most one "else" branch. Notes for C programmers:
1. The braces surrounding each branch of an "if" statement are
required.
2. The "else if" construct is disallowed. Use "elsif" keyword instead.
Here's an example of "if" statement:
if header :contains "from" "coyote"
{
discard;
}
elsif header :contains ["subject"] ["$$$"]
{
discard;
}
else
{
fileinto "INBOX";
}
The following section describes in detail conditions used in "if"
statements.
Tests and Conditions
....................
"Tests" are Sieve commands that return boolean value. E.g. the test
header :contains "from" "coyote"
returns true only if the header "From" of the current message contains
substring "coyote".
The tests shipped with the GNU Sieve are described in *Note Tests::.
"Condition" is a Sieve expression that evaluates to `true' or
`false'. In its simplest form, condition is just a Sieve test.
To reverse the sense of a condition use keyword `not', e.g.:
not header :contains "from" "coyote"
The results of several conditions may be joined together by logical
`and' and `or' operations. The special form `allof' takes several tests
as its arguments and computes the logical `and' of their results.
Similarly, the form `anyof' performs logical `or' over the results of
its arguments. E.g.:
if anyof (not exists ["From", "Date"],
header :contains "from" "fool@example.edu")
{
discard;
}
Preprocessor
------------
The preprocessor statements are a GNU extension to the Sieve
language. The syntax for a preprocessor statement is similar to that
used in `C' programming language, i.e.: a pound character (`#')
followed by a preprocessor directive and its arguments. Any amount of
whitespace can be inserted between the `#' and the directive.
Currently implemented directives are `include' and `searchpath'.
Sieve #include directive
........................
The `#include' directive reads in the contents of the given file.
The contents is "inserted" into the text being parsed starting at the
line where the directive appears. The directive takes two forms:
`#include "FILENAME"'
The FILENAME is taken relative to the current directory.
`#include <FILENAME>"'
The FILENAME is searched in the list of include directories as
specified by the `-I' command line options.
If FILENAME starts with a directory separator character (`/') both
forms have the same effect.
Sieve #searchpath directive
...........................
The `#searchpath' directive adds its argument to the list of
directories searched for loadable modules. It has the same effect as
`-L' command line switch used by GNU sieve utility (*note sieve
group::).
Require Statement
-----------------
Syntax: require STRING;
require STRING-LIST;
The require statement informs the parser that a script makes use of
a certain extension. Multiple capabilities can be declared using the
second form of the statement. The actual handling of a capability name
depends on its suffix.
If the name starts with `comparator-', it is understood as a request
to use the specified comparator. The comparator name consists of the
characters following the suffix.
If the name starts with `test-', it means a request to use the given
test. The test name consists of the characters following the suffix.
Otherwise, the capability is understood as a name of an action to be
used.
The `require' statement, if present, must be used before any other
statement that is using the required capability. As an extension, the
GNU sieve allows the `require' and any other statements to be
interspersed.
By default the following actions and comparators are always required:
* stop
* keep
* discard
* i;octet
* i;ascii-casemap
Example:
require ["fileinto", "reject"];
require "fileinto";
require "comparator-i;ascii-numeric";
When processing arguments for `require' statement, GNU libsieve uses
the following algorithm:
1. Look up the name in a symbol table. If the name begins with
`comparator-' it is looked up in the comparator table. If it
begins with `test-', the test table is used instead. Otherwise the
name is looked up in the action table.
2. If the name is found, the search is terminated.
3. Otherwise, transform the name. First, any `comparator-' or `test-'
prefix is stripped. Then, any character other than alphanumeric
characters, `.' and `,' is replaced with dash (`-'). The name thus
obtained is used as a file name of an external loadable module.
4. Try to load the module. The module is searched in the following
search paths (in the order given):
1. Mailutils module directory. By default it is
`$prefix/lib/mailutils'.
2. Sieve library path as given with the `-L' options in the
command line
3. Additional search directories specified with the
`#searchpath' directive.
4. The value of the environment variable LTDL_LIBRARY_PATH.
5. System library search path: The system dependent library
search path (e.g. on Linux it is set by the contents of the
file `/etc/ld.so.conf' and the value of the environment
variable LD_LIBRARY_PATH).
The value of LTDL_LIBRARY_PATH and LD_LIBRARY_PATH must be a
colon-separated list of absolute directories, for example,
`"/usr/lib/mypkg:/lib/foo"'.
In any of these directories, `libsieve' first attempts to find and
load the given filename. If this fails, it tries to append the
following suffixes to the file name:
1. the libtool archive extension `.la'
2. the extension used for native dynamic libraries on the host
platform, e.g., `.so', `.sl', etc.
5. If the module is found, `libsieve' executes its initialization
function (see below) and again looks up the name in the symbol
table. If found, search terminates successfully.
6. If either the module is not found, or the symbol wasn't found
after execution of the module initialization function, search is
terminated with an error status. `libsieve' then issues the
following diagnostic message:
source for the required action NAME is not available
Comparators
-----------
GNU libsieve supports the following built-in comparators:
`i;octet'
This comparator simply compares the two arguments octet by octet
`i;ascii-casemap'
It treats uppercase and lowercase characters in the ASCII subset of
UTF-8 as the same. This is the default comparator.
`i;ascii-numeric'
Treats the two arguments as ASCII representation of decimal
numbers and compares their numeric values. This comparator must be
explicitly required prior to use.
Tests
-----
This section describes the built-in tests supported by GNU libsieve.
In the discussion below the following macro-notations are used:
MATCH-TYPE
This tag specifies the matching type to be used with the test. It
can be one of the following:
`:is'
The `:is' match type describes an absolute match; if the
contents of the first string are absolutely the same as the
contents of the second string, they match. Only the string
"frobnitzm" is the string "frobnitzm". The null key ":is"
and only ":is" the null value. This is the default
match-type.
`:contains'
The `:contains' match type describes a substring match. If
the value argument contains the key argument as a substring,
the match is true. For instance, the string "frobnitzm"
contains "frob" and "nit", but not "fbm". The null key "" is
contained in all values.
`:matches'
The `:matches' version specifies a wildcard match using the
characters `*' and `?'. `*' matches zero or more characters,
and `?' matches a single character. `?' and `*' may be
escaped as `\\?' and `\\*' in strings to match against
themselves. The first backslash escapes the second backslash;
together, they escape the `*'.
`:regex'
The `:regex' version specifies a match using POSIX Extended
Regular Expressions.
COMPARATOR
A COMPARATOR syntax item is defined as follows:
:comparator "COMPARATOR-NAME"
It instructs sieve to use the given comparator with the test. If
COMPARATOR-NAME is not one of `i;octet', `i;ascii-casemap' it must
be required prior to using it. For example:
require "comparator-i;ascii-numeric";
if header :comparator "i;ascii-numeric" :is "X-Num" "10"
{
...
ADDRESS-PART
This syntax item is used when testing structured Internet
addresses. It specifies which part of an address must be used in
comparisons. Exactly one of the following tags may be used:
`:all'
Use the whole address. This is the default.
`:localpart'
Use local part of the address.
`:domain'
Use domain part of the address.
_Notice_, that MATCH-TYPE modifiers interact with comparators. Some
comparators are not suitable for matching with `:contains' or
`:matches'. If this occurs, sieve issues an appropriate error message.
For example, the statement:
if header :matches :comparator "i;ascii-numeric"
would result in the following error message:
comparator `i;ascii-numeric' is incompatible with match type `:matches'
in call to `header'
- Test: false
This test always evaluates to "false".
- Test: true
This test always evaluates to "true".
- Test: address [ADDRESS-PART][COMPARATOR][MATCH-TYPE] HEADER-NAMES
KEY-LIST
Tagged arguments:
ADDRESS-PART
Selects the address part to compare. Default is the whole
email address (`:all').
COMPARATOR
Specifies the comparator to be used instead of the default
`i;ascii-casemap'.
MATCH-TYPE
Specifies the match type to be used instead of the default
`:is'.
Required arguments:
HEADER-NAMES
A list of header names.
KEY-LIST
A list of address values.
The `address' test matches Internet addresses in structured headers
that contain addresses. It returns `true' if any header contains
any key in the specified part of the address, as modified by
COMPARATOR and MATCH-TYPE optional arguments.
This test returns `true' if any combination of the HEADER-NAMES
and KEY-LIST arguments match.
The `address' primitive never acts on the phrase part of an email
address, nor on comments within that address. Use the `header' test
instead. It also never acts on group names, although it does act
on the addresses within the group construct.
Example:
if address :is :all "from" "tim@example.com"
{
discard;
}
- Test: size [:over|:under] NUMBER
The `size' test deals with the size of a message. The required
argument NUMBER represents the size of the message in bytes. It
may be suffixed with the following quantifiers:
`k'
`K'
The number is expressed in kilobytes.
`m'
`M'
The number is expressed in megabytes.
`g'
`G'
The number is expressed in gigabytes.
If the tagged argument is `:over', and the size of the message is
greater than NUMBER, the test is true; otherwise, it is false.
If the argument is `:under', and the size of the message is less
than the NUMBER, the test is true; otherwise, it is false.
Otherwise, the test is true only if the size of the message equals
exactly NUMBER. This is a GNU extension.
The size of a message is defined to be the number of octets from
the initial header until the last character in the message body.
- Test: envelope [ADDRESS-PART][COMPARATOR][MATCH-TYPE] ENVELOPE-PART
KEY-LIST
Tagged arguments:
ADDRESS-PART
Selects the address part to compare. Default is the whole
email address (`:all').
COMPARATOR
Specifies the comparator to be used instead of the default
`i;ascii-casemap'.
MATCH-TYPE
Specifies the match type to be used instead of the default
`:is'.
Required arguments:
ENVELOPE-PARTS
A list of envelope parts to operate upon.
KEY-LIST
A list of address values.
The `envelope' test is true if the specified part of the SMTP
envelope matches the specified key.
If the envelope-part strings is (case insensitive) `from', then
matching occurs against the FROM address used in the `SMTP MAIL'
command.
_Notice_, that due to the limitations imposed by SMTP envelope
structure the use of any other values in ENVELOPE-PARTS header is
meaningless.
- Test: exists HEADER-NAMES
Required arguments:
HEADER-NAMES
List of message header names.
The `exists' test is `true' if the headers listed in HEADER-NAMES
argument exist within the message. All of the headers must exist
or the test is false.
The following example throws out mail that doesn't have a From
header and a Date header:
if not exists ["From","Date"]
{
discard;
}
- Test: header [COMPARATOR] [MATCH-TYPE] [:mime] HEADER-NAMES KEY-LIST
Tagged arguments:
COMPARATOR
Specifies the comparator to be used instead of the default
`i;ascii-casemap'.
MATCH-TYPE
Specifies the match type to be used instead of the default
`:is'.
:mime
This tag instructs `header' to search through the mime
headers in multipart messages as well.
Required arguments:
HEADER-NAMES
A list of header names.
KEY-LIST
A list of header values.
The `header' test evaluates to true if any header name matches any
key. The type of match is specified by the optional match
argument, which defaults to ":is" if not explicitly given.
The test returns `true' if any combination of the HEADER-NAMES and
KEY-LIST arguments match.
If a header listed in HEADER-NAMES exists, it contains the null
key (`""'). However, if the named header is not present, it does
not contain the null key. So if a message contained the header
X-Caffeine: C8H10N4O2
these tests on that header evaluate as follows:
header :is ["X-Caffeine"] [""] => false
header :contains ["X-Caffeine"] [""] => true
- Test: numaddr [:over|:under] HEADER-NAMES NUMBER
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 NUMBER, the test is true; otherwise, it is false.
If the tagged argument is `:under' and the number of addresses is
less than NUMBER, the test is true; otherwise, it is false.
If the tagged argument is not given, `:over' is assumed.
Actions
-------
The GNU libsieve supports the following default actions:
* stop
* keep
* discard
* fileinto
* reject
* redirect
Among them the first three actions do not need to be explicitly
required by a `require' statement, while the others do.
These actions are described in detail below.
- Action: stop
The `stop' action ends all processing. If no actions have been
executed, then the `keep' action is taken.
- Action: keep
The effect of this action is to preserve the current message in the
mailbox. This action is executed if no other action has been
executed.
- Action: discard
`Discard' silently throws away the current message. No notification
is returned to the sender, the message is deleted from the mailbox.
Example:
if header :contains ["from"] ["idiot@example.edu"]
{
discard;
}
- Action: fileinto FOLDER
Required arguments:
FOLDER
A string representing the folder name
The `fileinto' action delivers the message into the specified
folder.
- Action: reject REASON
The optional `reject' action refuses delivery of a message by
sending back a message delivery notification to the sender. It
resends the message to the sender, wrapping it in a "reject" form,
noting that it was rejected by the recipient. The required
argument REASON is a string specifying the reason for rejecting
the message.
Example:
If the message contained
Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST)
From: coyote@desert.example.org
To: roadrunner@acme.example.com
Subject: I have a present for you
I've got some great birdseed over here at my place.
Want to buy it?
and the user's script contained:
if header :contains "from" "coyote@desert.example.org"
{
reject "I am not taking mail from you, and I don't want
your birdseed, either!";
}
then the original sender <coyote@desert.example.org> would receive
the following notification:
To: <coyote@desert.example.org>
X-Authentication-Warning: roadrunner set sender using -f flag
Content-Type: multipart/mixed; boundary=----- =_aaaaaaaaaa0
MIME-Version: 1.0
----- =_aaaaaaaaaa0
The original message was received at
Tue, 1 Apr 1997 09:07:15 -0800 from
coyote@desert.example.org.
Message was refused by recipient's mail filtering program.
Reason given was as follows:
I am not taking mail from you, and I don't want your birdseed, either!
----- =_aaaaaaaaaa0
Content-Type: message/delivery-status
Reporting-UA: sieve; GNU Mailutils 0.1.3
Arrival-Date: Tue, 1 Apr 1997 09:07:15 -0800
Final-Recipient: RFC822; roadrunner@acme.example.com
Action: deleted
Disposition: automatic-action/MDN-sent-automatically;deleted
Last-Attempt-Date: Tue, 1 Apr 1997 09:07:15 -0800
----- =_aaaaaaaaaa0
Content-Type: message/rfc822
From: coyote@desert.example.org
To: roadrunner@acme.example.com
Subject: I have a present for you
I've got some great birdseed over here at my place.
Want to buy it?
----- =_aaaaaaaaaa0
If the REASON argument is rather long, the common approach is to
use the combination of the `text:' and `#include' keywords, e.g.:
if header :mime :matches "Content-Type"
[ "*application/msword;*", "*audio/x-midi*" ]
{
reject text:
#include "nomsword.txt"
.
;
}
- Action: redirect ADDRESS
The `redirect' action is used to send the message to another user
at a supplied ADDRESS, as a mail forwarding feature does. This
action makes no changes to the message body or existing headers,
but it may add new headers. It also modifies the envelope
recipient.
The `redirect' command performs an MTA-style "forward" -- that is,
what you get from a `.forward' file using `sendmail' under UNIX.
The address on the SMTP envelope is replaced with the one on the
`redirect' command and the message is sent back out. _Notice_,
that it differs from the MUA-style forward, which creates a new
message with a different sender and message ID, wrapping the old
message in a new one.
Extensions
==========
This section summarizes the GNU extensions to the sieve language
1. Handling of the `require' statement.
* According to the RFC an error must occur if a `require'
appears after a command other than `require'. The GNU sieve
library allows interspersing the `require' and other
statements. The only requirement is that `require' must occur
before a statement that is using the required capability
(*note Require Statement::).
* Prefixing the required capability with "test" requires the use
of an extension test.
2. `header' test
The `header' takes an optional argument `:mime', meaning to scan
the headers from each part of a multipart message.
3. `size' test
The `size' test allows to omit the optional argument
(:over|:under). In this case exact equality is assumed.
4. `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.
5. Match type optional argument.
Along with the usual `:is', `:matches' and `contains' matching
type, GNU sieve library understands `:regex' type. This matching
type toggles POSIX Extended Regular Expression matching.
Writing Loadable Commands
=========================
This section contains an example of how to write external loadable
commands for GNU libsieve.
/* This is an example on how to write extension tests for GNU sieve.
It provides test "numaddr".
Syntax: numaddr [":over" / ":under"] <header-names: string-list>
<limit: number>
The "numaddr" test counts Internet addresses in structured headers
that contain addresses. It returns true if the total number of
addresses satisfies the requested relation:
If the argument is ":over" and the number of addresses is greater than
the number provided, the test is true; otherwise, it is false.
If the argument is ":under" and the number of addresses is less than
the number provided, the test is true; otherwise, it is false.
If the argument is empty, ":over" is assumed. */
#ifdef HAVE_CONFIG_H
# include <config.h>
#endif
#include <stdlib.h>
#include <mailutils/libsieve.h>
struct val_ctr { /* Data passed to the counter function */
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;
address_t addr;
size_t count = 0;
if (header_aget_value (vp->hdr, name, &val))
return 0;
if (address_create (&addr, val) == 0)
{
address_get_count (addr, &count);
address_destroy (&addr);
vp->count += count;
}
free (val);
return vp->count >= vp->limit;
}
/* Handler for the numaddr test */
static int
numaddr_test (sieve_machine_t mach, list_t args, list_t tags)
{
sieve_value_t *h, *v;
struct val_ctr vc;
int rc;
if (sieve_get_debug_level (mach) & MU_SIEVE_DEBUG_TRACE)
sieve_debug (mach, "NUMADDR\n");
/* Retrieve required arguments: */
/* First argument: list of header names */
h = sieve_value_get (args, 0);
if (!h)
{
sieve_error (mach, "numaddr: can't get argument 1");
sieve_abort (mach);
}
/* Second argument: Limit on the number of addresses */
v = sieve_value_get (args, 1);
if (!v)
{
sieve_error (mach, "numaddr: can't get argument 2");
sieve_abort (mach);
}
/* Fill in the val_ctr structure */
message_get_header (sieve_get_message (mach), &vc.hdr);
vc.count = 0;
vc.limit = v->v.number;
/* Count the addresses */
rc = 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 (sieve_tag_lookup (tags, "under", NULL))
rc = !rc;
return rc;
}
/* Syntactic definitions for the numaddr test */
/* Required arguments: */
static sieve_data_type numaddr_req_args[] = {
SVT_STRING_LIST,
SVT_NUMBER,
SVT_VOID
};
/* Tagged arguments: */
static sieve_tag_def_t numaddr_tags[] = {
{ "over", SVT_VOID },
{ "under", SVT_VOID },
{ NULL }
};
static 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) (sieve_machine_t mach)
{
return sieve_register_test (mach, "numaddr", numaddr_test,
numaddr_req_args, numaddr_tag_groups, 1);
}
Programs
********
GNU Mailutils provides a set of programs for handling the email.
Authorization and authentication principles.
============================================
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 either a
one of them succeeds or the list is exhausted. In 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.
We represent the module lists as column-separated lists of module
names. 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 modules available for use in authorization list are:
system
User credentials are retrieved from the system user database
(`/etc/password').
sql
User credentials are retrieved from the sql database. The set of
`--sql-' options (*note auth::) is used to configure access to the
database.
virtdomain
User credentials are retrieved from a "virtual domain" user
database.
The modules available for use in authentication list are:
generic
The generic authentication type. User password is hashed and
compared against the hash value returned in authorization stage.
system
The hashed value of the user password is retrieved from
`/etc/shadow' file on systems that support it.
sql
The hashed value of the user password is retrieved from the sql
database using query supplied by `--sql-getpass' option (*note
auth::).
pam
The user is authenticated via pluggable authentication module
(pam). The pam service name to be used is configured via
`--pam-service' option (*note auth::)
Unless overridden by `--authentication' command line option, the
list of authentication modules is:
generic:system:pam:sql
Unless overridden by `--authorization' command line option, the list of
authorization modules is:
system:sql:virtdomains
Mailutils configuration file
============================
There are some command line options that are used so often that it is
inconvenient to specify them in the command line each time you run a
Mailutils utility. The "configuration files" provide a way to add
default command line arguments without having to type them in the
command line. Upon startup, each Mailutils utility scans and processes
the contents of the three startup files, none of which are required to
exist:
1. the site-wide configuration file
`mailutils.rc', found in your your system configuration directory
(usually `/etc' or `/usr/local/etc').
2. the user-specific configuration file
Usually `~/.mailutils', unless `~/.mailutils' is a directory, in
which case `~/.mailutils/mailutils' is used.
3. the programs-specific configuration file
Usually `~/.mu.PROGRAMrc', unless `~/.mailutils' is a directory,
in which case `~/.mailutils/PROGRAMrc' is used (where PROGRAM
means the program name).
These files have simple line-oriented syntax. Comments begin with the
pound sign (`#') and extend through the end of the line (1). Very long
lines may be split across several lines by escaping final newline with
a backslash (`\') character.
In the non-program-specific configuration files, any configuration
line must start with a "tag". In the program-specific configuration
file the tag must not be present, all options are for that specific
program.
A tag is either a name of a particular Mailutils utility or "option
group", prefixed with colon (`:'). The command line options common for
several Mailutils programs are divided into "option groups" or
"capabilities", e.g. the options `--mail-spool' and `--lock-flags' form
group `mailbox'. These groups are discussed in detail below.
When processing the non-program-specific configuration files, a
Mailutils utility selects those lines whose tag is either the name of
that utility or the name of the option group supported by it. In the
program-specific configuration file, all lines are selected. For each
line found, its tag (if present) is stripped away, and the rest of the
line is split up into words. These words are regarded as command line
options and are inserted to the program arguments _before_ any options
from the command line. Thus the options from `.mailutils' take
precedence over those from `mailutils.rc', and the options from the
command line take precedence over those from all three configuration
files.
The word splitting occurs at whitespace characters and is similar to
that performed by the shell. If an option must contain embedded
whitespace, it should be enclosed in a pair of quotes (either double or
single quotes).
---------- Footnotes ----------
(1) If `#' is not the first character on the line, it should be
separated from the previous word by any amount of whitespace.
default -- Options understood by most GNU utilities.
----------------------------------------------------
Each program also understands the following informational options:
`-u'
`--usage'
Display a short usage message and exit.
`-h'
`--help'
Display help message and exit.
`-L'
`--license'
Display GNU General Public License and exit.
`-v'
`--version'
Display program version and exit.
mailbox -- Specifies the mail spool location, and locking strategy.
-------------------------------------------------------------------
Option group `mailbox' consists of options used to specify the
location of the mail spool, and the locking strategy.
`-m PATH'
`--mail-spool=PATH'
Set path to the mailspool directory
`--lock-flags=FLAGS'
Set the default mailbox lock flags (E=external, R=retry, T=time,
P=pid).
mailer -- Sets the default mailer URL.
--------------------------------------
This option group overrides the default mailer URL (<sendmail:>).
`-m URL'
`--mailer URL'
address -- Specifies the default email address and domain.
----------------------------------------------------------
Option group `address' consists of options used to specify how to
qualify email addresses.
An unqualified address (one without an @) is qualified by appending
@DEFAULTDOMAIN. DEFAULTDOMAIN is the return of gethostname(), or the
result of gethostbyname() on the return of gethostname() (if the DNS
lookup is successful).
If the email address of the current user is needed, either the
address set by -email-addr is returned, or the current uid is looked up
in the user database, and qualified with the DEFAULTDOMAIN.
`-E EMAIL'
`--email-addr=EMAIL'
Set the current user's email address, this it makes more sense to
use this in one of the per-user configuration files.
`-D DOMAIN'
`--email-domain=DOMAIN'
Set the default email domain, this might make sense to use in
either the global or one of the per-user configuration files.
daemon -- Options common for daemon programs.
---------------------------------------------
`-d[NUMBER]'
`--daemon[=NUMBER]'
Run in standalone mode. An optional NUMBER specifies the maximum
number of child processes the daemon is allowed to fork. When it
is omitted, it defaults to 20 processes. _Please note_, that
there should be no whitespace between the `-d' and its parameter.
`-i'
`--inetd'
Run in inetd mode.
`-p NUMBER'
`--port NUMBER'
Listen on given port NUMBER. This option is meaningful only in
standalone mode. It defaults to port 143.
`-t NUMBER'
`--timeout NUMBER'
Set idle timeout to given NUMBER of seconds. The daemon breaks the
connection if it receives no commands from the client within that
number of seconds.
auth -- Authentication-specific options.
----------------------------------------
These options control the authorization and authentication module
lists. For a description of authentication concepts, refer to *Note
authentication::.
`--authorization MODLIST'
This option allows to set up a list of modules to be used for
authorization. MODLIST is a colon-separated list of modules. Valid
modules are:
system
User credentials are retrieved from the system user database
(`/etc/password').
sql
User credentials are retrieved from the sql database. The set
of `--sql-' options (see below) is used to configure access
to the database.
virtdomain
User credentials are retrieved from a "virtual domain" user
database.
`--authentication MODLIST'
This option allows to set up a list of modules to be used for
authentication. MODLIST is a colon-separated list of modules.
Valid modules are:
generic
The generic authentication type. User password is hashed and
compared against the hash value returned in authorization
stage.
system
The hashed value of the user password is retrieved from
`/etc/shadow' file on systems that support it.
sql
The hashed value of the user password is retrieved from the
sql database using query supplied by `--sql-getpass' option
(see below).
pam
The user is authenticated via pluggable authentication module
(pam). The pam service name to be used is configured via
`--pam-service' option (see below)
`--pam-service NAME'
When compiled with pam support, this option specifies the name of
pam service to be used when authenticating.
The following options exist in this group if the package was
configured with `--enable-sql' option. They take effect only if the
`sql' module is used in authentication and/or authorization. Currently
only MySQL is supported.
`--sql-getpwnam QUERY'
sql query to retrieve a passwd entry based on username
`--sql-getpwuid QUERY'
`--sql-getpass QUERY'
sql query to retrieve a password from the database
`--sql-host NAME'
Name or IP of MySQL server to connect to.
`--sql-user NAME'
sql user name
`--sql-passwd STRING'
sql connection password
`--sql-db STRING'
Name of the database to connect to.
`--sql-port NUMBER'
Port to use
logging -- Logging control options.
-----------------------------------
`--log-facility FACILITY'
Output logs to the specified `syslog' facility. The following
facility names are recognized: `user', `daemon', `mail', `auth'
and `local0' through `local7'. These names are case-insensitive.
Sieve specific options
----------------------
The following options comprise this group:
`-I DIR'
`--includedir=DIR'
Append directory DIR to the list of directories searched for
include files.
`-L DIR'
`--libdir=DIR'
Append directory DIR to the list of directories searched for
library files.
A sample configuration file.
----------------------------
The following configuration file specifies that all Mailutils
programs should use `/var/spool/mail' as a local mailspool directory.
Programs performing authentication will use pam service `mailutils'.
All programs, except `imap4d' will issue log messages via `mail'
facility, `imap4d' will use facility `local1'.
:mailbox --mail-spool /var/spool/mail
:auth --authentication pam --pam-service mailutils
:logging --log-facility mail
imap4d --daemon=20 --timeout=1800 --log-facility local1
IMAP4 daemon
============
GNU imap4d is a daemon implementing IMAP4 rev1 protocol for
accessing and handling electronic mail messages on a server. It can be
run either as a standalone program or from `inetd.conf' file.
Imap4d Namespace
----------------
GNU imap4d supports a notion of "namespaces" defined in RFC 2342. A
namespace is a set of directories upon which the user has certain
permissions. It should be understood that these permissions apply only
if the underlying filesystem allows them.
The three namespaces supported by `imap4d' are:
Personal Namespace
A namespace that is within the personal scope of the authenticated
user on a particular connection. The user has all permissions on
this namespace.
Other Users' Namespace
A namespace that consists of mailboxes from the "Personal
Namespaces" of other users. The user can read and list mailboxes
from this namespace. However, he is not allowed to use `%' and `*'
wildcards with `LIST' command, that is he can access a mailbox
only if he knows exactly its location.
Shared Namespace
A namespace that consists of mailboxes that are intended to be
shared amongst users and do not exist within a user's Personal
Namespace. The user has all permissions on this namespace.
By default, `imap4d' starts with the following namespaces:
Personal Namespace
The home directory of the user, if exists.
Other Users' Namespace
Empty
Shared Namespace
Empty
_Note_, that this means that by default, a user won't be able to see
or otherwise access mailboxes residing in the directories other than
his own home.
To change these defaults, use `--shared-namespace' and
`--other-namespace' options.
Starting imap4d
---------------
`imap4d' may run either in "standalone" or in "inetd" operation
modes. When run in "standalone" mode, the server disconnects from the
terminal and runs as a daemon, forking a child for each new connection.
The "inetd" mode allows to start the server from `/etc/inetd.conf'
file. This is the default operation mode.
imap4 stream tcp nowait root /usr/local/sbin/imap4d imap4d
The program uses following option groups: *Note mailbox::, *Note
daemon::, *Note logging::, *Note auth::.
Command line options
--------------------
`-d[NUMBER]'
`--daemon[=NUMBER]'
Run in standalone mode. An optional NUMBER specifies the maximum
number of child processes the daemon is allowed to fork. When it
is omitted, it defaults to 20 processes. _Please note_, that
there should be no whitespace between the `-d' and its parameter.
`-h'
`--help'
Display short help message and exit.
`-i'
`--inetd'
Run in inetd mode.
`-m PATH'
`--mail-spool=PATH'
Set path to the mailspool directory
`-O PATHLIST'
`--other-namespace=PATHLIST'
Set the list of directories forming the "Other User's" namespace.
PATHLIST is a list of directory names separated by colons.
`-p NUMBER'
`--port NUMBER'
Listen on given port NUMBER. This option is meaningful only in
standalone mode. It defaults to port 143.
`-S PATHLIST'
`--shared-namespace=PATHLIST'
Set the list of directories, forming the "Shared" namespace.
PATHLIST is a list of directory names separated by colons.
`-t NUMBER'
`--timeout NUMBER'
Set idle timeout to given NUMBER of seconds. Default is 1800
seconds (30 minutes). The daemon breaks the connection if it
receives no commands from the client within that number of seconds.
`-v'
`--version'
Display program version and exit.
POP3 daemon
===========
The `pop3d' daemon implements the Post Office Protocol server.
pop3d has two operation modes:
Inetd
The server is started from `/etc/inetd.conf' file:
pop3 stream tcp nowait root /usr/local/sbin/pop3d pop3d
This is the default operation mode.
Standalone
The server runs as daemon, forking a child for each new
connection. This mode is triggered by `-d' command line switch.
The program uses following option groups: *Note mailbox::, *Note
daemon::, *Note logging::, *Note auth::.
Command line options
--------------------
`-d[NUMBER]'
`--daemon[=NUMBER]'
Run in standalone mode. An optional NUMBER specifies the maximum
number of child processes the daemon is allowed to fork. When it
is omitted, it defaults to 10 processes. _Please note_, that
there should be no whitespace between the `-d' and its parameter.
`-h'
`--help'
Display short help message and exit.
`-i'
`--inetd'
Run in inetd mode.
`-m PATH'
`--mail-spool=PATH'
Set path to the mailspool directory
`-p NUMBER'
`--port NUMBER'
Listen on given port NUMBER. This option is meaningful only in
standalone mode. It defaults to port 110.
`-t NUMBER'
`--timeout NUMBER'
Set idle timeout to given NUMBER of seconds. Default is 600
seconds (10 minutes). The daemon breaks the connection if it
receives no commands from the client within that number of seconds.
`-v'
`--version'
Display program version and exit.
frm -- List headers from a mailbox.
===================================
The `frm' command outputs a header information of the selected
messages in a mailbox. By default, `frm' reads the 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 program uses following option groups: *Note mailbox::.
The following command line options alter the behavior of the program:
`-f STRING'
`--field STRING'
Display the header named by STRING instead of `From' `Subject'
pair.
`-l'
`--to'
Include the contents of `To' header to the output. The output field
order is then: `To' `From' `Subject'.
`-n'
`--number'
Prefix each line with corresponding message number.
`-Q'
`--Quiet'
Be very quiet. Nothing is output except error messages. This is
useful in shell scripts where only the return status of the
program is important.
`-q'
`--query'
Print a message only if there are unread messages in the mailbox.
`-S'
`--summary'
Print a summary line.
`-s ATTR'
`--status ATTR'
Only display headers from messages with the given status. ATTR
may be one of the following: `new', `read', `unread'. It is
sufficient to specify only first letter of an ATTR. Multiple `-s'
options are allowed.
`-t'
`--align'
Tidy mode. Currently is not implemented. Included for
compatibility with `frm' program from Elm package.
mail -- send and receive mail.
===============================
`Mail' is an enhanced version of standard `/bin/mail' program. As
well as its predecessor, it can be used either in sending mode or in
reading mode. `Mail' enters sending mode when one or more email
addresses were specified in this command line. In this mode the program
waits until user finishes composing the message, then attempts to send
it to the specified addresses and exits. See *Note Composing Mail::,
for a detailed description of this behavior.
If the command line contained no email addresses, `mail' switches to
reading mode. In this mode it allows to read and manipulate the
contents of a mailbox. The URL of the mailbox to operate upon is taken
from the argument of `--file' command line option. If it is not
specified, the user's system mailbox is assumed. For more detail, see
*Note Reading Mail::.
Command line options
--------------------
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: *Note mailbox::.
`Mail' understands following command line options:
`-e'
`--exist'
Return true if the mailbox contains some messages. Return false
otherwise. This is useful for writing shell scripts.
`-f[FILE]'
`--file[=FILE]'
Operate on mailbox FILE. If this option is not specified, the
default is user's system mailbox. If it is specified without
argument, the default is $HOME/mbox. _Please note_, that there
should be no whitespace between the short variant of the option
(`-f'), and its parameter. Similarly, when using long option
(`--file'), its argument must be preceded by equal sign.
`-F'
`--byname'
Save messages according to sender. Currently this option is not
implemented.
`-H'
`--headers'
Print header summary to stdout and exit.
`-i'
`--ignore'
Ignore interrupts.
`-m PATH'
`--mail-spool=PATH'
Set path to the mailspool directory
`-n'
`--norc'
Do not read the system-wide mailrc file. *Note Mail Configuration
Files::.
`-N'
`--nosum'
Do not display initial header summary.
`-p'
`--print'
`-r'
`--read'
Print all mail to standard output. It is equivalent to issuing
following commands after starting `mail -N':
print *
quit
`-q'
`--quit'
Cause interrupts to terminate program.
`-s SUBJ'
`--subject=SUBJ'
Send a message with a Subject of SUBJ. Valid only in sending mode.
`-t'
`--to'
Switch to sending mode.
`-u USER'
`--user=USER'
Operate on USER's mailbox. This is equivalent to:
mail -f/SPOOL_PATH/USER
with SPOOL_PATH being the full path to your mailspool directory
(`/var/spool/mail' or `/var/mail' on most systems).
`-?'
`--help'
Display a help message.
`--usage'
Display a short usage summary.
`-V'
`--version'
Print program version and exit.
How to specify message sets
---------------------------
Many mail commands such as print and delete can be given a "message
list" to operate upon. Wherever the message list is omitted, the command
operates on the current message.
The "message list" in its simplest form is one of:
.
Selects current message. It is equivalent to empty message list.
*
Selects all messages in the mailbox.
^
Selects first non-deleted message.
$
Selects last non-deleted message.
In its complex form, the "message list" is a comma or
whitespace-separated list of "message specifiers". A "message
specifier" is one of
Message Number
This specifier addresses the message with the given ordinal number
in the mailbox.
Message range
"Message range" is specified as two message numbers separated by a
dash. It selects all messages with the number lying within that
range.
Attribute specifier
An "Attribute specifier" is a colon followed by a single letter.
The "Attribute specifier" addresses all messages in the mailbox
that have the given attribute. These are the valid attribute
specifiers:
`:d'
Selects all deleted messages.
`:n'
Selects all recent messages, i.e. the messages that have not
been neither read not seen so far.
`:o'
Selects all messages that have been seen.
`:r'
Selects all messages that have been read.
`:u'
Selects all messages that have _not_ been read.
`:t'
Selects all tagged messages (*note Marking Messages::).
`:T'
Selects all untagged messages.
Header match
The "header match" is a string in the form:
[HEADER:]/STRING/
It selects all messages that contain header field HEADER matching
given REGEXP. If the variable `regexp' is set, the STRING is
assumed to be a POSIX regexp. Otherwise, a header is considered to
match STRING if the latter constitutes a substring of the former
(comparison is case-insensitive).
If HEADER: part is omitted, it is assumed to be `Subject:'.
Message body match
The "message body match" is a string in the form:
:/STRING/
It selects all messages whose body matches the string. The matching
rules are the same as described under "Header match".
A "message specifier" can be followed by "message part specifier",
enclosed in a pair of brackets. A "message part specifier" controls
which part of a message should be operated upon. It is meaningful only
for multipart messages. A "message part specifier" is a comma or
whitespace - separated list of part numbers or ranges. Each part number
can in turn be "message part specifier", thus allowing for operating
upon multiply-encoded messages.
The following are the examples of valid message lists:
Composing mail
--------------
You can compose the message by simply typing the contents of it, line
by line. But usually this is not enough, you would need to edit your
text, to quote some messages, etc. `Mail' provides these capabilities
through "compose escapes". The "compose escapes" are single-character
commands, preceded by special "escape character", which defaults to
`~'. The combination `escape character + command' is recognized as a
compose escape only if it occurs at the beginning of a line. If the
escape character must appear at the beginning of a line, enter it twice.
The actual escape character may be changed by setting the value of
`escape' mail variable (*note Mail Variables::).
Quitting Compose Mode
.....................
There are several commands allowing you to quit the compose mode.
Typing the end-of-file character (`C-D') on a line alone finishes
compose mode and sends the message to its destination. The `C-D'
character looses its special meaning if `ignoreeof' mail variable is
set.
If mail variable `dot' is set, typing dot (`.') on a line alone
achieves the same effect as `C-D' above.
Finally, using `~.' escape always quits compose mode and sends out
the composed message.
To abort composing of a message without sending it, type interrupt
character (by default, `C-C') twice. This behavior is disabled when
mail variable `ignore' is set. In this case, you can use `~x' escape to
achieve the same effect.
Getting Help on Compose Escapes: ~?
...................................
The `~?' escape prints on screen a brief summary of the available
compose escapes. _Please note_, that `~h' escape prompts for changing
the header values, and does _not_ give help.
Editing the Message: ~e and ~v.
...............................
If you are not satisfied with the message as it is, you can edit it
using a text editor specified either by `EDITOR' or by `VISUAL'
environment variables. The `~e' uses the former, and `~v' uses the
latter.
By default both escapes allow you to edit only the body of the
message. However, if the `editheaders' variable is set, `mail' will
load into the editor the complete text of the message with headers
included, thus allowing you to change the headers as well.
Modifying the Headers: ~h, ~t, ~c, ~b, ~s
.........................................
To add new addresses to the list of message recipients, use `~t'
command, e.g.:
~t name1@domain.net name2
To add addresses to `Cc' or `Bcc', use `~c' or `~b' escapes
respectively.
To change the `Subject' header, use `~s' escape, e.g.:
~s "Re: your message"
Finally, to edit all headers, type `~h' escape. This will present
you with the values of `To', `Cc', `Bcc', and `Subject' headers
allowing to edit them with normal text editing commands.
Enclosing Another Message: ~m and ~M
....................................
If you are sending mail from within mail command mode, you can
enclose the contents of any message sent to you by using `~m' or `~M'
commands. Typing `~m' alone will enclose the contents of the current
message, typing `~m 12' will enclose the contents of message #12 and so
on.
The `~m' uses retained and ignored lists when enclosing headers, the
`~M' encloses all header fields (*note Controlling Header Display::).
In both cases, the contents of `indentprefix' mail variable is
prepended to each line enclosed.
Adding a File to the Message: ~r and ~d
.......................................
To append the contents of file FILENAME to the message, type
~r FILENAME
or
~< FILENAME
The `~d' escape is a shorthand for
~r dead.letter
Printing And Saving the Message
...............................
The `~p' escape types the contents of the message entered so far,
including headers, on your terminal. You can save the message to an
arbitrary file using `~w' escape. It takes the filename as its argument.
Signing the Message: ~a and ~A
..............................
To save you the effort of typing your signature at the end of each
message, you can use `~a' or `~A' escapes. If your signature occupies
one line only, save it to the variable `sign' and use `~a' escape to
insert it. Otherwise, if it is longer than one line, save it to a file,
store the name of this file in the variable `Sign', and use `~A' escape
to insert it into the message.
Printing Another Message: ~f and ~F
...................................
Sometimes it is necessary to view the contents of another message,
while composing. These two escapes allow it. Both take the message list
as their argument. If they are used without argument, the contents of
the current message is printed. The difference between `~f' and `~F' is
that the former uses ignored and retained lists to select headers to be
displayed, whereas the latter prints all headers (*note Controlling
Header Display::).
Inserting Value of a Mail Variable: ~i
......................................
The `~i' escape enters the value of the named mail variable into the
body of the message being composed.
Executing Other Mail Commands: ~: and ~-
........................................
You can execute a mail command from within compose mode using `~:'
or `~-' escapes. For example, typing
~: from :t
will display the from lines of all tagged messages. Note, that executing
mail-sending commands (*note Replying::) from within the compose mode is
not allowed. An attempt to execute such a command will result in
diagnostic message "Command not allowed in an escape sequence" being
displayed. Also, when starting compose mode immediately from the shell
(e.g. running `mail address@domain'), most mail commands are
meaningless, since there is no mailbox to operate upon. In this case,
the only commands that can reasonably be used are: `alias', `unalias',
`alternate', `set', and `unset'.
Executing Shell Commands: ~! and ~|
...................................
The `~!' escape executes specified command and returns you to `mail'
compose mode without altering your message. When used without
arguments, it starts your login shell. The `~|' escape pipes the
message composed so far through the given shell command and replaces the
message with the output the command produced. If the command produced
no output, `mail' assumes that something went wrong and retains the old
contents of your message.
Reading mail
------------
To read messages from a given mailbox, use one of the following ways
of invoking `mail':
`mail'
To read messages from your system mailbox.
`mail --file'
To read messages from your mailbox ($HOME/mbox).
`mail --file=PATH_TO_MAILBOX'
To read messages from the specified mailbox.
`mail --user=USER'
To read messages from the system mailbox belonging to USER.
_Please note_, that usual mailbox permissions won't allow you to use
the last variant of invocation, unless you are a super-user.
Similarly, the last but one variant is also greatly affected by the
permissions the target mailbox has.
Unless you have started mail with `--norc' command line option, it
will read the contents of the system-wide configuration file. Then it
reads the contents of user configuration file, if any. For detailed
description of these files, see *Note Mail Configuration Files::.
After this initial setup, `mail' displays the first page of header
lines and enters interactive mode. In interactive mode, `mail' displays
its prompt (`?', if not set otherwise) and executes the commands the
user enters.
Quitting the program
....................
Following commands quit the program:
`quit'
Terminates the session. If `mail' was operating upon user's system
mailbox, then all undeleted and unsaved messages that have been
read and are not marked with hold flag are saved to the user's
mbox file (`$HOME/mbox'). The messages, marked with `delete' are
removed. The program exits to the Shell, unless saving the
mailbox fails, in which case user can escape with the exit command.
`exit'
`ex'
`xit'
Program exits to the Shell without modifying the mailbox it
operates upon.
Typing EOF (`C-D') alone is equivalent to `quit'.
Obtaining online help
.....................
Following commands can be used during the session to request online
help:
`help [COMMAND]'
`hel [COMMAND]'
`? [COMMAND]'
Display detailed command synopsis. If no COMMAND is given, help for
all available commands is displayed.
`list'
`*'
Print a list of available commands.
`version'
`ve'
Display program version.
`warranty'
`wa'
Display program warranty statement.
Moving within a mailbox
.......................
`next'
`n'
Move to the next message.
`previous'
`prev'
Move to the previous message.
Changing mailbox/directory
..........................
`cd [DIR]'
`chdir [DIR]'
`ch [DIR]'
Change to the specified directory. If DIR is omitted, $HOME is
assumed.
`file [MAILBOX]'
`fi [MAILBOX]'
`folder [MAILBOX]'
`fold [MAILBOX]'
Read in the contents of the specified MAILBOX. The current mailbox
is updated as if `quit' command has been issued. If MAILBOX is
omitted, the command prints the current mailbox name followed by
the summary information regarding it, e.g.:
& fold
"/var/spool/mail/gray": 23 messages 22 unread
Controlling header display
..........................
To control which headers in the message should be displayed, `mail'
keeps two lists: a "retained" header list and an "ignored" header list.
If "retained" header list is not empty, only the header fields listed
in it are displayed when printing the message. Otherwise, if "ignored"
header list is not empty, only the headers _not listed_ in this list
are displayed. The uppercase variants of message-displaying commands
can be used to print all the headers.
The following commands modify and display the contents of both lists.
`discard [HEADER-FIELD-LIST]'
`di [HEADER-FIELD-LIST]'
`ignore [HEADER-FIELD-LIST]'
`ig [HEADER-FIELD-LIST]'
Add HEADER-FIELD-LIST to the ignored list. When used without
arguments, this command prints the contents of ignored list.
`retain [HEADER-FIELD-LIST]'
`ret [HEADER-FIELD-LIST]'
Add HEADER-FIELD-LIST to the retained list. When used without
arguments, this command prints the contents of retained list.
Displaying information
......................
`='
Displays the current message number.
`headers [MSGLIST]'
`h [MSGLIST]'
Lists the current pageful of headers.
`from [MSGLIST]'
`f [MSGLIST]'
Lists the contents of `From' headers for a given set of messages.
`z [ARG]'
Presents message headers in pagefuls as described for `headers'
command. When ARG is `.', it is generally equivalent to `headers'.
When ARG is omitted or is `+', the next pageful of headers is
displayed. If ARG is `-', the previous pageful of headers is
displayed. The latter two forms of `z' command may also take a
numerical argument meaning the number of pages to skip before
displaying the headers. For example:
& z +2
will skip two pages of messages before displaying the header
summary.
`size [MSGLIST]'
`si [MSGLIST]'
Lists the message number and message size in bytes for each
message in MSGLIST.
`folders'
Displays the value of `folder' variable.
`summary'
`su'
Displays current mailbox summary. E.g.:
& summary
"/var/spool/mail/gray": 23 messages 22 unread
Displaying messages
...................
`print [MSGLIST]'
`p [MSGLIST]'
`type [MSGLIST]'
`t [MSGLIST]'
Prints out the messages from MSGLIST. The variable `crt'
determines the minimum number of lines the body of the message must
contain in order to be piped through pager command specified by
environment variable `PAGER'. If `crt' is set to a numeric value,
this value is taken as the minimum number of lines. Otherwise, if
`crt' is set without a value then the height of the terminal
screen is used to compute the threshold. The number of lines on
screen is controlled by `screen' variable.
`Print [MSGLIST]'
`P [MSGLIST]'
`Type [MSGLIST]'
`T [MSGLIST]'
Like print but also prints out ignored header fields. For
detailed description of ignored header lists, see *Note
Controlling Header Display::.
`decode [MSGLIST]'
`dec [MSGLIST]'
Print a multipart message. The `decode' command decodes and prints
out specified message parts. E.g.
& decode 15[2]
+---------------------------------------
| Message=15[2]
| Type=message/delivery-status
| encoding=7bit
+---------------------------------------
Content-Type: message/delivery-status
...
`top [MSGLIST]'
`to [MSGLIST]'
Prints the top few lines of each message in MSGLIST. The number
of lines printed is controlled by the variable `toplines' and
defaults to five.
`pipe [MSGLIST] [SHELL-COMMAND]'
`| [MSGLIST] [SHELL-COMMAND]'
Pipe the contents of specified messages through SHELL-COMMAND. If
SHELL-COMMAND is empty but the string variable `cmd' is set, the
value of this variable is used as a command name.
Marking messages
................
`tag [MSGLIST]'
`ta [MSGLIST]'
Tag messages. The tagged messages can be referred to in message
list using `:t' notation.
`untag [MSGLIST]'
`unt [MSGLIST]'
Clear tags from specified messages. To untag all messages tagged
so far type
& untag :t
`hold [MSGLIST]'
`ho [MSGLIST]'
`preserve [MSGLIST]'
`pre [MSGLIST]'
Marks each message to be held in user's system mailbox. This
command does not override the effect of `delete' command.
Disposing of messages
.....................
`delete [MSGLIST]'
`d [MSGLIST]'
Mark messages as deleted. Upon exiting with `quit' command these
messages will be deleted from the mailbox. Until the end of current
session the deleted messages can be referred to in message lists
using :d notation.
`undelete [MSGLIST]'
`u [MSGLIST]'
Clear delete mark from the specified messages.
`dp [MSGLIST]'
`dt [MSGLIST]'
Deletes the current message and prints the next message. If
MSGLIST is specified, deletes all messages from the list and
prints the message, immediately following last deleted one.
Saving messages
...............
`save [[MSGLIST] FILE]'
`s [[MSGLIST] FILE]'
Takes a message list and a file name and appends each message in
turn to the end of the file. The name of file and number of
characters appended to it is echoed on the terminal. Each saved
message is marked for deletion as if with `delete' command, unless
the variable `keepsave' is set.
`Save [MSGLIST]'
`S [MSGLIST]'
Like `save', but the file to append messages to is named after the
sender of the first message in MSGLIST. For example:
& from 14 15
U 14 smith@noldor.org Fri Jun 30 18:11 14/358 The Save c
U 15 gray@noldor.org Fri Jun 30 18:30 8/245 Re: The Sa
& Save 14 15
"smith" 22/603
i.e., 22 lines (603 characters) have been appended to the file
"smith". If the file does not exist, it is created.
`write [[MSGLIST] FILE]'
`w [[MSGLIST] FILE]'
Similar to `save', except that only message body (without the
header) is saved.
`Write [MSGLIST]'
`W [MSGLIST]'
Similar to `Save', except that only message body (without the
header) is saved.
`mbox [MSGLIST]'
`mb [MSGLIST]'
`touch [MSGLIST]'
`tou [MSGLIST]'
Mark list of messages to be saved in the user's mailbox
($HOME/mbox) upon exiting via `quit' command. This is the default
action for all read messages, unless you have variable `hold' set.
`copy [[MSGLIST] FILE]'
`c [[MSGLIST] FILE]'
Similar to `save', except that saved messages are not marked for
deletion.
`Copy [MSGLIST]'
`C [MSGLIST]'
Similar to `Save', except that saved messages are not marked for
deletion.
Editing messages
................
These command allow to edit messages in a mailbox. _Please note_,
that modified messages currently do not replace original ones. i.e.
you have to save them explicitly using your editor's `save' command if
you do not want the effects of your editing to be lost.
`edit [MSGLIST]'
`e [MSGLIST]'
Edits each message in MSGLIST with the editor, specified in
`EDITOR' environment variable.
`visual [MSGLIST]'
`v [MSGLIST]'
Edits each message in MSGLIST with the editor, specified in
`VISUAL' environment variable.
Scripting
.........
Comments
--------
The `#' character introduces an end-of-line comment. All characters
until and including the end of line are ignored.
Displaying arbitrary text
-------------------------
The `echo' (`ec') command prints its arguments to stdout.
Sourcing external command files
-------------------------------
The command `source FILENAME' reads commands from the named file.
Its minimal abbreviation is `so'.
Setting and unsetting the variables.
------------------------------------
The mail variables may be set using `set' (`se') command. The
command takes a list of assignments. The syntax of an assignment is
`NAME=STRING'
Assign a string value to the variable. If STRING contains
whitespace characters it must be enclosed in a pair of
double-quote characters (`"')
`NAME=NUMBER'
Assign a numeric value to the variable.
`NAME'
Assign boolean `True' value.
`noNAME'
Assign boolean `False' value.
Example:
& set askcc nocrt indentprefix="> "
This statement sets `askcc' to `True', `crt' to `False', and
`indentprefix' to "> ".
To unset mail variables use `unset'(`uns') command. The command
takes a list of variable names to unset.
Example: To undo the effect of the previous example, do:
& unset askcc crt indentprefix
Setting and unsetting shell environment variables.
--------------------------------------------------
Shell environment may be modified using `setenv' (`sete') command.
The command takes a list of assignments. The syntax of an assignment is:
`NAME=VALUE'
If variable NAME does not already exist in the environment, then
it is added to the environment with the value VALUE. If NAME does
exist, then its value in the environment is changed to VALUE.
`NAME'
Delete the variable NAME from the environment ("unset" it).
Conditional statements
----------------------
The conditional statement allows to execute a set of mail commands
depending on the mode the `mail' program is in. The conditional
statement is:
if COND
...
else
...
endif
where `...' represents the set of commands to be executed in each
branch of the statement. COND can be one of the following:
`s'
True if `mail' is operating in mail sending mode.
`r'
True if `mail' is operating in mail reading mode.
`t'
True if stdout is a terminal device (as opposed to a regular file).
The conditional statements can be nested to arbitrary depth. The
minimal abbreviations for `if', `else' and `endif' commands are `i',
`el' and `en'.
Example:
if t
set crt prompt="& "
else
unset prompt
endif
if s
alt gray@farlep.net gray@mirddin.farlep.net
set
Aliasing
........
`alias [alias [address...]]'
`a [alias [address...]]'
`group [alias [address...]]'
`g [alias [address...]]'
With no arguments, prints out all currently-defined aliases. With
one argument, prints out that alias. With more than one argument,
creates a new alias or changes an old one.
`unalias [alias...]'
`una [alias...]'
Takes a list of names defined by alias commands and discards the
remembered groups of users. The alias names no longer have any
significance.
`alternates name...'
`alt name...'
The alternates command is useful if you have accounts on several
machines. It can be used to inform mail that the listed addresses
are really you. When you reply to messages, mail will not send a
copy of the message to any of the addresses listed on the
alternates list. If the alternates command is given with no
argument, the current set of alternate names is displayed.
Replying
........
`mail [address...]'
`m [address...]'
Switches to compose mode. After composing the message, sends
messages to the specified addresses.
`reply [MSGLIST]'
`respond [MSGLIST]'
`r [MSGLIST]'
For each message in MSGLIST, switches to compose mode and sends
the composed message to the sender and all recipients of the
message.
`Reply [MSGLIST]'
`Respond [MSGLIST]'
`R [MSGLIST]'
Like `reply', except that the composed message is sent only to
originators of the specified messages.
`followup [MSGLIST]'
`fo [MSGLIST]'
Switches to compose mode. After composing, sends the message to the
originators and recipients of all messages in MSGLIST.
`Followup [MSGLIST]'
`F [MSGLIST]'
Similar to `followup', but reply message is sent only to
originators of messages in MSGLIST.
Incorporating new mail
......................
The `incorporate' (`inc') command incorporates newly arrived
messages to the displayed list of messages. This is done automatically
before returning to `mail' command prompt if the variable `autoinc' is
set.
Shell escapes
.............
To run arbitrary shell command from `mail' command prompt, use
`shell' (`sh') command. If no arguments are specified, the command
starts the user login shell. Otherwise, it uses its first argument as a
file name to execute and all subsequent arguments are passed as
positional parameters to this command. The `shell' command can also be
spelled as `!'.
How to alter the behavior of mail
---------------------------------
Following variables control the behavior of GNU `mail':
`Sign'
Type: String.
Default: Unset.
Contains the filename holding users signature. The contents of this
file is appended to the end of a message being composed by `~A'
escape.
`appenddeadletter'
Type: Boolean.
Default: False.
If this variable is `True', the contents of canceled letter is
appended to the user's `dead.letter' file. Otherwise it overwrites
its contents.
`askbcc'
Type: Boolean.
Default: False.
When set to `True' the user will be prompted to enter `Bcc' field
before composing the message.
`askcc'
Type: Boolean.
Default: True.
When set to `True' the user will be prompted to enter `Cc' field
before composing the message.
`asksub'
Type: Boolean.
Default: True in interactive mode, False otherwise.
When set to `True' the user will be prompted to enter `Subject'
field before composing the message.
`autoinc'
Type: Boolean.
Default: True.
Automatically incorporate newly arrived messages.
`autoprint'
Type: Boolean.
Default: False.
Causes the delete command to behave like dp - thus, after deleting
a message, the next one will be typed automatically.
`cmd'
Type: String.
Default: Unset.
Contains default shell command for `pipe'.
`columns'
Type: Numeric.
Default: Detected at startup by querying the terminal device. If
this fails, the value of environment variable `COLUMNS' is used.
This variable contains the number of columns on terminal screen.
`crt'
Type: Boolean or Numeric
Default: True in interactive mode, False otherwise.
The variable `crt' determines the minimum number of lines the body
of the message must contain in order to be piped through pager
command specified by environment variable `PAGER'. If `crt' is set
to a numeric value, this value is taken as the threshold.
Otherwise, if `crt' is set without a value, then the height of the
terminal screen is used to compute the threshold. The number of
lines on screen is controlled by `screen' variable.
`dot'
Type: Boolean.
Default: False.
If `True', causes `mail' to interpret a period alone on a line as
the terminator of a message you are sending.
`editheaders'
Type: Boolean.
Default: False.
When set, `mail' will include message headers in the text to be
the `~e' and `~v' escapes, thus allowing you to customize the
headers.
`escape'
Type: String.
Default: ~
If defined, the first character of this option gives the character
to denoting escapes.
`folder'
Type: String.
Default: Unset.
The name of the directory to use for storing folders of messages.
If unset, $HOME is assumed.
`header'
Type: Boolean.
Default: True, unless started with `--nosum' (`-N') option.
Whether to run `headers' command automatically after entering
interactive mode.
`hold'
Type: Boolean.
Default: False.
When set to `True', the read or saved messages will be stored in
user's mailbox (`$HOME/mbox'). Otherwise, they will be held in
system mailbox also. This option is in effect only when operating
upon user's system mailbox.
`ignore'
Type: Boolean.
Default: False.
When set to `True', `mail' will ignore keyboard interrupts when
composing messages. Otherwise an interrupt will be taken as a
signal to abort composing.
`ignoreeof'
Type: Boolean.
Default: False.
Controls whether typing EOF character terminates the letter being
composed.
`indentprefix'
Type: String.
Default: "\t" (a tab character).
String used by the `~m' tilde escape for indenting quoted messages.
`keepsave'
Type: Boolean.
Default: False.
Controls whether saved messages should be kept in system mailbox
too. This variable is in effect only when operating upon a user's
system mailbox.
`metoo'
Type: Boolean.
Default: False.
Usually, when an alias is expanded that contains the sender, the
sender is removed from the expansion. Setting this option causes
the sender to be included in the group.
`mode'
Type: String.
Default: The name of current operation mode.
Setting this variable does not affect the operation mode of the
program.
`noregex'
Type: Boolean.
Default: False.
Setting this to `True' enables use of regular expressions in
`/.../' message specifications.
`outfolder'
Type: String.
Default: Unset.
Contains the directory in which files created by `save', `write',
etc. commands will be stored. When unset, current directory is
assumed.
`page'
Type: Boolean.
Default: False.
If set to `True', the `pipe' command will emit a linefeed
character after printing each message.
`prompt'
Type: String.
Default: "? "
Contains the command prompt sequence.
`quiet'
Type: Boolean.
Default: False.
When set, suppresses the output of the startup banner.
`quit'
Type: Boolean.
Default: False, unless started with `--quit' (`-q') option.
When set, causes keyboard interrupts to terminate the program.
`rc'
Type: Boolean.
Default: True, unless started with `--norc' (`-N') option.
When this variable is set, `mail' will read the system-wide
configuration file upon startup. See *Note Mail Configuration
Files::.
`record'
Type: String.
Default: Unset.
When set, any outgoing message will be saved to the named file.
`save'
Type: Boolean.
Default: True.
When set, the aborted messages will be stored in the user's
`dead.file'. See also `appenddeadletter'.
`screen'
Type: Numeric.
Default: Detected at startup by querying the terminal device. If
this fails, the value of environment variable `LINES' is used.
This variable contains the number of lines on terminal screen.
`sendmail'
Type: String.
Default: sendmail:/usr/lib/sendmail
Contains the URL of mail transport agent.
`sign'
Type: String.
Default: Unset.
Contains the 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.
`subject'
Type: String.
Default: Unset.
Contains default subject line. This will be used when `asksub' is
off.
`toplines'
Type: Numeric.
Default: 5
Number of lines to be displayed by `top' and `Top' commands.
`verbose'
Type: Boolean.
Default: False.
When set, the actual delivery of messages is displayed on the
user's terminal.
Personal and system-wide configuration files
--------------------------------------------
Upon startup, `mail' reads the contents of the two command files:
the system-wide configuration file, and the user's configuration file.
Each line read from these files is processed like a usual `mail'
command.
When run with `--norc' (`-N') option, `mail' does not read the
contents of system-wide configuration file. The user's file, if it
exists, is always processed.
The user's configuration file is located in the user's home
directory and is named `.mailrc'. The location and name of the
system-wide configuration file is determined when configuring the
package via `--with-mail-rc' option. It defaults to
`SYSCONFDIR/mail.rc'.
mail.local -- Deliver mail to the local mailbox.
================================================
`mail.local' reads the standard input up to an end-of-file and
appends the received data to the local mailboxes.
Invoking mail.local
-------------------
The program uses following option groups: *Note mailbox::, *Note
auth::, *Note logging::, *Note sieve::.
`-f ADDR'
`--from ADDR'
Specify the sender's name. This option forces `mail.local' to add
`From ' envelope to the beginning of the message. If it is not
specified, `mail.local' first looks into the first line from the
standard input. If it starts with `From ', it is assumed to
contain a valid envelope. If it does not, `mail.local' creates the
envelope by using current user name and date.
`-h'
`--help'
Display this help and exit.
`-L'
`--license'
Display GNU General Public License and exit.
`-m PATH'
`--mail-spool PATH'
Specify path to mailspool directory.
`-q'
`--quota-db FILE'
Specify path to mailbox quota database (*note Mailbox Quotas::).
`-s PATTERN'
`--source PATTERN'
Set name pattern for user-defined mail filters written in Scheme
(*note Scheme Filters::). The metacharacters `%u' and `%h' in the
pattern are expanded to the current recipient user name and home
directory correspondingly.
This option is available only if the package has been configured to
use Guile extension language.
`-S PATTERN'
`--sieve PATTERN'
Set name pattern for user-defined mail filters written is Sieve
(*note Sieve Filters::). The metacharacters `%u' and `%h' in the
pattern are expanded to the current recipient user name and home
directory correspondingly.
`-t NUMBER'
`--timeout NUMBER'
Wait NUMBER seconds for acquiring the lockfile. If it doesn't
become available after that amount of time, return failure. The
timeout defaults to 5 minutes.
`-x FLAGS'
`--debug FLAGS'
Enable debugging. The debugging information will be output using
syslog. The FLAGS is a string consisting of the following flags:
Debug flags are:
`g'
Start with guile debugging evaluator and backtraces. This is
convenient for debugging user-defined filters (*note Scheme
Filters::).
`T'
Enable libmailutil traces (MU_DEBUG_TRACE).
`P'
Enable network protocol traces (MU_DEBUG_PROT)
`t'
Enable sieve trace (MU_SIEVE_DEBUG_TRACE)
`l'
Enable sieve action logs
The digits in the range `0' - `9' used in FLAGS set `mail.local'
debugging level.
`-v'
`--version'
Display program version and exit.
`--ex-multiple-delivery-success'
Don't return errors when delivering to multiple recipients.
`--ex-quota-tempfail'
Return temporary failure if disk or mailbox quota is exceeded. By
default, 'service unavailable' is returned if the message exceeds
the mailbox quota.
Using mail.local with various MTAs
----------------------------------
This section explains how to invoke `mail.local' from configuration
files of various Mail Transport Agents.
All examples in this section suppose that `mail.local' must receive
following command line switches:
-s %h/.filter.scm -q /etc/mail/userquota
Using mail.local with sendmail.
...............................
The `mail.local' must be invoked from the local mailer definition in
the `sendmail.cf' file. It must have the following flags set `lswS',
meaning the mailer is local, the 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, `fn' flags may be specified to allow
`mail.local' to generate usual `From ' envelope instead of the one
supplied by sendmail.
Here is an example of mailer definition in `sendmail.cf'
Mlocal, P=/usr/local/libexec/mail.local,
F=lsDFMAw5:/|@qSPfhn9,
S=EnvFromL/HdrFromL, R=EnvToL/HdrToL,
T=DNS/RFC822/X-Unix,
A=mail -s %h/.filter.scm -q /etc/mail/userquota $u
To define local mailer in `mc' source file, it will suffice to set:
define(`LOCAL_MAILER_PATH', `/usr/local/libexec/mail.local')
define(`LOCAL_MAILER_ARGS',
`mail -s %h/.filter.scm -q /etc/mail/userquota $u')
Using mail.local with exim.
...........................
Using `mail.local' with exim is quite straightforward. The following
example illustrates the definition of appropriate transport and
director in `exim.conf':
# transport
mail_local_pipe:
driver = pipe
command = /usr/local/libexec/mail.local -s %h/.filter.scm \
-q /etc/mail/userquota $local_part
return_path_add
delivery_date_add
envelope_to_add
# director
mail_local:
driver = localuser
transport = mail_local_pipe
Setting up mailbox quotas
-------------------------
Implementing user-defined Sieve mail filters.
---------------------------------------------
Implementing user-defined Scheme mail filters.
----------------------------------------------
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.
The program uses following option groups: *Note mailbox::.
The program accepts following command line options:
`-q'
`--quite'
`-s'
`--silent'
Be quiet. Display only number of messages per mailbox, without
leading text.
`-?'
`--help'
Output help message and exit.
`--usage'
Output short usage summary and exit.
`-V'
`--version'
Output program version and exit.
readmsg -- Extract messages from a folder.
==========================================
The program, readmsg, extracts with the selection argument messages
from a mailbox. Selection can be specify by:
1. A lone "*" means select all messages in the mailbox.
2. A list of message numbers may be specified. Values of "0" and
"$" in the list both mean the last message in the mailbox. For
example:
readmsg 1 3 0
extracts three messages from the folder: the first, the third,
and the last.
3. Finally, the selection may be some text to match. This will
select a mail message which exactly matches the specified text.
For example,
readmsg staff meeting
extracts the message which contains the words "staff meeting."
Note that it will not match a message containing "Staff Meeting" -
the matching is case sensitive. Normally only the first
message which matches the pattern will be printed.
Command line options
--------------------
`-a'
`--show-all'
If a pattern is use for selection show all messages that match
pattern by default only the first one is presented.
`-d'
`--debug'
Display mailbox debugging information.
`-f MAILBOX'
`--folder=MAILBOX'
Specified the default mailbox.
`-h'
`--header'
Show the entire header and ignore the weedlist.
`-n'
`--no-header'
Do not print the message header.
`-p'
`--form-feed'
Put form-feed (Control-L) between messages instead of newline.
`-w WEEDLIST'
`--weedlist=WEEDLIST'
A whitespace or coma separated list of header names to show per
message. Default is -weedlist="From Subject Date To CC
Apparently-"
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.
A Sieve Interpreter
-------------------
Sieve interpreter `sieve' allows to apply Sieve scripts to an
arbitrary number of mailboxes. GNU `sieve' implements a superset of the
Sieve language as described in RFC 3028. *Note Input Language::, for a
description of the Sieve language. *Note Extensions::, for a discussion
of differences between the GNU implementation of Sieve and its standard.
Invocation
..........
The `sieve' invocation syntax is:
sieve [OPTIONS] SCRIPT
where SCRIPT denotes the filename of the sieve program to parse, and
OPTIONS is one or more of the following:
`-c'
`--compile-only'
Compile script and exit.
`-d[FLAGS]'
`--debug[=FLAGS]'
Specify debug flags. The FLAGS argument is a sequence of one or
more of the following letters:
`g' Enable main parser traces
`T' Enable mailutil traces
`P' Trace network protocols
`t' Enable sieve trace
`i' Trace the program instructions
*Note Logging and Debugging::, for detailed discussion of these.
`-D'
`--dump'
Compile the script, dump disassembled code on standard output and
exit.
`-e ADDRESS'
`--email ADDRESS'
Override the user email address. This is useful for `reject' and
`redirect' actions. By default, the user email address is deduced
from the user name and the full name of the machine where sieve is
executed.
`-f'
`--mbox-url=MBOX'
Mailbox to sieve (defaults to user's system mailbox)
`-k'
`--keep-going'
Keep on going if execution fails on a message
`-n'
`--no-actions'
Dry run: do not execute any actions, just print what would be done.
`-t TICKET'
`--ticket=TICKET'
Ticket file for mailbox authentication
`-v'
`--verbose'
Log all actions executed.
Apart from these, `sieve' understands the options from the following
groups: `sieve', `mailbox', `mailer', `logging'.
Logging and debugging
.....................
The default behavior of `sieve' is to remain silent about anything
except errors. However, it is sometimes necessary to see which actions
are executed and on which messages. This is particularly useful when
debugging the sieve scripts. The `--verbose' (`-v') option outputs log
of every action executed.
Option `--debug' allows to produce even more detailed debugging
information. This option takes an argument specifying the debugging
level to be enabled. The argument can consist of the following letters:
``t''
This flag enables sieve tracing. It means that every test will be
logged when executed.
``T''
This flag enables debugging of underlying `mailutils' library.
``P''
Trace network protocols: produces log of network transactions
executed while running the script.
``g''
Enable main parser traces. This is useful for debugging the sieve
grammar.
``i''
Trace the program instructions. It is the most extensive debugging
level. It produces the full execution log of a sieve program,
showing each instruction and states of the sieve machine. It is
only useful for debugging the code generator.
_Note_, that there should be no whitespace between the short variant
of the option (`-d'), and its argument. Similarly, when using long
option (`--debug'), its argument must be preceded by equal sign.
If the argument to `--debug' is omitted, it defaults to `TPt'.
Option `--dump' produces the disassembled dump of the compiled sieve
program.
By default `sieve' output all diagnostics on standard error and
verbose logs on standard output. This behaviour is changed when
`--log-facility' is given in the command line (*note logging::). This
option causes `sieve' to output its diagnostics to the given syslog
facility.
Extending Sieve
...............
The basic set of sieve actions, tests and comparators may be extended
using loadable extensions. Usual `require' mechanism is used for that.
When processing arguments for `require' statement, `sieve' uses the
following algorithm:
1. Look up the name in a symbol table. If the name begins with
`comparator-' it is looked up in the comparator table. If it
begins with `test-', the test table is used instead. Otherwise the
name is looked up in the action table.
2. If the name is found, the search is terminated.
3. Otherwise, transform the name. First, any `comparator-' or `test-'
prefix is stripped. Then, any character other than alphanumeric
characters, `.' and `,' is replaced with dash (`-'). The name thus
obtained is used as a file name of an external loadable module.
4. Try to load the module. The module is searched in the following
search paths (in the order given):
1. Mailutils module directory. By default it is
`$prefix/lib/mailutils'.
2. The value of the environment variable LTDL_LIBRARY_PATH.
3. Additional search directories specified with the
`#searchpath' directive.
4. System library search path: The system dependent library
search path (e.g. on Linux it is set by the contents of the
file `/etc/ld.so.conf' and the value of the environment
variable LD_LIBRARY_PATH).
The value of LTDL_LIBRARY_PATH and LD_LIBRARY_PATH must be a
colon-separated list of absolute directories, for example,
`"/usr/lib/mypkg:/lib/foo"'.
In any of these directories, `sieve' first attempts to find and
load the given filename. If this fails, it tries to append the
following suffixes to the file name:
1. the libtool archive extension `.la'
2. the extension used for native dynamic libraries on the host
platform, e.g., `.so', `.sl', etc.
5. If the module is found, `sieve' executes its initialization
function (see below) and again looks up the name in the symbol
table. If found, search terminates successfully.
6. If either the module is not found, or the symbol wasn't found
after execution of the module initialization function, search is
terminated with an error status. `sieve' then displays the
following diagnostic message:
source for the required action NAME is not available
A Sieve to Scheme Translator and Filter
---------------------------------------
A Sieve to Scheme Translator `sieve.scm' translates a given Sieve
script into an equivalent Scheme program and optionally executes it.
The program itself is written in Scheme and requires presence of Guile
1.4 on the system. For more information on Guile refer to *Note
Overview: (guile)Top.
`-f FILENAME'
`--file FILENAME'
Set input file name.
`-o FILENAME'
`--output FILENAME'
Set output file name
`-L DIRNAME'
`--lib-dir DIRNAME'
Set sieve library directory name
`-d LEVEL'
`--debug LEVEL'
Set debugging level
The Scheme programs produced by `sieve.scm' can be used with `guimb'
or `mail.local'.
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 program uses following option groups: *Note mailbox::.
Specifying Scheme Program to Execute
------------------------------------
The Scheme program or expression to be executed is passed to `guimb'
via the following options:
`-s FILE'
`--source FILE'
Load Scheme source code from FILE.
`-c EXPR'
`--code EXPR'
Execute given scheme expression.
The above switches stop further argument processing, and pass all
remaining arguments as the value of `(command-line)'.
If the remaining arguments must be processed by `guimb' itself, use
following options:
`-e EXPR'
`--expression EXPR'
Execute scheme expression.
`-f FILE'
`--file FILE'
Load Scheme source code from FILE.
You can specify both of them. In this case, the FILE is read first,
then EXPR is executed. You may still pass any additional arguments to
the script using `--guile-arg' option (*note Passing Options to
Scheme::).
Specifying Mailboxes to Operate Upon
------------------------------------
There are four basic ways of passing mailboxes to `guimb'.
`guimb [OPTIONS] [MAILBOX...]'
The resulting mailbox is not saved, unless the user-supplied
scheme program saves it.
`guimb [OPTIONS] --mailbox DEFMBOX'
The contents of DEFMBOX is processed and is replaced with the
resulting mailbox contents. Useful for applying filters to user's
mailbox.
`guimb [OPTIONS] --mailbox DEFMBOX mailbox [mailbox...]'
The contents of specified mailboxes is processed, and the resulting
mailbox contents is appended to DEFMBOX.
`guimb [OPTIONS] --user USERNAME [mailbox...]'
The contents of specified mailboxes is processed, and the resulting
mailbox contents is appended to the user's system mailbox. This
allows to use `guimb' as a mail delivery agent.
If no mailboxes are specified in the command line, `guimb' reads and
processes the system mailbox of the current user.
Passing Options to Scheme
-------------------------
Sometimes it is necessary to pass some command line options to the
scheme procedure. There are three ways of doing so.
When using `--source' (`-s') or `--code' (`-c') options, all the
rest of the command line following the option's argument is passed to
Scheme program verbatim. This allows for making guimb scripts
executable by the shell. If your system supports `#!' magic at the
start of scripts, add the following two lines to the beginning of your
script to allow for its immediate execution:
#! /usr/local/bin/guimb -s
!#
(replace `/usr/local/bin/' with the actual path to the `guimb').
Otherwise, if you use `--file' or `--expression' options, the
additional arguments may be passed to the Scheme program `-g'
(`--guile-arg') command line option. For example:
guimb --guile-arg -opt --guile-arg 24 --file progfile
In this example, the scheme procedure will see the following command
line:
progfile -opt 24
Finally, if there are many arguments to be passed to Scheme, it is
more convenient to enclose them in `-{' and `-}' escapes:
guimb -{ -opt 24 -} --file progfile
Guimb Invocation Summary
------------------------
This is a short summary of the command line options available to
`guimb'.
`-d'
`--debug'
Start with debugging evaluator and backtraces.
`-e EXPR'
`--expression EXPR'
Execute given Scheme expression.
`-m PATH'
`--mail-spool=PATH'
Set path to the mailspool directory
`-f PROGFILE'
`--file PROGFILE'
Read Scheme program from PROGFILE.
`-g ARG'
`--guile-command ARG'
Append ARG to the command line passed to Scheme program.
`-{ ... -}'
Pass all command line options enclosed between `-{' and `-}' to
Scheme program.
`-m'
`--mailbox MBOX'
Set default mailbox name.
`-u'
`--user NAME'
Act as local MDA for user NAME.
`-h'
`--help'
Display help message.
`-v'
`--version'
Display program version.
Comsat daemon
=============
Comsatd is the server which receives reports of incoming mail and
notifies users, wishing to get this service. It can be started either
from `inetd.conf' or as a standalone daemon.
Starting comsatd
----------------
`Comsatd' uses following option groups: *Note mailbox::, *Note
daemon::, *Note logging::.
`-c FILE'
`--config FILE'
Read configuration from given FILE. For more information about
comsatd configuration files, see *Note Configuring comsatd::.
`-d'
`--daemon'
Run as a standalone daemon.
`-i'
`--inetd'
The server is started from `/etc/inetd.conf' file:
comsat dgram udp wait root /usr/sbin/comsatd \
comsatd -c /etc/comsat.conf
This is the default operation mode.
`-m PATH'
`--mail-spool=PATH'
Set path to the mailspool directory
`-p NUMBER'
`--port NUMBER'
Specify the port number to listen on. Default is 512.
`-v'
`--version'
Output version and exit successfully.
`-h'
`--help'
Display short help message and exit.
Configuring comsatd
-------------------
The configuration parameters for comsatd are kept in a single
configuration file. The file uses line-oriented format: each line
contains a single statement. Comments are introduced with the `#' sign
and empty lines are ignored. You can specify the configuration file to
use by using `-c' or `--config' command line switch.
The configuration file statements can logically be subdivided into
"General Settings", "Security Settings" and "Access Control Lists". The
following sections address each of these statement group in detail.
General Settings
................
These statements control the general behavior of the comsat daemon:
max-lines NUMBER
Set maximum number of message body lines to be output.
allow-biffrc ( yes | no )
Enable or disable processing of user's `.biffrc' file. By default,
it is enabled.
Security Settings
.................
These statements control the way `comsatd' fights possible flooding
attacks.
max-requests NUMBER
Set maximum number of incoming requests per
`request-control-interval'.
request-control-interval NUMBER
Set the request control interval (seconds).
overflow-delay-time NUMBER
Set the initial amount of time to sleep, after the first overflow
occurs.
overflow-control-interval NUMBER
Set the overflow control interval. If two consecutive overflows
happen within NUMBER seconds, the overflow-delay-time is doubled.
Access Control Lists
....................
Access control lists determine from which addresses `comsatd' will
receive mail notification messages.
The access control lists are introduced in configuration file using
keyword `acl'. General format for an ACL rule is
acl ACTION NETLIST
Here, ACTION specifies the action to be taken when a request arrives
from one of the networks, listed in NETLIST. There are two possible
actions: `allow' and `deny'.
The NETLIST is a whitespace-separated list of network numbers. Each
network number may be specified in one of the following forms:
NETNUM
Means a single host with IP address NETNUM.
NETNUM/NETMASK
NETNUM/MASKLEN
`any'
Denotes any IP address. It is equivalent to `0.0.0.0/0'.
Upon receiving a notification message, `comsatd' compares its source
address against each ACL rule in the order of their appearance in the
configuration file. The first rule that matches the packet determines
whether the message will be processed or rejected. If no matching rule
was found, the default rule applies. Currently, default rule is
acl allow any
If you don't need such behavior, specify the default rule explicitly.
For example, the common use would be:
acl allow 127.0.0.1
acl deny any
which makes `comsatd' receive the notification messages from localhost
only.
A per-user configuration file.
------------------------------
By default, when a notification arrives, `comsatd' prints subject,
from headers and the first five lines from the new message to the user's
tty. The user is allowed to change this behavior by using his own
configuration file. This file should be located in the user's home
directory and should be named `.biffrc'. It must be owned by the user
and have its permissions bits set to 0600. (_Please note_, that the use
of per-user configuration files may be disabled, by specifying
`allow-biffrc no' in the main configuration file, see *note Configuring
comsatd::).
The `.biffrc' file consists of a series of statements. Each
statement occupies one line and defines an action to be taken upon
arrival of a new mail. Very long lines may be split using `\' as the
last character on the line. As usual, comments may be introduced with
`#' character.
The actions specified in `.biffrc' file are executed in turn. The
following actions are defined:
beep
Produce an audible signal.
echo STRING
Output STRING to user's terminal device.
exec PROG ARGLIST
Execute program PROG with arguments from ARGLIST. PROG must be
specified with absolute pathname. It may not be a setuid or setgid
program.
In the description above, STRING denotes any sequence of characters.
This sequence must be enclosed in a pair of double-quotes, if it
contains whitespace characters. The `\' character inside a string
starts a C escape sequence. Following meta-characters may be used in
strings:
$u
Expands to username
$h
Expands to hostname
$H{name}
Expands to value of message header `name'.
$B(C,L)
Expands to message body. C and L give maximum number of characters
and lines in the expansion. When omitted, they default to 400, 5.
Example I.
..........
Dump to the user's terminal the contents of `From' and `Subject'
headers followed by at most 5 lines of message body.
echo "Mail to \a$u@$h\a\n---\n\
From: $H{from}\n\
Subject: $H{Subject}\n\
---\n\
$B(,5)\
---\n"
Example II.
...........
Produce a bell, then pop up the xmessage window on display :0.0 with
the text formatted in the same manner as in the previous example.
beep
exec /usr/X11R6/bin/xmessage \
-display :0.0 -timeout 10 "Mail to $u@$h \n---\n\
From: $H{from}\n\
Subject: $H{Subject}\n\
---\n\
$B(,5)\
---\n"
mailutils-config -- Get the information about the Mailutils build.
==================================================================
This program is designed for developers wishing to link their
programs against libmailbox. It allows to examine the particulars of the
current build of Mailutils and to get the command line parameters
necessary for compiling and linking an application with Mailutils
libraries.
Getting Compiler Flags.
-----------------------
When invoked with the option `--compile', or its short form `-c',
`mailutils-config' prints the flags that must be given to the compiler
for compiling the program using Mailutils functions. An example usage:
cc -omyprog.o `mailutils-config --compile` myprog.c
Getting Loader Flags
--------------------
The `--link', or its short form `-l' prints to the standard output
the loader flags necessary to link a program against Mailutils
libraries.
When invoked without arguments, it produces the flags necessary to
link against the basic library of Mailutils: `libmailbox'. Up to two
arguments may be given that alter this behavior. These are:
`auth'
Print flags to link against `libmuauth', the library adding new
authentication methods to `libmailbox'.
`guile'
Print flags to link against `libmu_scm', the Guile interface
library.
Both arguments may be given simultaneously, e.g.:
cc -omyprog myprog.o `mailutils-config --link auth guile`
Obtaining General Build Information
-----------------------------------
The `--info', or `-i' retrieves the options (flags) used when
building Mailutils. It may be used with or without arguments.
When used without arguments, it prints the list of all build flags,
e.g.:
$ mailutils-config --info
VERSION=0.1.3
USE_LIBPAM
HAVE_LIBLTDL
WITH_GUILE
WITH_READLINE
HAVE_MYSQL
ENABLE_VIRTUAL_DOMAINS
ENABLE_IMAP
ENABLE_POP
ENABLE_MH
ENABLE_SMTP
ENABLE_SENDMAIL
This option also accepts any number of arguments. When these are
given, each argument is treated as a name of a build flag.
`Mailutils-config' checks if such a flag was defined and prints its
full name if so. It exits with zero code if all the flags given on the
command line are defined. Otherwise, it exits with code of 1.
The comparison of the flag names is case-insensitive. The arguments
given need not include the leading prefix (i.e. the characters up to
and including the first underscore character).
Given the previous example, the invocation
$ mailutils --info readline use_libpam pop
will produce the following output:
WITH_READLINE
USE_LIBPAM
ENABLE_POP
and will exit with a zero status.
The following command:
$ mailutils --info readline gssapi pop
will exit with status 1, and will print:
WITH_READLINE
ENABLE_POP
since `WITH_GSSAPI' flag is not defined.
The flags and their meanings are:
USE_LIBPAM
The Mailutils uses PAM libraries.
HAVE_LIBLTDL
The GNU wrapper library `libltdl' is present and is used by
Mailutils. *Note Using libltdl: (libtool)Using libltdl, for more
information on `libltdl' library.
WITH_BDB2
Support for Berkeley DB is compiled in (the package was configured
with `--with-db2' option).
WITH_NDBM
Support for NDBM is compiled in (the package was configured with
`--with-ndbm' option).
WITH_OLD_DBM
Support for old style DBM is compiled in (the package was
configured with `--with-dbm' option).
WITH_GDBM
Support for GDBM is compiled in (the package was configured with
`--with-gdbm' option). *Note Introduction: (gdbm)Top, for
information about this library.
WITH_GSSAPI
Support for GSSAPI is compiled in (the package was configured with
`--with-gssapi' option).
WITH_GUILE
Support for Guile extension language is built (the package was
configured with `--with-guile' option). *Note Overview:
(guile)Top, for information about Guile.
WITH_PTHREAD
The POSIX thread support is compiled in.
WITH_READLINE
The readline support is enabled (the package was configured with
`--with-readline' option). *Note Top: (readline)Top, for more
information.
HAVE_MYSQL
Authentication via MySQL is supported (the package was configured
with `--enable-mysql' option).
ENABLE_VIRTUAL_DOMAINS
Support for mail virtual domains is enabled (the package was
configured with `--enable-virtual-domains' option).
ENABLE_IMAP
Support for IMAP4 protocol is enabled.
ENABLE_POP
Support for POP3 protocol is enabled.
ENABLE_MH
Support for mailboxes in MH format is enabled.
ENABLE_SMTP
Support for SMTP mailer is enabled.
ENABLE_SENDMAIL
Support for Sendmail mailer is enabled.
Reporting Bugs
**************
Email bug reports to <bug-mailutils@gnu.org>. Be sure to include
the word "mailutils" somewhere in the "Subject:" field.
As the purpose of bug reporting is to improve software, please be
sure to include maximum information when reporting a bug. The
information needed is:
* Version of the package you are using.
* Compilation options used when configuring the package.
* Conditions under which the bug appears.
The archives of bug-mailutils mailing list are available from
<http://mail.gnu.org/mailman/listinfo/bug-mailutils>.
Getting news about GNU mailutils
********************************
The two places to look for any news regarding GNU Mailutils are the
Mailutils homepage at <http://www.gnu.org/software/mailutils>, and the
project page at <http://savannah.gnu.org/projects/mailutils>.
The updated versions of this manual are available online from
<http://www.gnu.org/software/mailutils/manual>.
Acknowledgement
***************
In no particular order,
* Jakob Kaivo <jkaivo@ndn.net>,
* Jeff Bailey <jbailey@gnu.org>,
* Sean Perry <shaleh@debian.org>,
* Thomas Fletcher <thomasf@qnx.com>,
* Dave Inglis <dinglis@qnx.com>,
* Brian Edmond <briane@qnx.com>,
* Sam Roberts <sroberts@uniserve.com>,
* Sergey Poznyakoff <gray@Mirddin.farlep.net>,
* Franc,ois Pinard <pinard@IRO.UMontreal.CA>.
* Jordi Mallach <jordi@sindominio.net>
Function Index
**************
This is an alphabetical list of all Mailutils functions.
*sieve_get_data:
See ``Manipulating the Sieve Machine''.
address:
See ``Tests''.
address_aget_email:
See ``Address''.
address_create:
See ``Address''.
address_createv:
See ``Address''.
address_destroy:
See ``Address''.
address_get_comments:
See ``Address''.
address_get_count:
See ``Address''.
address_get_domain:
See ``Address''.
address_get_email:
See ``Address''.
address_get_local_part:
See ``Address''.
address_get_personal:
See ``Address''.
address_get_route:
See ``Address''.
address_is_group:
See ``Address''.
address_t:
See ``Address''.
address_to_string:
See ``Address''.
attribute_copy:
See ``Attribute''.
attribute_create:
See ``Attribute''.
attribute_destroy:
See ``Attribute''.
attribute_is_answered:
See ``Attribute''.
attribute_is_deleted:
See ``Attribute''.
attribute_is_draft:
See ``Attribute''.
attribute_is_equal:
See ``Attribute''.
attribute_is_flagged:
See ``Attribute''.
attribute_is_read:
See ``Attribute''.
attribute_is_recent:
See ``Attribute''.
attribute_is_seen:
See ``Attribute''.
attribute_set_answered:
See ``Attribute''.
attribute_set_deleted:
See ``Attribute''.
attribute_set_draft:
See ``Attribute''.
attribute_set_flagged:
See ``Attribute''.
attribute_set_read:
See ``Attribute''.
attribute_set_recent:
See ``Attribute''.
attribute_set_seen:
See ``Attribute''.
attribute_to_string:
See ``Attribute''.
attribute_unset_answered:
See ``Attribute''.
attribute_unset_deleted:
See ``Attribute''.
attribute_unset_draft:
See ``Attribute''.
attribute_unset_flagged:
See ``Attribute''.
attribute_unset_read:
See ``Attribute''.
attribute_unset_recent:
See ``Attribute''.
attribute_unset_seen:
See ``Attribute''.
auth_authenticate:
See ``Authenticator''.
auth_create:
See ``Authenticator''.
auth_destroy:
See ``Authenticator''.
auth_epilogue:
See ``Authenticator''.
auth_prologue:
See ``Authenticator''.
body_create:
See ``Body''.
body_destroy:
See ``Body''.
body_get_filename:
See ``Body''.
body_get_stream:
See ``Body''.
body_lines:
See ``Body''.
body_set_filename:
See ``Body''.
body_set_stream:
See ``Body''.
body_size:
See ``Body''.
char*:
See ``URL''.
decoder_stream_create:
See ``Stream''.
discard:
See ``Actions''.
encoder_stream_create:
See ``Stream''.
envelope:
See ``Tests''.
envelope_create:
See ``Envelope''.
envelope_date:
See ``Envelope''.
envelope_destroy:
See ``Envelope''.
envelope_get_message:
See ``Envelope''.
envelope_sender:
See ``Envelope''.
envelope_set_date:
See ``Envelope''.
envelope_set_sender:
See ``Envelope''.
exists:
See ``Tests''.
false:
See ``Tests''.
file_stream_create:
See ``Stream''.
fileinto:
See ``Actions''.
folder_close:
See ``Folder''.
folder_create:
See ``Folder''.
folder_delete:
See ``Folder''.
folder_destroy:
See ``Folder''.
folder_get_authority:
See ``Folder''.
folder_get_debug:
See ``Folder''.
folder_get_observable:
See ``Folder''.
folder_get_stream:
See ``Folder''.
folder_get_url:
See ``Folder''.
folder_list:
See ``Folder''.
folder_lsub:
See ``Folder''.
folder_open:
See ``Folder''.
folder_rename:
See ``Folder''.
folder_set_authority:
See ``Folder''.
folder_set_debug:
See ``Folder''.
folder_set_stream:
See ``Folder''.
folder_set_url:
See ``Folder''.
folder_subscribe:
See ``Folder''.
folder_unsubscribe:
See ``Folder''.
header:
See ``Tests''.
header_aget_value:
See ``Headers''.
header_create:
See ``Headers''.
header_destroy:
See ``Headers''.
header_get_stream:
See ``Headers''.
header_get_value:
See ``Headers''.
header_set_lines:
See ``Headers''.
header_set_size:
See ``Headers''.
header_set_value:
See ``Headers''.
iterator_create:
See ``Iterator''.
iterator_current:
See ``Iterator''.
iterator_destroy:
See ``Iterator''.
iterator_first:
See ``Iterator''.
iterator_is_done:
See ``Iterator''.
iterator_next:
See ``Iterator''.
keep:
See ``Actions''.
locker_create:
See ``Locker''.
locker_destroy:
See ``Locker''.
locker_lock:
See ``Locker''.
locker_touchlock:
See ``Locker''.
locker_unlock:
See ``Locker''.
mailbox_append_message:
See ``Mailbox''.
mailbox_close:
See ``Mailbox''.
mailbox_create:
See ``Mailbox''.
mailbox_create_default:
See ``Mailbox''.
mailbox_destroy:
See ``Mailbox''.
mailbox_expunge:
See ``Mailbox''.
mailbox_get_debug:
See ``Mailbox''.
mailbox_get_folder:
See ``Mailbox''.
mailbox_get_locker:
See ``Mailbox''.
mailbox_get_message:
See ``Mailbox''.
mailbox_get_observable:
See ``Mailbox''.
mailbox_get_property:
See ``Mailbox''.
mailbox_get_size:
See ``Mailbox''.
mailbox_get_stream:
See ``Mailbox''.
mailbox_get_ticket:
See ``Mailbox''.
mailbox_get_url:
See ``Mailbox''.
mailbox_is_modified:
See ``Mailbox''.
mailbox_message_unseen:
See ``Mailbox''.
mailbox_messages_count:
See ``Mailbox''.
mailbox_messages_recent:
See ``Mailbox''.
mailbox_open:
See ``Mailbox''.
mailbox_scan:
See ``Mailbox''.
mailbox_set_locker:
See ``Mailbox''.
mailbox_set_stream:
See ``Mailbox''.
mailbox_set_ticket:
See ``Mailbox''.
mailbox_t:
See ``Mailbox''.
mailbox_uidnext:
See ``Mailbox''.
mailbox_uidvalidity:
See ``Mailbox''.
mailer_close:
See ``Mailer''.
mailer_create:
See ``Mailer''.
mailer_destroy:
See ``Mailer''.
mailer_get_debug:
See ``Mailer''.
mailer_get_observable:
See ``Mailer''.
mailer_get_property:
See ``Mailer''.
mailer_get_stream:
See ``Mailer''.
mailer_get_url:
See ``Mailer''.
mailer_open:
See ``Mailer''.
mailer_send_message:
See ``Mailer''.
mailer_set_debug:
See ``Mailer''.
mailer_set_stream:
See ``Mailer''.
mapfile_stream_create:
See ``Stream''.
memory_stream_create:
See ``Stream''.
message_create:
See ``Message''.
message_create_attachment:
See ``Message''.
message_destroy:
See ``Message''.
message_encapsulate:
See ``Message''.
message_get_attribute:
See ``Message''.
message_get_body:
See ``Message''.
message_get_envelope:
See ``Message''.
message_get_header:
See ``Message''.
message_get_num_parts:
See ``Message''.
message_get_observable:
See ``Message''.
message_get_part:
See ``Message''.
message_get_stream:
See ``Message''.
message_get_uid:
See ``Message''.
message_get_uidl:
See ``Message''.
message_is_multipart:
See ``Message''.
message_save_attachment:
See ``Message''.
message_set_attribute:
See ``Message''.
message_set_body:
See ``Message''.
message_set_envelope:
See ``Message''.
message_set_header:
See ``Message''.
message_set_stream:
See ``Message''.
message_set_uidl:
See ``Message''.
message_unencapsulate:
See ``Message''.
mu-address-get-comments:
See ``Address Functions''.
mu-address-get-count:
See ``Address Functions''.
mu-address-get-domain:
See ``Address Functions''.
mu-address-get-email:
See ``Address Functions''.
mu-address-get-local:
See ``Address Functions''.
mu-address-get-personal:
See ``Address Functions''.
mu-closelog:
See ``Log Functions''.
mu-logger:
See ``Log Functions''.
mu-mailbox-append-message:
See ``Mailbox Functions''.
mu-mailbox-close:
See ``Mailbox Functions''.
mu-mailbox-expunge:
See ``Mailbox Functions''.
mu-mailbox-get-message:
See ``Mailbox Functions''.
mu-mailbox-get-port:
See ``Mailbox Functions''.
mu-mailbox-get-url:
See ``Mailbox Functions''.
mu-mailbox-messages-count:
See ``Mailbox Functions''.
mu-mailbox-open:
See ``Mailbox Functions''.
mu-mailbox-url:
See ``Mailbox Functions''.
mu-message-copy:
See ``Message Functions''.
mu-message-delete:
See ``Message Functions''.
mu-message-get-body:
See ``Message Functions''.
mu-message-get-flag:
See ``Message Functions''.
mu-message-get-header:
See ``Message Functions''.
mu-message-get-header-fields:
See ``Message Functions''.
mu-message-get-lines:
See ``Message Functions''.
mu-message-get-port:
See ``Message Functions''.
mu-message-get-sender:
See ``Message Functions''.
mu-message-get-size:
See ``Message Functions''.
mu-message-get-user-flag:
See ``Message Functions''.
mu-message-send:
See ``Message Functions''.
mu-message-set-flag:
See ``Message Functions''.
mu-message-set-header:
See ``Message Functions''.
mu-message-set-header-fields:
See ``Message Functions''.
mu-message-set-user-flag:
See ``Message Functions''.
mu-mime-add-part:
See ``MIME Functions''.
mu-mime-create:
See ``MIME Functions''.
mu-mime-get-message:
See ``MIME Functions''.
mu-mime-get-num-parts:
See ``MIME Functions''.
mu-mime-get-part:
See ``MIME Functions''.
mu-mime-multipart?:
See ``MIME Functions''.
mu-openlog:
See ``Log Functions''.
mu_auth_data:
See ``Data Types''.
mu_auth_data_alloc:
See ``Module Creation and Destruction''.
mu_auth_data_free:
See ``Module Creation and Destruction''.
mu_auth_fp:
See ``Data Types''.
mu_auth_generic_module:
See ``Existing Modules''.
mu_auth_init:
See ``Initializing the libmuauth''.
mu_auth_module:
See ``Data Types''.
mu_auth_nosupport:
See ``Existing Modules''.
mu_auth_pam_module:
See ``Existing Modules''.
MU_AUTH_REGISTER_ALL_MODULES:
See ``Initializing the libmuauth''.
mu_auth_register_module:
See ``Module Creation and Destruction''.
mu_auth_runlist:
See ``Obtaining Authorization Information''.
mu_auth_sql_module:
See ``Existing Modules''.
mu_auth_system_module:
See ``Existing Modules''.
mu_auth_virtual_module:
See ``Existing Modules''.
mu_authenticate:
See ``Obtaining Authorization Information''.
mu_get_auth_by_name:
See ``Obtaining Authorization Information''.
mu_get_auth_by_uid:
See ``Obtaining Authorization Information''.
MU_STREAM_APPEND:
See ``Stream''.
MU_STREAM_CREAT:
See ``Stream''.
MU_STREAM_NO_CHECK:
See ``Stream''.
MU_STREAM_NO_CLOSE:
See ``Stream''.
MU_STREAM_NONBLOCK:
See ``Stream''.
MU_STREAM_RDWR:
See ``Stream''.
MU_STREAM_READ:
See ``Stream''.
MU_STREAM_WRITE:
See ``Stream''.
numaddr:
See ``Tests''.
parse822_addr_spec:
See ``Parse822 -- Functions for Parsing RFC 822 Headers''.
parse822_address:
See ``Parse822 -- Functions for Parsing RFC 822 Headers''.
parse822_address_list:
See ``Parse822 -- Functions for Parsing RFC 822 Headers''.
parse822_domain:
See ``Parse822 -- Functions for Parsing RFC 822 Headers''.
parse822_domain_literal:
See ``Parse822 -- Functions for Parsing RFC 822 Headers''.
parse822_domain_ref:
See ``Parse822 -- Functions for Parsing RFC 822 Headers''.
parse822_field_body:
See ``Parse822 -- Functions for Parsing RFC 822 Headers''.
parse822_field_name:
See ``Parse822 -- Functions for Parsing RFC 822 Headers''.
parse822_group:
See ``Parse822 -- Functions for Parsing RFC 822 Headers''.
parse822_local_part:
See ``Parse822 -- Functions for Parsing RFC 822 Headers''.
parse822_mail_box:
See ``Parse822 -- Functions for Parsing RFC 822 Headers''.
parse822_quote_local_part:
See ``Parse822 -- Functions for Parsing RFC 822 Headers''.
parse822_quote_string:
See ``Parse822 -- Functions for Parsing RFC 822 Headers''.
parse822_route:
See ``Parse822 -- Functions for Parsing RFC 822 Headers''.
parse822_route_addr:
See ``Parse822 -- Functions for Parsing RFC 822 Headers''.
parse822_sub_domain:
See ``Parse822 -- Functions for Parsing RFC 822 Headers''.
parse822_unix_mbox:
See ``Parse822 -- Functions for Parsing RFC 822 Headers''.
redirect:
See ``Actions''.
reject:
See ``Actions''.
sieve_abort:
See ``Logging and Diagnostic Functions''.
sieve_action_log_t:
See ``Sieve Data Types''.
sieve_action_lookup:
See ``Symbol Space Functions''.
sieve_comparator_t:
See ``Sieve Data Types''.
sieve_compile:
See ``Compiling and Executing the Script''.
sieve_data_type:
See ``Sieve Data Types''.
sieve_debug:
See ``Logging and Diagnostic Functions''.
sieve_destructor_t:
See ``Sieve Data Types''.
sieve_disass:
See ``Compiling and Executing the Script''.
sieve_error:
See ``Logging and Diagnostic Functions''.
sieve_get_daemon_email:
See ``Manipulating the Sieve Machine''.
sieve_get_debug_level:
See ``Manipulating the Sieve Machine''.
sieve_get_mailer:
See ``Manipulating the Sieve Machine''.
sieve_get_message:
See ``Manipulating the Sieve Machine''.
sieve_get_message_num:
See ``Manipulating the Sieve Machine''.
sieve_get_ticket:
See ``Manipulating the Sieve Machine''.
sieve_handler_t:
See ``Sieve Data Types''.
sieve_is_dry_run:
See ``Manipulating the Sieve Machine''.
sieve_load_ext:
See ``Symbol Space Functions''.
sieve_log_action:
See ``Logging and Diagnostic Functions''.
sieve_machine_add_destructor:
See ``Manipulating the Sieve Machine''.
sieve_machine_destroy:
See ``Manipulating the Sieve Machine''.
sieve_machine_init:
See ``Manipulating the Sieve Machine''.
sieve_machine_t:
See ``Sieve Data Types''.
sieve_mailbox:
See ``Compiling and Executing the Script''.
sieve_malloc:
See ``Memory Allocation''.
sieve_message:
See ``Compiling and Executing the Script''.
sieve_mfree:
See ``Memory Allocation''.
sieve_mrealloc:
See ``Memory Allocation''.
sieve_mstrdup:
See ``Memory Allocation''.
sieve_parse_error_t:
See ``Sieve Data Types''.
sieve_printf_t:
See ``Sieve Data Types''.
sieve_register_action:
See ``Symbol Space Functions''.
sieve_register_comparator:
See ``Symbol Space Functions''.
sieve_register_test:
See ``Symbol Space Functions''.
sieve_retrieve_t:
See ``Sieve Data Types''.
sieve_runtime_tag_t:
See ``Sieve Data Types''.
sieve_set_daemon_email:
See ``Manipulating the Sieve Machine''.
sieve_set_debug:
See ``Manipulating the Sieve Machine''.
sieve_set_debug_level:
See ``Manipulating the Sieve Machine''.
sieve_set_error:
See ``Manipulating the Sieve Machine''.
sieve_set_logger:
See ``Manipulating the Sieve Machine''.
sieve_set_mailer:
See ``Manipulating the Sieve Machine''.
sieve_set_parse_error:
See ``Manipulating the Sieve Machine''.
sieve_set_ticket:
See ``Manipulating the Sieve Machine''.
sieve_tag_checker_t:
See ``Sieve Data Types''.
sieve_tag_def_t:
See ``Sieve Data Types''.
sieve_tag_lookup:
See ``Symbol Space Functions''.
sieve_test_lookup:
See ``Symbol Space Functions''.
sieve_type_str:
See ``Manipulating the Sieve Machine''.
sieve_value_t:
See ``Sieve Data Types''.
size:
See ``Tests''.
stdio_stream_create:
See ``Stream''.
stop:
See ``Actions''.
stream_close:
See ``Stream''.
stream_create:
See ``Stream''.
stream_destroy:
See ``Stream''.
stream_flush:
See ``Stream''.
stream_get_fd:
See ``Stream''.
stream_get_flags:
See ``Stream''.
stream_get_state:
See ``Stream''.
stream_is_seekable:
See ``Stream''.
stream_open:
See ``Stream''.
stream_read:
See ``Stream''.
stream_readline:
See ``Stream''.
stream_setbufsiz:
See ``Stream''.
stream_size:
See ``Stream''.
stream_truncate:
See ``Stream''.
stream_write:
See ``Stream''.
string_to_attribute:
See ``Attribute''.
tcp_stream_create:
See ``Stream''.
true:
See ``Tests''.
url_create:
See ``URL''.
url_decode:
See ``URL''.
url_destroy:
See ``URL''.
url_get_host:
See ``URL''.
url_get_passwd:
See ``URL''.
url_get_path:
See ``URL''.
url_get_port:
See ``URL''.
url_get_query:
See ``URL''.
url_get_scheme:
See ``URL''.
url_get_user:
See ``URL''.
url_parse:
See ``URL''.
Program Index
*************
comsatd:
See ``Comsat daemon''.
frm:
See ``frm -- List headers from a mailbox.''.
guimb:
See ``guimb -- A mailbox scanning and processing language.''.
imap4d:
See ``IMAP4 daemon''.
mail:
See ``mail -- send and receive mail.''.
mail.local:
See ``mail.local -- Deliver mail to the local mailbox.''.
mailutils-config:
See ``mailutils-config -- Get the information about the Mailutils build.''.
messages:
See ``messages -- Count the number of messages in a mailbox.''.
pop3d:
See ``POP3 daemon''.
readmsg:
See ``readmsg -- Extract messages from a folder.''.
sieve:
See ``sieve''.
Concept Index
*************
This is a general index of all issues discussed in this manual
#include, sieve:
See ``Sieve #include directive''.
#searchpath, sieve:
See ``Sieve #searchpath directive''.
:address:
See ``address -- Specifies the default email address and domain.''.
:auth:
See ``auth -- Authentication-specific options.''.
:daemon:
See ``daemon -- Options common for daemon programs.''.
:logging:
See ``logging -- Logging control options.''.
:mailbox:
See ``mailbox -- Specifies the mail spool location, and locking strategy.''.
:mailer:
See ``mailer -- Sets the default mailer URL.''.
:sieve:
See ``Sieve specific options''.
Acknowledgement:
See ``Acknowledgement''.
Address:
See ``Address''.
Attribute:
See ``Attribute''.
authentication:
See ``Authorization and authentication principles.''.
Authentication Library:
See ``Authentication Library''.
Authenticator:
See ``Authenticator''.
authorization:
See ``Authorization and authentication principles.''.
Body:
See ``Body''.
Envelope:
See ``Envelope''.
Folder:
See ``Folder''.
Framework:
See ``Framework''.
Headers:
See ``Headers''.
IMAP4 namespace:
See ``Imap4d Namespace''.
Introduction:
See ``Introduction''.
Iterator:
See ``Iterator''.
libmu_scm:
See ``Mailutils to Scheme interface''.
libmuauth:
See ``Authentication Library''.
libmuauth modules:
See ``Existing Modules''.
libmuauth, data types:
See ``Data Types''.
libmuauth, linking with:
See ``Using Libmuauth in Your Programs''.
libmuauth, obtaining authorization information:
See ``Obtaining Authorization Information''.
libsieve:
See ``Sieve Library''.
linking with libmuauth:
See ``Using Libmuauth in Your Programs''.
Locker:
See ``Locker''.
Mailbox:
See ``Mailbox''.
Mailer:
See ``Mailer''.
Mailutils configuration file:
See ``Mailutils configuration file''.
mailutils.rc:
See ``Mailutils configuration file''.
mailutils.rc, an example:
See ``A sample configuration file.''.
Message:
See ``Message''.
namespace:
See ``Imap4d Namespace''.
Programs:
See ``Programs''.
Reporting Bugs:
See ``Reporting Bugs''.
Scheme:
See ``Mailutils to Scheme interface''.
Sieve Library:
See ``Sieve Library''.
Sieve preprocessor statements, a GNU extension:
See ``Preprocessor''.
Stream:
See ``Stream''.
URL:
See ``URL''.
using libmuauth:
See ``Using Libmuauth in Your Programs''.
...Table of Contents...