mailutils, SDK.

version 0.0.9b, 14 October 2001

Alain Magloire et al.

Copyright \begin{matrix}c \\ ◯ \end{matrix} 1999, 2000, 2001 Free Software Foundation, Inc.

Published by the Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA 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

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2 Concrete API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 3 Framework. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 4 Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 5 Reporting Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 6 Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

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

1.1 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: Confor-

mance 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

2 Concrete API

2.1 POP3

/* Prefix pop3 is reserved */
#include <mailutils/pop3.h>

The purpose of the Post Office Protocol Version 3 (POP3) is to permit a client to download a maildrop from a remote server. It does not provide complex or extensive operation on the maildrop. When the client successfully authenticates, the server acquires an exclusive access lock on the mailbox and holds it the entire duration of the session. After the authentication, the session enters transaction state and the client may issues commands to access messages in the mailbox.

• Authorization state • User

• Pass

• Quit

• Capa (extension)

• Auth (extension)

• Transaction state • Stat

• List

• Retr

• Dele

• Noop

• Rset

• Top

• Uidl (extension)

• Quit

• Capa (extension) When the command Quit is issue the session enters the update state. The servers removes

all messages marked deleted, releases the exclusive lock and closes the TCP connection.

2.1.1 Commands

An opaque structure pop3 t is use as a handle for the session, it is allocated and initialized by calling pop3_create (). All Functions will wait for a reply from the POP3 server before returning. The duration of the wait can be set by calling pop3_set_timeout (), the default is 10 minutes^{1}. Once a successful connection is established with pop3_connect (), two builtins authentications are provided pop3_apop () or pop3_user ()/pop3_pass (). The pop3_stat () and pop3_list () functions can be use to get the number and size of messages. Downloading of messages is done via a stream provided by pop3_retr () or pop3_top ()^{2}. The stream_t should be destroyed to indicate to the library that the action is finished. POP3 only provide a single channel for operation, it means only one operation can be done at a time, all the functions will return MU ERROR OPERATION IN PROGRESS if call during another operation. The functions pop3_list_all (), pop3_uidl_all () and pop3_

capa () return iterators pop3_list_current (), pop3_uidl_current () are provided as

cover function to format the string return by iterator_current (), iterator_destroy () must be call to release any resources.

In a multithreaded application, only one thread should access pop3 t handles.

2.1.1.1 Initialization

Function int pop3 create (pop3_t * pop3)

Allocate and initialize a pop3 handle.

MU_ERROR_NO_MEMORY
MU_ERROR_INVALID_PARAMETER

Function void pop3 destroy (pop3_t *pop3)

When a POP3 session is finished, the structure must be free ()’ed to reclaim memory.

Function int pop3 connect (pop3_t, const char *host, unsigned port, int

flags) A connection is established by calling pop3d_open (), the previous connection is close first. If non-blocking the function should be recalled until the return value is not MU ERROR TRY AGAIN or MU ERROR IN PROGRESS.

MU_ERROR_NO_MEMORY
MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_IN_PROGRESS
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED
MU_ERROR_TIMEOUT
MU_ERROR_NO_LOCK

1 Caution: Although the RFC 1939 specifies that the minimum default timeout is ten minutes many servers has shorter idle period, care should be taken to at least send a pop3_noop () between lengthy period of times.

2 Caution: Some Internet Service Providers do not permit to leave mail on server and the message will be deleted once downloaded.

2.1.1.2 Carrier

Function int pop3 set carrier (pop3_t, stream_t carrier); The type of stream use to contact as server will be set to carrier in the pop3 t handle. Any previous carrier stream in the handle, will be close and release.

MU_ERROR_INVALID_PARAMETER

Function int pop3 get carrier (pop3_t, stream_t *carrier); Return the pop3 t carrier. If none was set, a new tcp stream will be created.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY

2.1.1.3 Apop

Function int pop3 apop (pop3_t, const char *user, const char *secret)

Apop offers an alternative to User/Pass authentication. For intermittent use of POP3, like checking for new mail, it is the preferred the authentication. It reduces the risk of password capture. The user and the shared secret are pass to pop3_apop (), the MD5 digest is calculated by applying the times tamp given by the server in the greeting followed by the secret.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

2.1.1.4 Capa

Function int pop3 capa (pop3_t, pop3_capa_iterator_t *iterator)

The Capa command is send to the sever and the list of capabilities is return in an iterator. iterator_current () gives an allocated string that should be free ()’ed. Caution: The iterator must be destroy after use, it will discard any remaining responses from CAPA and clear the way for new operations.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED
     #include <stdio.h>
     #include <stdlib.h>
     #include <mailutils/pop3.h>

     void print_capabilities (pop3_t pop3)
     {
        iterator_t iterator;
        status = pop3_capa (pop3, &iterator);
        if (status == 0)
         {
             for (iterator_first (iterator);
                  !iterator_is_done (iterator);
                  iterator_next (iterator))
               {
                   char *capa;
                   if (iterator_current (iterator, &capa) == 0)
                    {;
                        printf ("CAPA: %s\n", capa);
                        free (capa);
                    }
               }
             pop3_capa_destroy (&iterator);
         }
        else
          printf ("NONE\n");
     }

2.1.1.5 Dele

Function int pop3 dele (pop3_t, unsigned msgno)

Sends a Dele to the servers who will mark the msgno for deletion. The msgno may not refer to a message already marked deleted. If successful any future reference to msgno in other operations will be an error, unless unmarked by RSET.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

2.1.1.6 List

Function int pop3 list (pop3_t, unsigned msgno, size_t *size)

Sends a List for a specific msgno and returns the size.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function int pop3 list all (pop3_t, iterator_t *iterator)

Sends A List with no argument to the server. The iterator must be destroy after use, it will discard any remaining response from LIST and clear the way for new operations. A cover function pop3_list_current () around to scan properly the

string return by the iterator_current ().
     #include <stdio.h>
     #include <stdlib.h>
     #include <mailutils/pop3.h>
     void print_list (pop3_t pop3)
     {
        iterator_t iterator;
        status = pop3_list_all (pop3, &iterator);
        if (status == 0)
         {
             for (iterator_first (iterator);
                  !iterator_is_done (iterator);
                  iterator_next (iterator))
               {
                   unsigned int msgno, size;
                   if (pop3_list_current (iterator, &msgno, &size) == 0)
                    {
                        printf ("LIST: %d %d\n", msgno, size);
                    }
               }
             iterator (&iterator);
         }
        else
          printf ("NONE\n");
     }
MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function int pop3 list current (pop3_t, unsigned int *msgno, size_t *size)

Cover functions around iterator_current () from an iterator created by pop3_ list_all () to format the result.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

2.1.1.7 Noop

Function int pop3 noop (pop3_t)

Sends a NOOP, useful to reset the timeout on the server.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

2.1.1.8 Pass

Function int pop3 pass (pop3_t, const char *passwd)

Sends the PASS, to authenticate after the USER command.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

2.1.1.9 Quit

Function int pop3 quit (pop3_t)

Enter the UPDATE state. The server will delete all messages marked deleted before closing the connection.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

2.1.1.10 Retr

Function int pop3 retr (pop3_t, unsigned msgno, stream_t *)

If successful a stream_t is created to allow downloading of the message, byte-stuff lines or handle internally, CRLFs are converted to LF. All other operations will fail until the stream is destroyed by the caller.

     #include <stdio.h>
     #include <mailutils/pop3.h>
     int

     print_message (pop3_t pop3, unsigned int msgno)
     {
        stream_t stream;
        int status = pop3_retr (pop3, msgno, &stream);
        if (status == 0)
         {
            size_t n = 0;
            char buf[128];
            while ((stream_readline (stream, buf, sizeof buf, &n) == 0)
                   && n)
              printf ("%s", buf);
            stream_release (stream);
         }
        return status;
     }
MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

2.1.1.11 Rset

Function int pop3 rset (pop3_t)

Sends a RSET to unmark the messages marked as deleted.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

2.1.1.12 Stat

Function int pop3 stat (pop3_t, unsigned msgno, unsigned *msg count,

    size_t *size)

The number of messages in the mailbox and the size of the mailbox in octets. Caution: The size is in RFC822 where line termination is CRLF, messages marked as deleted are not counted in either total.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

2.1.1.13 Top

Function int pop3 top (pop3_t, unsigned int msgno, unsigned int lines,
    stream_t *stream)

If successful a stream is created to allow downloading of the header, byte-stuff lines or handle internally, CRLFs are converted to LF. All other operations will failed until the stream is destroyed by the caller.

     #include <stdio.h>
     #include <mailutils/pop3.h>
     int
     print_top (pop3_t pop3, unsigned int msgno, unsigned int lines)
     {
         stream_t stream;
         int status = pop3_top (pop3, msgno, lines, &stream);
         if (status == 0)
          {
             size_t n = 0;
             char buf[128];
             while ((stream_readline (stream, buf, sizeof buf, &n) == 0)
                    && n)
               printf ("%s", buf);
             stream_release (stream);
          }
       return status;
     }
MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

2.1.1.14 Uidl

Function int pop3 uidl (pop3_t, unsigned int msgno, char **uidl)

The Uniq Identifier is return in uidl, the string must be free ()’ed, by the caller.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function int pop3 uidl all (pop3_t, iterator_t * iterator)

An iterator object is return to iterate through the response and must be destroyed by the caller.

     #include <stdio.h>
     #include <stdlib.h>
     #include <mailutils/pop3.h>
     void print_uidl (pop3_t pop3)
     {
        iterator_t iterator;
        status = pop3_uidl_all (pop3, &iterator);
        if (status == 0)
         {
             for (iterator_first (iterator);
                  !iterator_is_done (iterator);
                  iterator_next (iterator))
               {
                   unsigned int msgno;
                   char *uidl;
                   if (pop3_uidl_current (iterator, &msgno, &uidl) == 0)
                    {
                        printf ("LIST: %d %s\n", msgno, uidl);
                        free (uidl);
                    }
               }
             iterator (&iterator);
         }
        else
          printf ("NONE\n");
     }
MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function int pop3 uidl current (iterator_t iterator, unsigned int *msgno,

    char **uidl)

Cover functions around iterator_current () from an iterator created by pop3_ uidl_all () to format the result. The variable uidl should be free ()’ed.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

2.1.1.15 User

Function int pop3 user (pop3_t, const char *user)

Sends the User command.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

2.1.1.16 Help functions

Function int pop3 writeline (pop3_t, const char *format, ...); Copy in the internal buffer of pop3_t the string, pop3_send () should be called later to flush the string to the POP3 server.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

Function int pop3 sendline (pop3_t, const char *cmd);

Cover function for pop3_writeline () and pop3_send ().
MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED
Function int pop3 send (pop3_t, const char *cmd);

Flushes out the strings written by pop3_writeline () in the internal buffer to the channel.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED
Function int pop3 response (pop3_t, char *buffer, size_t len, size_t

*plen) The last response from the last command is save and can be examine after a failure or success.

MU_ERROR_INVALID_PARAMETER

Chapter 2: Concrete API 12

MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED

2.1.1.17 Timeout

Function int pop3 set timeout (pop3_t, int timeout)

Set the timeout time for I/O on the carrier. The default is 10 minutes. The timeout is given in milliseconds.

Function int pop3 get timeout (pop3_t, int *timeout)

Get the timeout time for I/O on the carrier. The timeout is given in milliseconds.

2.2 IMAP4

/* Prefix imap4 is reserved */
#include <mailutils/imap4.h>

Internet Message Access Protocol - Version (4rev1). Not implemented.

2.2.1 Commands 2.2.1.1 Initialization

Function int imap4 create (imap4_t *)

Function int imap4 open (imap4_t, const char *hostname, unsigned int

port, int flags)

Function int imap4d set timeout (imap4_t, unsigned int seconds)

2.2.1.2 Append

Function int imap4 append (imap4_t)

2.2.1.3 Capability

Function int imap4 capability (imap4_t)

2.2.1.4 Create

Function int imap4 create mailbox (imap4_t, const char *mbox)

Chapter 2: Concrete API 13

2.2.1.5 Check

Function int imap4 check (imap4_t)

2.2.1.6 Close

Function int imap4 close (imap4_t)

2.2.1.7 Copy

Function int imap4 copy (imap4_t)

2.2.1.8 UID Copy

Function int imap4 uid copy (imap4_t)

2.2.1.9 Delete

Function int imap4 delete (imap4_t)

2.2.1.10 Fetch

Function int imap4 fetch (imap4_t)

2.2.1.11 UID Fetch

Function int imap4 uid fetch (imap4_t)

2.2.1.12 Examine

Function int imap4 examine (imap4_t)

2.2.1.13 Expunge

Function int imap4 expunge (imap4_t)

2.2.1.14 List

Function int imap4 list (imap4_t)

2.2.1.15 Lsub

Function int imap4 lsub (imap4_t)

Chapter 2: Concrete API 14

2.2.1.16 Namespace

Function int imap4 namespace (imap4_t)

2.2.1.17 Rename

Function int imap4 rename (imap4_t)

2.2.1.18 Search

Function int imap4 search (imap4_t)

2.2.1.19 UID Search

Function int imap4 uid search (imap4_t)

2.2.1.20 Select

Function int imap4 select (imap4_t)

2.2.1.21 Status

Function int imap4 status (imap4_t)

2.2.1.22 Store

Function int imap4 store (imap4_t)

2.2.1.23 UID Store

Function int imap4 uid store (imap4_t)

2.2.1.24 Subscribe

Function int imap4 subscribe (imap4_t)

2.2.1.25 Unsubscribe

Function int imap4 unsubscribe (imap4_t)

2.3 Mbox

     /* Prefix mbox is reserved */
     #include <mailutils/mbox.h>

The most common mailbox format on UNIX platform is mbox. Mbox file is messages separated by the special format string.

        From SP envelope-sender SP date [SP moreinfo]

"From " is sometimes call the From .

envelope-sender

is a word with no space.

date has the same format as asctime ()

moreinfo are optional values that are seldom used.

A mbox t is created, initialized and destroyed by mbox_create () and mbox_destroy (). When opening, mbox_open () will do a quick check to see if the format is a valid format or an empty file. The scanning of the mailbox is done by mbox_scan (). The function, mbox_ scan (), takes callback functions called during the scanning to provide information. The scanning will cache some of the headers fields for speed. Closing the mailbox, mbox_close () will free any resources like, headers cache, locks etc ... All the messages with attributes marked deleted will only be removed on mbox_expunge (). If only the attributes need to be save but the messages not removed, this can be done by mbox_save_attributes (). New messages are added with mbox_append (). Attributes are saved in the Status: header field, Read is ’R’, Seen is ’O’, Deleted is ’d’ and Reply is ’r’.

2.3.0.1 Initialization

Function int mbox create (mbox_t *mbox)

Allocate and initialize a mbox handle.

     MU_ERROR_NO_MEMORY
     MU_ERROR_INVALID_PARAMETER

Function void mbox destroy (mbox_t mbox)

When a POP3 session is finished, the structure must be free ()’ed to reclaim memory.

2.3.0.2 Carrier

Function int mbox set carrier (mbox_t, stream_t carrier); Another type of stream can be provided to work on, the carrier is set in the mbox t handle. Any previous carrier stream in the handle, will be close and release. Since the parsing code maintain only the offsets off the message the carrier stream must be seekable.

     MU_ERROR_INVALID_PARAMETER

Function int mbox get carrier (mbox_t, stream_t *carrier); Return the mbox t carrier. If none was set, a new file stream will be created.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY

Function int mbox open (mbox_t, const char *filename, int flags)

Open carrier stream with filename and flags. The stream will be quickly examine to see if it is a mbox format.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY
MU_ERROR_NO_ENTRY
MU_ERROR_NO_ACCESS
MU_ERROR_NOT_SUPPORTED

Function int mbox close (mbox_t)

Close the carrier stream and resources particular to the mailbox.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY

Function int mbox uidnext (mbox_t, unsigned long *uidnext)

Return the uidnext, if the mbox t was not scan mbox_scan () is called first.

MU_ERROR_INVALID_PARAMETER
same as mbox_scan ()

Function int mbox uidvalidity (mbox_t, unsigned long *uidvalidity)

Return the uidvalidity, if the mbox t was not scan mbox_scan () is called first.

MU_ERROR_INVALID_PARAMETER
same as mbox_scan ()

Function int mbox get attribute (mbox_t, unsigned int msgno,

    attribute_t *attribute)

Return an attribute to indicate the status of message number msgno.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY

Function int mbox get separator (mbox_t, unsigned int msgno, char

**sep) Return an allocated string in sep containing the value "From " separating each message in Unix mbox format. The string should be free ()ed by the caller.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY

Function int mbox set separator (mbox_t, unsigned int msgno, const char

*sep) The variable sep should contain a valid "From " separator that will be use when the expunging.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY
Function int mbox get hstream (mbox_t, unsigned int msgno, stream_t

*stream) Return a stream to read the header of message msgno. The stream should be destroy after usage.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY
Function int mbox set hstream (mbox_t, unsigned int msgno, stream_t

stream) Use stream when expunging for message msgno.

MU_ERROR_INVALID_PARAMETER
Function int mbox set hsize (mbox_t, unsigned int msgno, unsigned int

*size) Return the size of message msgno.

MU_ERROR_INVALID_PARAMETER
Function int mbox set hlines (mbox_t, unsigned int msgno, unsigned int

*size) Return the number of lines of message msgno.

MU_ERROR_INVALID_PARAMETER
Function int mbox get bstream (mbox_t, unsigned int msgno, stream_t

*stream) Return a stream to read the body of message msgno. The stream should be destroy after usage.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY
Function int mbox set bstream (mbox_t, unsigned int msgno, stream_t

stream) Use stream when expunging for message msgno.

MU_ERROR_INVALID_PARAMETER
Function int mbox set bsize (mbox_t, unsigned int msgno, unsigned int

*size) Return the size of message msgno.

MU_ERROR_INVALID_PARAMETER

Function int mbox set blines (mbox_t, unsigned int msgno, unsigned int

*size) Return the number of lines of message msgno.

MU_ERROR_INVALID_PARAMETER

Function int mbox get size (mbox_t, unsigned int *size)

Return the size of mailbox.

MU_ERROR_INVALID_PARAMETER

Function int mbox save (mbox_t)

Save the changes to the messages back to the mailbox, but do not remove messages mark for deletion in the process.

MU_ERROR_INVALID_PARAMETER

Function int mbox mak deleted (mbox_t, unsigned int msgno)

Mark msgno for deletion.

MU_ERROR_INVALID_PARAMETER

Function int mbox unmak deleted (mbox_t, unsigned int msgno)

Unmark msgno if it was marked for deletion.

MU_ERROR_INVALID_PARAMETER

Function int mbox expunge (mbox_t)

Save the changes to the mailbox and in the process remove all messages marked for deletion.

MU_ERROR_INVALID_PARAMETER
Function int mbox append (mbox_t, const char *sep, stream_t stream)

Append to the mailbox an rfc822 message represented by stream. The variable sep should contain a valid "From " separator or NULL to get the default.

MU_ERROR_INVALID_PARAMETER
Function int mbox append hb (mbox_t, const char *sep, stream_t

hstream, stream_t bstream) Append to the mailbox an rfc822 message represented by a header, hstream, and a body, bstream. The variable sep should contain a valid "From " separator or NULL to get the default.

MU_ERROR_INVALID_PARAMETER
Function int mbox scan (mbox_t, unsigned int start, unsigned int *count)

Start scanning the mailbox for new messages. The variable start can be a message number starting point. The result of the scanning will be in count. The scanning will trigger the mbox_newmsg_cb() callback for each new message and mbox_progress_cb () at different interval to notify progression. The return values of the those callback should be 0 is different then 0 the scanning will be stop an the function returns MU ERROR INTERRUPTED.

MU_ERROR_INVALID_PARAMETER
MU_ERROR_INTERRUPTED
MU_ERROR_NO_MEMORY

Function int mbox set progress cb (mbox_t, int (*callback) (int, void *)),

    void *arg)

Set the callback function for progress. The variable arg will be pass back in the callback as the second argument.

MU_ERROR_INVALID_PARAMETER

Function int mbox set newmsg cb (mbox_t, int (*callback) (int, void *)),

    void *arg)

Set the callback function for new messages. The variable arg will be pass back in the callback as the second argument.

MU_ERROR_INVALID_PARAMETER

2.4 Mh

/* Prefix mh is reserved */
#include <mailutils/mh.h>

Mail Handler mailbox format. Not implemented.

2.5 Maildir

/* Prefix maildir is reserved */
#include <mailutils/maildir.h>

QMail mailbox format. Not implemented.

2.6 SMTP

/* Prefix smtp is reserved */
#include <mailutils/smtp.h>

Simple Mail Transfer Protocol. Not implemented.

2.6.1 Commands

2.6.1.1 Initialization

Function int smtp create (smtp_t *)

Function void smtp destroy (smtp_t *)

Function int smtp open (smtp_t, const char *host, unsigned int port, int

flags)

Chapter 2: Concrete API 20

2.6.1.2 Data

Function int smtp data (smtp_t, stream_t stream)

2.6.1.3 Helo

Function int smtp helo (smtp_t, const char *domain) Function int smtp ehlo (smtp_t, const char *domain)

2.6.1.4 Expn

Function int smtp expn (smtp_t, const char *list, iterator_t *)

2.6.1.5 Help

Function int smtp help (smtp_t, const char *help, iterator_t *)

2.6.1.6 Mail From

Function int smtp mail from (smtp_t, const char *address, const char

*param)

2.6.1.7 Noop

Function int smtp noop (smtp_t)

2.6.1.8 Quit

Function int smtp quit (smtp_t)

2.6.1.9 Recpt To

Function int smtp rcpt to (smtp_t, const char *address, const char

*param)

2.6.1.10 Reset

Function int smtp reset (smtp_t)

2.6.1.11 Verify

Function int smtp verify (smtp_t, const char *user)

2.6.1.12 Help functions

Function extern int smtp_readline (smtp_t, char *buffer, size_t len, size_t

*len)

Function extern int smtp_response (smtp_t, char *buffer, size_t len, size_t

*len)

Function extern int smtp_writeline (smtp_t, const char *format, ...)
Function extern int smtp_sendline (smtp_t, const char *line)
Function extern int smtp_send (smtp_t

2.7 Sendmail

     /* Prefix sendmail is reserved */
     #include <mailutils/sendmail.h>

Spawning Sendmail daemon to deliver mail. Not implemented.

2.8 NNTP

     /* Prefix nntp is reserved */
     #include <mailutils/nntp.h>

Network News Transfer Protocol. Not implemented.

2.8.1 Commands

2.8.1.1 Initialization

Function int nntp create (nnpt_t *) Function int nntp destroy (nnpt_t *) Function int nntp open (nnpt_t)

2.8.1.2 Article

Function int nntp article (nnpt_t)

2.8.1.3 Body

Function int nntp body (nntp_t)

Chapter 2: Concrete API 22

2.8.1.4 Group

Function int nntp group (nntp_t)

2.8.1.5 Head

Function int nntp head (nntp_t)

2.8.1.6 Help

Function int nntp help (nntp_t)

2.8.1.7 IHave

Function int nntp ihave (nntp_t)

2.8.1.8 Last

Function int nntp last (nntp_t)

2.8.1.9 List

Function int nntp list (nntp_t)

2.8.1.10 NewGroups

Function int nntp newgroups (nntp_t)

2.8.1.11 NewNews

Function int nntp newnews (nntp_t)

2.8.1.12 Next

Function int nntp next (nntp_t)

2.8.1.13 Post

Function int nntp post (nntp_t)

2.8.1.14 Quit

Function int nntp quit (nntp_t)

2.8.1.15 Slave

Function int nntp slave (nntp_t)

2.8.1.16 Stat

Function int nntp stat (nntp_t)

2.9 Parse822

     /* 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)

3 Framework

Wherever the mail is and whatever format it is stored in, the same operations to manipulate emails are common. To unified the C API, GNU mailutils offers a heteroclite set of objects that work in aggregation to do operations on emails. Each object do 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   |
                          +--------------+

For example writing a simple from command that will list 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/registrar.h>
#include <mailutils/list.h>
#include <mailutils/mailbox.h>
#define BUFFER_SIZE 64
int
main (int argc, const char **argv)
{

char from[BUFFER_SIZE];
char subject[BUFFER_SIZE];
char *mail;
mailbox_t mbox;
int status
size_t msgno, total = 0;
mail = (argc == 2) ? argv[1] : getenv ("MAIL");
/* Register the type of mailbox. IMAP4, POP3 and local format  */
{
    list_t registrar;
    registrar_get_list (&registrar);
    list_append (registrar, imap_record);
    list_append (registrar, path_record);
    list_append (registrar, pop_record);
}
status = mailbox_create (&mbox, mail);
if (status != 0)
  {
     fprintf (stderr, "mailbox_create: %s\n", strerror (status));
     exit (EXIT_FAILURE);
  }
status = mailbox_open (mbox, MU_STREAM_READ);
if (status != 0)
  {
     fprintf (stderr, "mailbox_open: %s\n", strerror (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",
                     strerror (status));
            exit (EXIT_FAILURE);
        }
      status = header_get_value (hdr, MU_HEADER_FROM, from,
                                 sizeof (from), NULL);

if (status != 0)
strcpy (from, "(NO FROM)");
status = header_get_value (hdr, MU_HEADER_SUBJECT, subject,
        sizeof (subject), NULL);
if (status != 0)
strcpy (subject, "(NO SUBJECT)");
printf ("%s\t%s\n", from, subject);
}
mailbox_close (mbox);
mailbox_destroy (&mbox);
return 0;
}

% MAIL=pop://alain@localhost ./sfrom
Passwd: xxxx
Jim Meyering <meyering@foo.org>      fetish(shellutils) beta
François Pinard <pinard@bar.org> recode new alpha
...

3.1 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)

3.2 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_ERROR_INVALID_PARAMETER

The url name supplied is invalid or not supported. pmbox is NULL.

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.

3.3 Mailer

/* Prefix mailer is reserved */
#include <mailutils/mailer.h>

The API is still shaky and undefined.

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, message_t)

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 *)

3.4 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)

Return non-zero value if message 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);

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

3.6 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_HDR_RETURN_PATH

Return-Path

MU_HDR_RECEIVED

Received

MU_HDR_DATE

Date

MU_HDR_FROM

From

MU_HDR_RESENT_FROM

Resent-From

MU_HDR_SUBJECT

Subject

MU_HDR_SENDER

Sender

MU_HDR_RESENT_SENDER

Resent-SENDER

MU_HDR_TO

To

MU_HDR_RESENT_TO

Resent-To

MU_HDR_CC

Cc

MU_HDR_RESENT_CC

Resent-Cc

MU_HDR_BCC

Bcc

MU_HDR_RESENT_BCC

Resent-Bcc

MU_HDR_REPLY_TO

Reply-To

MU_HDR_RESENT_REPLY_TO

Resent-Reply-To

MU_HDR_MESSAGE_ID

Message-ID

MU_HDR_RESENT_MESSAGE_ID

Resent-Message-ID

MU_HDR_IN_REPLY_TO

In-Reply-To

MU_HDR_ENCRYPTED

Encrypted

MU_HDR_PRECEDENCE

Precedence

MU_HDR_STATUS

Status

MU_HDR_CONTENT_LENGTH

Content-Length

MU_HDR_CONTENT_TYPE

Content-Type

MU_HDR_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)

3.7 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)

3.8 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)

3.9 Stream

   #include <mailutils/stream.h>

Function int stream create (stream_t *pstream, int flags, void *owner)

     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 is created.

     MU_STREAM_NONBLOCK

The stream is set non blocking.

     MU_STREAM_NO_CHECK

Stream is destroyed without checking for the owner.

Function void stream destroy (stream_t *pstream, void *owner)

Function int stream open (stream_t stream, const char *name, intport,

int flag)

Function int stream close (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 flush (stream_t 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.

Function int file stream create (stream_t *pstream) Function int mapfile stream create (stream_t *pstream)

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 tcp stream create (stream_t *pstream)

An example using tcp_stream_create to make a simple web client:

#include <stdlib.h>
#include <stdio.h>
#include <errno.h>
#include <string.h>
#include <unistd.h>
#include <sys/select.h>
#include <mailutils/io.h>
const char *wbuf = "GET / HTTP/1.0\r\n\r\n";
char rbuf[1024];
int
main(int argc, char **argv)
{
  int ret, off = 0, fd;
  stream_t stream;
  size_t nb;
  fd_set fds;
  argc = argc, argv = argv;
  ret = tcp_stream_create (&stream);
  if (ret != 0)
    {
       fprintf (stderr, "tcp_stream_create: %s\n",
                mailutils_error(ret));
       exit (EXIT_FAILURE);
    }
connect_again:
  ret = stream_open (stream, "www.netscape.com", 80,
                     MU_STREAM_NONBLOCK);
  if (ret != 0)
    {
       if (ret == MU_ERROR_EAGAIN)
         {
             ret = stream_get_fd(stream, &fd);
             if (ret != 0)
               {
                   fprintf (stderr, "stream_get_fd: %s\n",
                            mailutils_error(ret));
                   exit (EXIT_FAILURE);
               }
               FD_ZERO (&fds);
               FD_SET (fd, &fds);
               select (fd+1, NULL, &fds, NULL, NULL);
               goto connect_again;

    }
    fprintf (stderr, "stream_open: %s\n", mailutils_error (ret));
    exit (EXIT_FAILURE);
}
ret = stream_get_fd (stream, &fd);
if (ret != 0)
{
   fprintf(stderr, "stream_get_fd: %s\n", strerror(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;
     }
   fprintf (stderr, "stream_write: %s\n", strerror(ret));
   exit (EXIT_FAILURE)
}
if (nb != strlen (wbuf))
  {
     fprintf(stderr, "stream_write: %s\n", "nb != wbuf length");
     exit (EXIT_FAILURE);
  }
do
  {
read_again:
     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);
               goto read_again;
             }
           fprintf (stderr, "stream_read: %s\n", strerror(ret));
           exit(EXIT_FAILURE);

                   }
                   write (2, rbuf, nb);
              } while (nb);
              ret = stream_close (stream);
              if (ret!= 0)
                {
                   fprintf (stderr, "stream_close: %s\n", strerror(ret));
                   exit (EXIT_FAILURE);
                }
              stream_destroy (&stream, NULL);
              exit (EXIT_SUCCESS);
     }

3.10 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)

3.11 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;
}

3.12 Address

/* Prefix address is reserved */
#include <mailutils/address.h>

The Internet address format is defined in RFC 822. RFC 822 has been updated, and is now superceeded by RFC 2822, which makes some corrections and clarifications. References to RFC 822 here apply equally to RFC 2822.

The RFC 822 format is more flexible than many people realize, here is a quick summary of the syntax this parser implements, see RFC 822 for the details. "[]" pairs mean "optional", "/" means "one or the other", and double-quoted characters are literals.

addr-spec    = local-part "¨ domain
mailbox      = addr-spec ["(" display-name ")"] /
               [display-name] "<" [route] addr-spec ">"
mailbox-list = mailbox ["," mailbox-list]
group        = display-name ":" [mailbox-list] ";"
address      = mailbox / group / unix-mbox
address-list = address ["," address-list]

unix-mbox is a non-standard extension meant to deal with the common practice of using user names as addresses in mail utilities. It allows addresses such as "root" to be parsed correctly. These are NOT valid internet email addresses, they must be qualified before use.

Several address functions have a set of common arguments with consistent semantics, these are described here to avoid repetition.

Since an address-list may contain multiple addresses, they are accessed by a one-based index number, no. The index is one-based because pop, imap, and other message stores commonly use one-based counts to access messages and attributes of messages.

If len is greater than 0 it is the length of the buffer buf, and as much of the component as possible will be copied into the buffer. The buffer will be null terminated.

The size of a particular component may be queried by providing 0 for the len of the buffer, in which case the buffer is optional. In this case, if n is provided *n is assigned the length of the component string.

Data Type 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 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. 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.

3.13 Example

#include <stdio.h>
#include <errno.h>
#include <mailutils/address.h>
#define EPARSE ENOENT
static const char* err_name(int e)
{
    struct {
int e;
const char* s;
    } map[] = {
#define E(e) { e, #e },
E(ENOENT)
E(EINVAL)
E(ENOMEM)
#undef E
{ 0, NULL }
    };
    static char s[sizeof(int) * 8 + 3];
    int i;
    for(i = 0; map[i].s; i++) {
if(map[i].e == e)
    return map[i].s;
    }
    sprintf(s, "[%d]", e);
    return s;
}
static int parse(const char* str)
{
    size_t no = 0;
    size_t pcount = 0;
    int status;
    char buf[BUFSIZ];
    address_t  address = NULL;
    status = address_create(&address, str);
    address_get_count(address, &pcount);
    if(status) {
printf("%s=> error %s\n\n", str, err_name(status));

return 0;
    } else {
printf("%s=> pcount %d\n", str, pcount);
    }
    for(no = 1; no <= pcount; no++) {
size_t got = 0;
int isgroup;
address_is_group(address, no, &isgroup);
printf("%d ", 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;
}

3.14 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)

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

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

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

3.15.3 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

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

3.15.5 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* s)

Decodes an RFC 1738 % encoded string, returning the decoded string in allocated memory. If the string is not encoded, this degenerates to a strdup().

3.16 Example

     #include <mailutils/url.h>
     #include <stdio.h>
     #include <string.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)

{
  printf(stderr, "url_create %s ERROR: [%d] %s",
    str, rc, strerror(rc));
  exit (1);
}
if ((rc = url_parse (u)) != 0)
  {
    printf ("%s --> FAILED: [%d] %s\n",
      str, rc, strerror(rc));
    continue;
  }
printf ("%s --> SUCCESS\n", str);
url_get_scheme (u, buffer, len, NULL);
printf (" scheme <%s>\n", buffer);
url_get_user (u, buffer, len, NULL);
printf (" user <%s>\n", buffer);
url_get_passwd (u, buffer, len, NULL);
printf (" passwd <%s>\n", buffer);
url_get_auth (u, buffer, len, NULL);
printf (" auth <%s>\n", buffer);
url_get_host (u, buffer, len, NULL);
printf (" host <%s>\n", buffer);
url_get_port (u, &port);
printf (" port %ld\n", port);
url_get_path (u, buffer, len, NULL);
printf (" path <%s>\n", buffer);
url_get_query (u, buffer, len, NULL);
printf (" query <%s>\n", buffer);
url_destroy (&u);
}
return 0;
}

4 Programs

GNU Mailutils provides a set of programs for handling the email.

4.1 IMAP4 daemon

imap4d has two operation modes:

Inetd The server is started from ‘/etc/inetd.conf’ file:

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

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.

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.

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

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

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.

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

4.3 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 following command line options alter the behavior of the program:

‘-h’

‘--help’ Display short help message and exit.

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

‘-v’
‘--version’

Display version information and exit

4.4 mail — send and receive mail.

Mail is an enhanced version of standard ‘/bin/mail’ program. As well as its predecessor, it can be used either in sending mode or in reading mode. Mail enters sending mode when one or more email addresses were specified in this command line. In this mode the program waits until user finishes composing the message, then attempts to send it to the specified addresses and exits. See See Section 4.4.3 [Composing Mail], page 61, 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. See Section 4.4.4 [Reading Mail], page 64 for more detail.

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

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

‘-n’

‘--norc’ Do not read the system-wide mailrc file. See Section 4.4.6 [Mail Configuration Files], page 76.

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

4.4.2 How to specify message sets

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

The message list in its simplest form is one of:

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

* Selects all messages in the mailbox.

^Selects first non-deleted message.

$ Selects last non-deleted message.

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

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

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

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

‘:d’ Selects all deleted messages.

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

‘:o’ Selects all messages that have been seen.

‘:r’ Selects all messages that have been read.

‘:u’ Selects all messages that have not been read.

‘:t’ Selects all tagged messages (see Section 4.4.4.8 [Marking Messages], page 67).

‘: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:

4.4.3 Composing mail

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

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

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

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

Please note, that both commands allow you to edit the body of the message, and not its headers. To change message headers, see Section 4.4.3.4 [Modifying the Headers], page 62.

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

4.4.3.5 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 (see Section 4.4.4.5 [Controlling Header Display], page 65).

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

4.4.3.6 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

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

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

4.4.3.9 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 (see Section 4.4.4.5 [Controlling Header Display], page 65).

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

4.4.3.11 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 (see Section 4.4.4.14 [Replying], page 71) 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.

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

4.4.4 Reading mail

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

mail To read messages from your system mailbox.

mail --file

To read messages from your mailbox ($HOME/mbox).

mail --file=path to mailbox To read messages from the specified mailbox.

mail --user=user

To read messages from the system mailbox belonging to user.

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

Unless you have started mail with ‘--norc’ command line option, it will read the contents of the system-wide configuration file. Then it reads the contents of user configuration file, if any. See Section 4.4.6 [Mail Configuration Files], page 76 for detailed description of these 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.

4.4.4.1 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’.

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

4.4.4.3 Moving within a mailbox

‘next’

‘n’ Move to the next message.

‘previous’

‘prev’ Move to the previous message.

4.4.4.4 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

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

4.4.4.6 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

4.4.4.7 Displaying messages

‘print [msglist]’ ‘p [msglist]’

‘type [msglist]’ ‘t [msglist]’

Prints out the messages from msglist. If the variable crt is set and the number of lines in the message is greater than the number of lines on screen, the message is piped through pager command specified by environment variable PAGER. 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. See Section 4.4.4.5 [Controlling Header Display], page 65 for detailed description of ignored header lists.

‘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 shellcommand is empty but the string variable cmd is set, the value of this variable is used as a command name.

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

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

4.4.4.10 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.arda.org Fri Jun 30 18:11  14/358   The Save c
      U  15 gray@noldor.arda.org  Fri Jun 30 18:30  8/245    Re: The Sa
     & Save 14 15
     "smith" 22/603

i.e., 22 characters (603 lines) 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.

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

4.4.4.12 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

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

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

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

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

4.4.4.16 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 !.

4.4.5 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. Default: True in interactive mode, False otherwise. If True, any messages with number of lines greater than number of lines on terminal screen (as determined by screen variable) will be printed using program set in the environment variable ENVIRON.

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.

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 Section 4.4.6 [Mail Configuration Files], page 76.

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.

4.4.6 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’.

4.5 messages — Count the number of messages in a mailbox.

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

Number of messages in folder: number

where folder represents the folder name, number represents the number of messages. 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.

4.6 readmsg — Extract messages from a folder.

The program is currently in development

4.7 sieve

The program is currently in development

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

4.8.1 Specifying Scheme Program to Execute

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

‘-e’
‘--expression EXPR’

Execute scheme expression.

‘-f’
‘--file PROGFILE’

Read and execute program from PROGFILE.

You can specify both of them. In this case, the PROGFILE is executed first.

4.8.2 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 USER [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 its standard input.

4.8.3 Passing Options to Scheme

Sometimes it is necessary to pass some command line options to the scheme procedure. This can be done via ‘-g’ (‘--guile-command’) command line option. For example:

     guimb --guile-command -opt --guile-command 24 --file progfile

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

     progfile -opt 24

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

All arguments enclosed between ‘-{’ and ‘-}’ are not processed by ‘guimb’, they are instead passed to the Scheme program verbatim.

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

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

4.8.5 Scheme Procedures and Variables

4.8.5.1 Address Functions

mu-address-get-personal ADDRESS NUM

Return personal part of an email address.

mu-address-get-comments ADDRESS NUM

mu-address-get-email ADDRESS NUM

Return email part of an email address.

mu-address-get-domain ADDRESS NUM

Return domain part of an email address

mu-address-get-local ADDRESS NUM

Return local part of an email address.

mu-address-get-count ADDRESS

Return number of parts in email address.

4.8.5.2 Mailbox Functions

mu-mailbox-open URL MODE Opens a mailbox specified by URL.

mu-mailbox-close MBOX

Closes mailbox MBOX

mu-mailbox-get-url MBOX

Returns the URL of the mailbox.

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.

mu-mailbox-get-message MBOX MSGNO Retrieve from MBOX message # MSGNO.

mu-mailbox-messages-count MBOX

Returns number of messages in the mailbox.

mu-mailbox-expunge MBOX

Expunges deleted messages from the mailbox.

mu-mailbox-url MBOX

Returns the URL of the mailbox

mu-mailbox-append-message MBOX MESG

Appends the message to the mailbox

4.8.5.3 Message Functions

mu-message-copy MESG

Creates the copy of the given message.

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.

mu-message-get-size MESG

Returns the size of the given message.

mu-message-get-lines MESG

Returns number of lines in the given message.

mu-message-get-sender MESG

Returns the sender email address for the message MESG.

mu-message-get-header MESG HEADER Returns the header value of the HEADER in the MESG.

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

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

mu-message-get-flag MESG FLAG

Return value of the attribute FLAG.

mu-message-set-flag MESG FLAG VALUE Set the given attribute of the message. If optional VALUE is #f, the attribute is unset.

mu-message-get-user-flag MESG FLAG

Returns value of the user attribute FLAG.

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.

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

mu-message-get-body MESG

Returns the message body for the message MESG.

mu-message-send MESG MAILER Sends the message MESG. Optional MAILER overrides default mailer settings in mu-mailer.

4.8.5.4 MIME Functions

mu-mime-create FLAGS MESG

Creates a new MIME object.

mu-mime-multipart? MIME

Returns #t if MIME is a multipart object.

mu-mime-get-num-parts MIME

Returns number of parts in a MIME object.

mu-mime-get-part MIME PART

Returns part number PART from a MIME object.

mu-mime-add-part MIME MESG

Adds MESG to the MIME object.

mu-mime-get-message MIME

Converts MIME object to a message.

4.8.5.5 Log Functions

mu-openlog IDENT OPTION FACILITY Opens a connection to the system logger for Guile program.

mu-logger PRIO TEXT

Generates a log message to be distributed via syslogd.

mu-closelog Closes the channel to the system logger open by mu-openlog.

5 Reporting Bugs

Email bug reports to bug-mailutils@gnu.org. Be sure to include the word “mailutils” somewhere in the “Subject:” field.

6 Acknowledgement

In no particular order, Jakob Kaivo jkaivo@ndn.net, Jeff Bailey jbailey@gnu.org,

Sean Perry shaleh@debian.org, Thomas Fletcher thomasf@qnx.com, Dave Inglis dinglis@qnx.com,

Brian Edmond briane@qnx.com, Sam Roberts sroberts@uniserve.com, Sergey Poznyakoff

gray@Mirddin.farlep.net, François Pinard pinard@IRO.UMontreal.CA.

Concept Index 83

Concept Index

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

A

Acknowledgement. . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 address_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Authenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

B

Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

C

Concrete API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

E

Envelope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

F

Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

H

Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

I

IMAP4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 IMAP4 Append . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 IMAP4 Capability . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 IMAP4 Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 IMAP4 Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 IMAP4 Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 IMAP4 Create. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 IMAP4 Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 IMAP4 Examine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 IMAP4 Expunge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 IMAP4 Fetch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 IMAP4 Initialization . . . . . . . . . . . . . . . . . . . . . . . . . 12 IMAP4 List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 IMAP4 Lsub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 IMAP4 Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . 14 IMAP4 Rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 IMAP4 Search. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 IMAP4 Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 IMAP4 Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 IMAP4 Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 IMAP4 Subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 IMAP4 UID Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 IMAP4 UID Fetch . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 IMAP4 UID Search . . . . . . . . . . . . . . . . . . . . . . . . . . 14 IMAP4 UID Store . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 IMAP4 Unsubscribe . . . . . . . . . . . . . . . . . . . . . . . . . 14 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Iterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

L

Locker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

M

Mailbox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 mailbox_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Maildir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Mailer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Mbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Mbox channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Mbox Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Mh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

N

NNTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 NNTP Article . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 NNTP Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 NNTP Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 NNTP Head. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 NNTP Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 NNTP IHave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 NNTP Initialization. . . . . . . . . . . . . . . . . . . . . . . . . . 21 NNTP Last . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 NNTP List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 NNTP NewGroups. . . . . . . . . . . . . . . . . . . . . . . . . . . 22 NNTP NewNews . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 NNTP Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 NNTP Post . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 NNTP Quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Concept Index 84

NNTP Slave. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 NNTP Stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

P

Parse822 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 POP3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 POP3 Apop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 POP3 Capa . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 POP3 channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 POP3 Dele . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 POP3 Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 POP3 List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 POP3 Noop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 POP3 Pass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 POP3 Quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 POP3 Retr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 POP3 Rset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 POP3 Stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Pop3 Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 POP3 Top . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 POP3 Uidl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 POP3 User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 pop3 t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

R

Reporting Bugs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

S

Sendmail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 SMTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 SMTP Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 SMTP Expn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 SMTP Helo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 SMTP Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 SMTP Help functions . . . . . . . . . . . . . . . . . . . . . . . . 21 SMTP Initialization. . . . . . . . . . . . . . . . . . . . . . . . . . 19 SMTP Mail From. . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 SMTP Noop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 SMTP Quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 SMTP Recpt To . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 SMTP Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 SMTP Verify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 smtp t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Stream. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 struct pop3 list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

U

URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Index 85

Index

This is an alphabetical list of all mailutils functions.

A

ADDRESS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 address_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 address_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 address_get_comments. . . . . . . . . . . . . . . . . . . . . . . 47 address_get_count . . . . . . . . . . . . . . . . . . . . . . . . . . 48 address_get_domain . . . . . . . . . . . . . . . . . . . . . . . . . 48 address_get_email . . . . . . . . . . . . . . . . . . . . . . 46, 47

address_get_local_part . . . . . . . . . . . . . . . . . . . . 47

address_get_personal. . . . . . . . . . . . . . . . . . . . . . . 47 address_get_route . . . . . . . . . . . . . . . . . . . . . . . . . . 48 address_is_group . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 address_to_string . . . . . . . . . . . . . . . . . . . . . . . . . . 48 attribute_copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 attribute_create . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 attribute_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . 39 attribute_is_answered . . . . . . . . . . . . . . . . . . . . . 39 attribute_is_deleted. . . . . . . . . . . . . . . . . . . . . . . 39 attribute_is_draft . . . . . . . . . . . . . . . . . . . . . . . . . 39 attribute_is_equal . . . . . . . . . . . . . . . . . . . . . . . . . 40 attribute_is_flagged. . . . . . . . . . . . . . . . . . . . . . . 39 attribute_is_read . . . . . . . . . . . . . . . . . . . . . . . . . . 39 attribute_is_recent. . . . . . . . . . . . . . . . . . . . . . . . 39 attribute_is_seen . . . . . . . . . . . . . . . . . . . . . . . . . . 39

attribute_set_answered . . . . . . . . . . . . . . . . . . . . 39

attribute_set_deleted . . . . . . . . . . . . . . . . . . . . . 39 attribute_set_draft. . . . . . . . . . . . . . . . . . . . . . . . 39 attribute_set_flagged . . . . . . . . . . . . . . . . . . . . . 39 attribute_set_read . . . . . . . . . . . . . . . . . . . . . . . . . 39 attribute_set_recent. . . . . . . . . . . . . . . . . . . . . . . 39 attribute_set_seen . . . . . . . . . . . . . . . . . . . . . . . . . 39 attribute_to_string. . . . . . . . . . . . . . . . . . . . . . . . 40

attribute_unset_answered . . . . . . . . . . . . . . . . . . 40
attribute_unset_deleted . . . . . . . . . . . . . . . . . . . 40

attribute_unset_draft . . . . . . . . . . . . . . . . . . . . . 40

attribute_unset_flagged . . . . . . . . . . . . . . . . . . . 40

attribute_unset_read. . . . . . . . . . . . . . . . . . . . . . . 40

attribute_unset_recent . . . . . . . . . . . . . . . . . . . . 40

attribute_unset_seen. . . . . . . . . . . . . . . . . . . . . . . 40 auth_authenticate . . . . . . . . . . . . . . . . . . . . . . . . . . 45 auth_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 auth_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 auth_epilogue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 auth_prologue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

B

body_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 body_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 body_get_filename . . . . . . . . . . . . . . . . . . . . . . . . . . 39 body_get_stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 body_lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 body_set_filename . . . . . . . . . . . . . . . . . . . . . . . . . . 39 body_set_stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 body_size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

C

char* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Closes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

D

decoder_stream_create . . . . . . . . . . . . . . . . . . . . . 41

E

encoder_stream_create . . . . . . . . . . . . . . . . . . . . . 41 envelope_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 envelope_date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 envelope_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 envelope_get_message. . . . . . . . . . . . . . . . . . . . . . . 36 envelope_sender . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 envelope_set_date . . . . . . . . . . . . . . . . . . . . . . . . . . 36 envelope_set_sender. . . . . . . . . . . . . . . . . . . . . . . . 36

F

file_stream_create . . . . . . . . . . . . . . . . . . . . . . . . . 41 FLAGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 folder_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 folder_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 folder_delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 folder_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 folder_get_authority. . . . . . . . . . . . . . . . . . . . . . . 28 folder_get_debug . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 folder_get_observable . . . . . . . . . . . . . . . . . . . . . 28 folder_get_stream . . . . . . . . . . . . . . . . . . . . . . . . . . 28 folder_get_url . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 folder_list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 folder_lsub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 folder_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 folder_rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 folder_set_authority. . . . . . . . . . . . . . . . . . . . . . . 28 folder_set_debug . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 folder_set_stream . . . . . . . . . . . . . . . . . . . . . . . . . . 28 folder_set_url . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 folder_subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 folder_unsubscribe . . . . . . . . . . . . . . . . . . . . . . . . . 28

H

header_aget_value . . . . . . . . . . . . . . . . . . . . . . . . . . 38 header_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 header_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 header_get_stream . . . . . . . . . . . . . . . . . . . . . . . . . . 38 header_get_value . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 header_set_lines . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 header_set_size . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 header_set_value . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

I

IDENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 imap4_append . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 imap4_capability . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 imap4_check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 imap4_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 imap4_copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 imap4_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 imap4_create_mailbox. . . . . . . . . . . . . . . . . . . . . . . 12 imap4_delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 imap4_examine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 imap4_expunge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 imap4_fetch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 imap4_list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 imap4_lsub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 imap4_namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 imap4_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 imap4_rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 imap4_search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 imap4_select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 imap4_status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 imap4_store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 imap4_subscribe . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 imap4_uid_copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 imap4_uid_fetch . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 imap4_uid_search . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 imap4_uid_store . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 imap4_unsubscribe . . . . . . . . . . . . . . . . . . . . . . . . . . 14 imap4d_set_timeout . . . . . . . . . . . . . . . . . . . . . . . . . 12 int . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 iterator_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 iterator_current . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 iterator_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 iterator_first . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 iterator_is_done . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 iterator_next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

L

locker_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 locker_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 locker_lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 locker_touchlock . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 locker_unlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

M

                                                mailbox_append_message . . . . . . . . . . . . . . . . . . . . 29

mailbox_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 mailbox_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

                                                mailbox_create_default . . . . . . . . . . . . . . . . . . . . 29

mailbox_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 mailbox_expunge . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 mailbox_get_debug . . . . . . . . . . . . . . . . . . . . . . . . . . 30 mailbox_get_folder . . . . . . . . . . . . . . . . . . . . . . . . . 30 mailbox_get_locker . . . . . . . . . . . . . . . . . . . . . . . . . 30 mailbox_get_message. . . . . . . . . . . . . . . . . . . . . . . . 30

                                                mailbox_get_observable . . . . . . . . . . . . . . . . . . . . 30

mailbox_get_property. . . . . . . . . . . . . . . . . . . . . . . 31 mailbox_get_size . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 mailbox_get_stream . . . . . . . . . . . . . . . . . . . . . . . . . 31 mailbox_get_ticket . . . . . . . . . . . . . . . . . . . . . . . . . 31 mailbox_get_url . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 mailbox_is_modified. . . . . . . . . . . . . . . . . . . . . . . . 31

                                                mailbox_message_unseen . . . . . . . . . . . . . . . . . . . . 31
                                                mailbox_messages_count . . . . . . . . . . . . . . . . . . . . 32
                                                mailbox_messages_recent . . . . . . . . . . . . . . . . . . . 32

mailbox_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 mailbox_scan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 mailbox_set_locker . . . . . . . . . . . . . . . . . . . . . . . . . 32 mailbox_set_stream . . . . . . . . . . . . . . . . . . . . . . . . . 33 mailbox_set_ticket . . . . . . . . . . . . . . . . . . . . . . . . . 33 mailbox_uidnext . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 mailbox_uidvalidity. . . . . . . . . . . . . . . . . . . . . . . . 33 mailer_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 mailer_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 mailer_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 mailer_get_debug . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 mailer_get_observable . . . . . . . . . . . . . . . . . . . . . 34 mailer_get_property. . . . . . . . . . . . . . . . . . . . . . . . 33 mailer_get_stream . . . . . . . . . . . . . . . . . . . . . . . . . . 33 mailer_get_url . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 mailer_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 mailer_send_message. . . . . . . . . . . . . . . . . . . . . . . . 33 mailer_set_debug . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 mailer_set_stream . . . . . . . . . . . . . . . . . . . . . . . . . . 34 mapfile_stream_create . . . . . . . . . . . . . . . . . . . . . 41 MBOX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79, 80 mbox_append . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 mbox_append_hb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 mbox_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 mbox_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 mbox_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 mbox_expunge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 mbox_get_attribute . . . . . . . . . . . . . . . . . . . . . . . . . 16 mbox_get_bstream . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 mbox_get_carrier . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 mbox_get_hstream . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 mbox_get_separator . . . . . . . . . . . . . . . . . . . . . . . . . 16 mbox_get_size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 mbox_mak_deleted . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 mbox_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 mbox_save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 mbox_scan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 mbox_set_blines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 mbox_set_bsize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 mbox_set_bstream . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 mbox_set_carrier . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 mbox_set_hlines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 mbox_set_hsize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 mbox_set_hstream . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 mbox_set_newmsg_cb . . . . . . . . . . . . . . . . . . . . . . . . . 19 mbox_set_progress_cb. . . . . . . . . . . . . . . . . . . . . . . 19 mbox_set_separator . . . . . . . . . . . . . . . . . . . . . . . . . 17 mbox_uidnext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 mbox_uidvalidity . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 mbox_unmak_deleted . . . . . . . . . . . . . . . . . . . . . . . . . 18 MESG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80, 81 message_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

                                                message_create_attachment . . . . . . . . . . . . . . . . . 35

message_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 message_encapsulate. . . . . . . . . . . . . . . . . . . . . . . . 35 message_get_attribute . . . . . . . . . . . . . . . . . . . . . 35 message_get_body . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 message_get_envelope. . . . . . . . . . . . . . . . . . . . . . . 35 message_get_header . . . . . . . . . . . . . . . . . . . . . . . . . 34 message_get_num_parts . . . . . . . . . . . . . . . . . . . . . 35

                                                message_get_observable . . . . . . . . . . . . . . . . . . . . 35

message_get_part . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 message_get_stream . . . . . . . . . . . . . . . . . . . . . . . . . 35 message_get_uid . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 message_get_uidl . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 message_is_multipart. . . . . . . . . . . . . . . . . . . . . . . 34

                                                message_save_attachment . . . . . . . . . . . . . . . . . . . 35

message_set_attribute . . . . . . . . . . . . . . . . . . . . . 35 message_set_body . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 message_set_envelope. . . . . . . . . . . . . . . . . . . . . . . 35 message_set_header . . . . . . . . . . . . . . . . . . . . . . . . . 34 message_set_stream . . . . . . . . . . . . . . . . . . . . . . . . . 35 message_set_uidl . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 message_unencapsulate . . . . . . . . . . . . . . . . . . . . . 35 MIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81, 82 MU_STREAM_APPEND . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 MU_STREAM_CREAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 MU_STREAM_NO_CHECK . . . . . . . . . . . . . . . . . . . . . . . . . 40 MU_STREAM_NONBLOCK . . . . . . . . . . . . . . . . . . . . . . . . . 40 MU_STREAM_RDWR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 MU_STREAM_READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 MU_STREAM_WRITE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

N

nntp_article . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 nntp_body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 nntp_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 nntp_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 nntp_group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 nntp_head . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 nntp_help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 nntp_ihave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 nntp_last . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 nntp_list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 nntp_newgroups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 nntp_newnews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 nntp_next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 nntp_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 nntp_post . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 nntp_quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 nntp_slave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 nntp_stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

P

parse822_addr_spec . . . . . . . . . . . . . . . . . . . . . . . . . 23 parse822_address . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 parse822_address_list . . . . . . . . . . . . . . . . . . . . . 23 parse822_domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

parse822_domain_literal . . . . . . . . . . . . . . . . . . . 24

parse822_domain_ref. . . . . . . . . . . . . . . . . . . . . . . . 24 parse822_field_body. . . . . . . . . . . . . . . . . . . . . . . . 24 parse822_field_name. . . . . . . . . . . . . . . . . . . . . . . . 24 parse822_group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 parse822_local_part. . . . . . . . . . . . . . . . . . . . . . . . 23 parse822_mail_box . . . . . . . . . . . . . . . . . . . . . . . . . . 23

parse822_quote_local_part . . . . . . . . . . . . . . . . . 24

parse822_quote_string . . . . . . . . . . . . . . . . . . . . . 24 parse822_route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 parse822_route_addr. . . . . . . . . . . . . . . . . . . . . . . . 23 parse822_sub_domain. . . . . . . . . . . . . . . . . . . . . . . . 23 parse822_unix_mbox . . . . . . . . . . . . . . . . . . . . . . . . . 23 pop3_apop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 pop3_capa. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 pop3_connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 pop3_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 pop3_dele. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 pop3_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 pop3_get_carrier . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 pop3_get_timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 pop3_list. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 pop3_list_all . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 pop3_list_current . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 pop3_noop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 pop3_pass. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 pop3_quit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 pop3_response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 pop3_retr. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 pop3_rset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 pop3_send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 pop3_sendline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 pop3_set_carrier . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 pop3_set_timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 pop3_stat. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 pop3_top. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 pop3_uidl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 pop3_uidl_all . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 pop3_uidl_current . . . . . . . . . . . . . . . . . . . . . . . . . . 10 pop3_user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 pop3_writeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 PRIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

S

smtp_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 smtp_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 smtp_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 smtp_ehlo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 smtp_expn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 smtp_helo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 smtp_help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 smtp_mail_from . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 smtp_noop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 smtp_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 smtp_quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 smtp_rcpt_to . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 smtp_reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 smtp_verify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 stream_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 stream_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 stream_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 stream_flush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 stream_get_fd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 stream_get_flags . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 stream_get_state . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 stream_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 stream_read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 stream_readline . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 stream_size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 stream_truncate . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 stream_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 string_to_attribute. . . . . . . . . . . . . . . . . . . . . . . . 40

T

tcp_stream_create . . . . . . . . . . . . . . . . . . . . . . . . . . 41

U

URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 url_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 url_decode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 url_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 url_get_host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 url_get_passwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 url_get_path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 url_get_port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 url_get_query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 url_get_scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 url_get_user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 url_parse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Table of Contents

1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 Concrete API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2.1 POP3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2.1.1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2.1.1.1 Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1.1.2 Carrier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1.1.3 Apop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1.1.4 Capa . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1.1.5 Dele . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.1.1.6 List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.1.1.7 Noop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.1.1.8 Pass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.1.1.9 Quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.1.1.10 Retr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.1.1.11 Rset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.1.1.12 Stat. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.1.1.13 Top . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.1.1.14 Uidl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.1.1.15 User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.1.1.16 Help functions . . . . . . . . . . . . . . . . . . . . . . . 11 2.1.1.17 Timeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2.2 IMAP4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2.2.1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.2.1.1 Initialization. . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.2.1.2 Append . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.2.1.3 Capability . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.2.1.4 Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.2.1.5 Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.2.1.6 Close. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.2.1.7 Copy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.2.1.8 UID Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.2.1.9 Delete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.2.1.10 Fetch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.2.1.11 UID Fetch . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.2.1.12 Examine . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.2.1.13 Expunge . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.2.1.14 List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.2.1.15 Lsub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.2.1.16 Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.2.1.17 Rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.2.1.18 Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.2.1.19 UID Search. . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.2.1.20 Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.2.1.21 Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.2.1.22 Store. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.2.1.23 UID Store . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.2.1.24 Subscribe. . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.2.1.25 Unsubscribe . . . . . . . . . . . . . . . . . . . . . . . . . 14

2.3 Mbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.3.0.1 Initialization. . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.3.0.2 Carrier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

2.4 Mh. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 2.5 Maildir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 2.6 SMTP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

2.6.1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 2.6.1.1 Initialization. . . . . . . . . . . . . . . . . . . . . . . . . . 19 2.6.1.2 Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 2.6.1.3 Helo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 2.6.1.4 Expn. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 2.6.1.5 Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 2.6.1.6 Mail From . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 2.6.1.7 Noop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 2.6.1.8 Quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 2.6.1.9 Recpt To . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 2.6.1.10 Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 2.6.1.11 Verify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 2.6.1.12 Help functions . . . . . . . . . . . . . . . . . . . . . . . 21

2.7 Sendmail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 2.8 NNTP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

2.8.1 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 2.8.1.1 Initialization. . . . . . . . . . . . . . . . . . . . . . . . . . 21 2.8.1.2 Article . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 2.8.1.3 Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 2.8.1.4 Group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.8.1.5 Head . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.8.1.6 Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.8.1.7 IHave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.8.1.8 Last . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.8.1.9 List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.8.1.10 NewGroups. . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.8.1.11 NewNews . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.8.1.12 Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.8.1.13 Post . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.8.1.14 Quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.8.1.15 Slave. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 2.8.1.16 Stat. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

2.9 Parse822 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

3 Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

3.1 Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 3.2 Mailbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 3.3 Mailer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 3.4 Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 3.5 Envelope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 3.6 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 3.7 Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 3.8 Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 3.9 Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 3.10 Iterator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 3.11 Authenticator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 3.12 Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 3.13 Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 3.14 Locker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 3.15 URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

3.15.1 POP3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 3.15.2 IMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 3.15.3 File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 3.15.4 Mailto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 3.15.5 URL functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

3.16 Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

4 Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

4.1 IMAP4 daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 4.2 POP3 daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 4.3 frm — List headers from a mailbox. . . . . . . . . . . . . . . . . . . . . . 57 4.4 mail — send and receive mail.. . . . . . . . . . . . . . . . . . . . . . . . . . . 58

4.4.1 Command line options . . . . . . . . . . . . . . . . . . . . . . . . . 58 4.4.2 How to specify message sets . . . . . . . . . . . . . . . . . . . . 60 4.4.3 Composing mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

4.4.3.1 Quitting Compose Mode. . . . . . . . . . . . . . . 61 4.4.3.2 Getting Help on Compose Escapes: ~? . . 62 4.4.3.3 Editing the Message: ~e and ~v. . . . . . . . 62 4.4.3.4 Modifying the Headers: ~h, ~t, ~c, ~b, ~s

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

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

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 4.4.3.7 Printing And Saving the Message . . . . . . 63 4.4.3.8 Signing the Message: ~a and ~A. . . . . . . . 63 4.4.3.9 Printing Another Message: ~f and ~F … 63 4.4.3.10 Inserting Value of a Mail Variable: ~i . . 63 4.4.3.11 Executing Other Mail Commands: ~: and

~-. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 4.4.3.12 Executing Shell Commands: ~! and ~|

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 4.4.4 Reading mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

4.4.4.1 Quitting the program. . . . . . . . . . . . . . . . . . 64 4.4.4.2 Obtaining online help . . . . . . . . . . . . . . . . . 64 4.4.4.3 Moving within a mailbox . . . . . . . . . . . . . . 65 4.4.4.4 Changing mailbox/directory . . . . . . . . . . . 65 4.4.4.5 Controlling header display . . . . . . . . . . . . . 65 4.4.4.6 Displaying information . . . . . . . . . . . . . . . . 66 4.4.4.7 Displaying messages . . . . . . . . . . . . . . . . . . . 66 4.4.4.8 Marking messages . . . . . . . . . . . . . . . . . . . . . 67 4.4.4.9 Disposing of messages . . . . . . . . . . . . . . . . . 68 4.4.4.10 Saving messages . . . . . . . . . . . . . . . . . . . . . 68 4.4.4.11 Editing messages. . . . . . . . . . . . . . . . . . . . . 69 4.4.4.12 Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 4.4.4.13 Aliasing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 4.4.4.14 Replying . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 4.4.4.15 Incorporating new mail . . . . . . . . . . . . . . . 72 4.4.4.16 Shell escapes . . . . . . . . . . . . . . . . . . . . . . . . 72

4.4.5 How to alter the behavior of mail . . . . . . . . . . . . . . . 72 4.4.6 Personal and system-wide configuration files . . . . . 76

4.5 messages — Count the number of messages in a mailbox.. . 76 4.6 readmsg — Extract messages from a folder. . . . . . . . . . . . . . . 77 4.7 sieve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 4.8 guimb — A mailbox scanning and processing language. … 77

4.8.1 Specifying Scheme Program to Execute. . . . . . . . . . 77 4.8.2 Specifying Mailboxes to Operate Upon . . . . . . . . . . 77 4.8.3 Passing Options to Scheme . . . . . . . . . . . . . . . . . . . . . 78 4.8.4 Guimb Invocation Summary . . . . . . . . . . . . . . . . . . . . 78 4.8.5 Scheme Procedures and Variables . . . . . . . . . . . . . . . 79

4.8.5.1 Address Functions . . . . . . . . . . . . . . . . . . . . 79 4.8.5.2 Mailbox Functions . . . . . . . . . . . . . . . . . . . . 79 4.8.5.3 Message Functions . . . . . . . . . . . . . . . . . . . . 80 4.8.5.4 MIME Functions . . . . . . . . . . . . . . . . . . . . . . 81 4.8.5.5 Log Functions . . . . . . . . . . . . . . . . . . . . . . . . 82

5 Reporting Bugs. . . . . . . . . . . . . . . . . . . . . . . . . . . 82

6 Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . . 82

Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85