GNU MAILUTILS offers a general purpose library whose aim is to provide a rich set of functions for accessing different mailbox formats and mailers.
For more information on,
/* 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.
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.
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.
Allocate and initialize a pop3 handle.
MU_ERROR_NO_MEMORY
MU_ERROR_INVALID_PARAMETER
When a POP3 session is finished, the structure must be free ()'ed to
reclaim memory.
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
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
Return the pop3_t carrier. If none was set, a new tcp stream will be created.
MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY
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
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");
}
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
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
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
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
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
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
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
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
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
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
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
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
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
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
Sends the User command.
MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED
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
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
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
The last response from the last command is save and can be examine after a failure or success.
MU_ERROR_INVALID_PARAMETER
MU_ERROR_IO
MU_ERROR_TIMEOUT
MU_ERROR_TRY_AGAIN
MU_ERROR_OPERATION_DENIED
Set the timeout time for I/O on the carrier. The default is 10 minutes. The timeout is given in milliseconds.
Get the timeout time for I/O on the carrier. The timeout is given in milliseconds.
/* Prefix imap4_ is reserved */#include <mailutils/imap4.h>
Internet Message Access Protocol - Version (4rev1). Not implemented.
/* 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 "
envelope-sender
date
asctime ()
moreinfo
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'.
Allocate and initialize a mbox handle.
MU_ERROR_NO_MEMORY
MU_ERROR_INVALID_PARAMETER
When a POP3 session is finished, the structure must be free ()'ed to
reclaim memory.
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
Return the mbox_t carrier. If none was set, a new file stream will be created.
MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY
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
Close the carrier stream and resources particular to the mailbox.
MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY
Return the uidnext, if the mbox_t was not scan mbox_scan ()
is called first.
MU_ERROR_INVALID_PARAMETER
same as mbox_scan ()
Return the uidvalidity, if the mbox_t was not scan mbox_scan ()
is called first.
MU_ERROR_INVALID_PARAMETER
same as mbox_scan ()
Return an attribute to indicate the status of message number msgno.
MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY
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
The variable sep should contain a valid "From " separator that will be use when the expunging.
MU_ERROR_INVALID_PARAMETER
MU_ERROR_NO_MEMORY
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
Use stream when expunging for message msgno.
MU_ERROR_INVALID_PARAMETER
Return the size of message msgno.
MU_ERROR_INVALID_PARAMETER
Return the number of lines of message msgno.
MU_ERROR_INVALID_PARAMETER
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
Use stream when expunging for message msgno.
MU_ERROR_INVALID_PARAMETER
Return the size of message msgno.
MU_ERROR_INVALID_PARAMETER
Return the number of lines of message msgno.
MU_ERROR_INVALID_PARAMETER
Return the size of mailbox.
MU_ERROR_INVALID_PARAMETER
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
Mark msgno for deletion.
MU_ERROR_INVALID_PARAMETER
Unmark msgno if it was marked for deletion.
MU_ERROR_INVALID_PARAMETER
Save the changes to the mailbox and in the process remove all messages marked for deletion.
MU_ERROR_INVALID_PARAMETER
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
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
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
Set the callback function for progress. The variable arg will be pass back in the callback as the second argument.
MU_ERROR_INVALID_PARAMETER
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
/* Prefix mh_ is reserved */#include <mailutils/mh.h>
Mail Handler mailbox format. Not implemented.
/* Prefix maildir_ is reserved */#include <mailutils/maildir.h>
QMail mailbox format. Not implemented.
/* Prefix smtp_ is reserved */#include <mailutils/smtp.h>
Simple Mail Transfer Protocol. Not implemented.
/* Prefix sendmail_ is reserved */#include <mailutils/sendmail.h>
Spawning Sendmail daemon to deliver mail. Not implemented.
/* Prefix nntp_ is reserved */#include <mailutils/nntp.h>
Network News Transfer Protocol. Not implemented.
/* Prefix parse822_ is reserved */#include <mailutils/parse822.h>
Internet Message Format, see Address node for the discussion.
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 (®istrar);
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@,{c}ois Pinard <pinard@bar.org> recode new alpha
...
/* 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) |
\-----------------/
/* Prefix mailbox_ is reserved */#include <mailutils/mailbox.h>
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) |
\-----------------/
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
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
ENOMEM
mailbox_create () based on the environment
variable $MAIL or the string formed by
_PATH_MAILDIR/user" or $LOGNAME if user is null,
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
ENOMEM
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
ENOMEM
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
ENOMEM
0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
ENOMEM
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
stream_create for flag's description.
The return value is 0 on success and a code number on error conditions:
EAGAIN
EINPROGRESS
EBUSY
MU_ERROR_INVALID_PARAMETER
ENOMEM
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
ENOMEM
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
auth_t object on creation.
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
The return value is 0 on success and a code number on error conditions:
MU_ERROR_INVALID_PARAMETER
/* Prefix mailer_ is reserved */#include <mailutils/mailer.h>
The API is still shaky and undefined.
#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 |
+-----------------------+
/* Prefix envelope_ is reserved */#include <mailutils/envelope.h>
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.
Get the address that this message was reportedly received from. This would be the "mail from" argument if the message was delivered or received via SMTP, for example.
Primarily for internal use. The implementation of 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.
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.
/* 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.
Some basic macros are already provided for rfc822.
MU_HDR_RETURN_PATH
MU_HDR_RECEIVED
MU_HDR_DATE
MU_HDR_FROM
MU_HDR_RESENT_FROM
MU_HDR_SUBJECT
MU_HDR_SENDER
MU_HDR_RESENT_SENDER
MU_HDR_TO
MU_HDR_RESENT_TO
MU_HDR_CC
MU_HDR_RESENT_CC
MU_HDR_BCC
MU_HDR_RESENT_BCC
MU_HDR_REPLY_TO
MU_HDR_RESENT_REPLY_TO
MU_HDR_MESSAGE_ID
MU_HDR_RESENT_MESSAGE_ID
MU_HDR_IN_REPLY_TO
MU_HDR_ENCRYPTED
MU_HDR_PRECEDENCE
MU_HDR_STATUS
MU_HDR_CONTENT_LENGTH
MU_HDR_CONTENT_TYPE
MU_HDR_MIME_VERSION
/* Prefix body_ is reserved */#include <mailutils/body.h>
/* Prefix attribute_ is reserved */#include <mailutils/attribute.h>
#include <mailutils/stream.h>
MU_STREAM_READ
MU_STREAM_WRITE
MU_STREAM_RDWR
MU_STREAM_APPEND
MU_STREAM_CREAT
MU_STREAM_NONBLOCK
MU_STREAM_NO_CHECK
MU_STREAM_STATE_OPEN
stream_open.
MU_STREAM_STATE_READ
stream_read or stream_readline.
MU_STREAM_STATE_WRITE
stream_write.
MU_STREAM_STATE_CLOSE
stream_close.
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);
}
/* Prefix iterator_ is reserved */#include <mailutils/iterator.h>
/* 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.
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;
}
/* 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.
@macro ADDRESSENOMEM
null.
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.
0 on success and a code number on error conditions:
0 on success and a code number on error conditions:
0 on success and a code number on error conditions:
0 on success and a code number on error conditions:
0
length for a unix-mbox.
The return value is 0 on success and a code number on error conditions:
0 on success and a code number on error conditions:
0
length for a unix-mbox.
The return value is 0 on success and a code number on error conditions:
0 on success and a code number on error conditions:
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:
0 on success and a code number on error conditions:
null, the count is 0. If count is
not null, the count will be written to *count.
The return value is 0.
#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;
}
/* Prefix locker_ is reserved */#include <mailutils/locker.h>
MU_LOCKER_RDLOCK
MU_LOCKER_WRLOCK
MU_LOCKER_PID
MU_LOCKER_FCNTL
MU_LOCKER_TIME
A mailbox or a mailer can be described in a URL, the string will contain the
necessary information to initialize mailbox_t, or mailer_t
properly.
The POP URL scheme contains a POP server, optional port number and the authentication mechanism. The general form is
pop://[<user>[;AUTH=<auth>]@]<host>[:<port>]orpop://[<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.orgpop://asterix;AUTH=*@france.compop://falbala;AUTH=+APOP@france.compop://obelix;AUTH=+APOP@village.gaulois.org:2000pop://obelix:menhir@village.gaulois.org:2000
For more complete information see rfc2368.
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>]orimap://[<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.orgimap://asterix;AUTH=*@imap.france.comimap://asterix:potion@imap.france.com
For more complete information see rfc2192.
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://pathfile://var/mail/userfile://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://pathmh://path
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=subscribemailto://bug-mailutils@gnu.org?Subject=hello&body=subscribe
For more complete information see rfc2368.
Helper functions are provided to retrieve and set the URL fields.
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.
#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;
}
GNU Mailutils provides a set of programs for handling the email.
imap4d has two operation modes:
imap4 stream tcp nowait root /usr/local/sbin/imap4d imap4dThis is the default operation mode.
The `pop3d' daemon implements the Post Office Protocol server.
pop3d has two operation modes:
pop3 stream tcp nowait root /usr/local/sbin/pop3d pop3dThis is the default operation mode.
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:
From Subject pair.
To header to the output. The output field
order is then: To From Subject.
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 Composing mail, for a detailed description of this behavior.
If the command line contained no email addresses, mail switches
to reading mode. In this mode it allows to read and manipulate the
contents of a mailbox. The URL of the mailbox to operate upon is
taken from the argument of `--file' command line option. If it
is not specified, the user's system mailbox is assumed. See section Reading mail for more detail.
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:
print * quit
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).
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:
In its complex form, the message list is a comma or whitespace-separated list of message specifiers. A message specifier is one of
[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:'.
:/string/It selects all messages whose body matches the string. The matching rules are the same as described under "Header match".
A message specifier can be followed by message part specifier, enclosed in a pair of brackets. A message part specifier controls which part of a message should be operated upon. It is meaningful only for multipart messages. A message part specifier is a comma or whitespace - separated list of part numbers or ranges. Each part number can in turn be message part specifier, thus allowing for operating upon multiply-encoded messages.
The following are the examples of valid message lists:
You can compose the message by simply typing the contents of it, line
by line. But usually this is not enough, you would need to edit
your text, to quote some messages, etc. `Mail' provides these
capabilities through compose escapes. The compose escapes
are single-character commands, preceded by special escape character,
which defaults to `~'. The combination escape character + command
is recognized as a compose escape only if it occurs at the beginning of
a line. If the escape character must appear at the beginning of a
line, enter it twice.
The actual escape character may be changed by setting the value of
escape mail variable (see section How to alter the behavior of mail).
There are several commands allowing you to quit the compose mode.
Typing the end-of-file character (`C-D') on a line alone finishes
compose mode and sends the message to its destination. The `C-D'
character looses its special meaning if ignoreeof mail variable
is set.
If mail variable dot is set, typing dot (`.') on a line
alone achieves the same effect as `C-D' above.
Finally, using `~.' escape always quits compose mode and sends out the composed message.
To abort composing of a message without sending it, type interrupt
character (by default, `C-C') twice. This behavior is disabled
when mail variable ignore is set. In this case, you can use
`~x' escape to achieve the same effect.
The `~?' escape prints on screen a brief summary of the available compose escapes. Please note, that `~h' escape prompts for changing the header values, and does not give help.
If you are not satisfied with the message as it is, you can edit it
using a text editor specified either by EDITOR or by
VISUAL environment variables. The `~e' uses the former,
and `~v' uses the latter.
Please note, that both commands allow you to edit the body of the message, and not its headers. To change message headers, see section 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.
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 Controlling header display).
In both cases, the contents of indentprefix mail variable is
prepended to each line enclosed.
To append the contents of file filename to the message, type
~r filename
or
~< filename
The `~d' escape is a shorthand for
~r dead.letter
The `~p' escape types the contents of the message entered so far, including headers, on your terminal. You can save the message to an arbitrary file using `~w' escape. It takes the filename as its argument.
To save you the effort of typing your signature at the end of each
message, you can use `~a' or `~A' escapes. If your signature
occupies one line only, save it to the variable sign and use
`~a' escape to insert it. Otherwise, if it is longer than one
line, save it to a file, store the name of this file in the
variable Sign, and use `~A' escape to insert it into
the message.
Sometimes it is necessary to view the contents of another message, while composing. These two escapes allow it. Both take the message list as their argument. If they are used without argument, the contents of the current message is printed. The difference between `~f' and `~F' is that the former uses ignored and retained lists to select headers to be displayed, whereas the latter prints all headers (see section Controlling header display).
The `~i' escape enters the value of the named mail variable into the body of the message being composed.
You can execute a mail command from within compose mode using `~:' or `~-' escapes. For example, typing
~: from :t
will display the from lines of all tagged messages. Note, that executing
mail-sending commands (see section Replying) from within the compose mode is
not allowed. An attempt to execute such a command will result in
diagnostic message "Command not allowed in an escape sequence" being
displayed. Also, when starting compose mode immediately from the shell
(e.g. running `mail address@domain'), most mail commands are
meaningless, since there is no mailbox to operate upon. In this case,
the only commands that can reasonably be used are: alias,
unalias, alternate, set, and unset.
The `~!' escape executes specified command and returns you to `mail' compose mode without altering your message. When used without arguments, it starts your login shell. The `~|' escape pipes the message composed so far through the given shell command and replaces the message with the output the command produced. If the command produced no output, `mail' assumes that something went wrong and retains the old contents of your message.
To read messages from a given mailbox, use one of the following ways of invoking `mail':
mail
mail --file
mail --file=path_to_mailbox
mail --user=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 Personal and system-wide configuration files 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.
Following commands quit the program:
delete are removed.
The program exits to the Shell, unless saving the mailbox fails, in
which case user can escape with the exit command.
Typing EOF (`C-D') alone is equivalent to `quit'.
Following commands can be used during the session to request online help:
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
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.
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 +2will skip two pages of messages before displaying the header summary.
folder variable.
& summary "/var/spool/mail/gray": 23 messages 22 unread
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.
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 ...
toplines and
defaults to five.
cmd is set,
the value of this variable is used as a command name.
& untag :t
delete command.
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.
delete command, unless the variable
keepsave is set.
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/603i.e., 22 characters (603 lines) have been appended to the file "smith". If the file does not exist, it is created.
save, except that only message body (without the
header) is saved.
Save, except that only message body (without the
header) is saved.
quit command. This is the default action for
all read messages, unless you have variable hold set.
save, except that saved messages are not marked for
deletion.
Save, except that saved messages are not marked for
deletion.
These command allow to edit messages in a mailbox. Please note,
that modified messages currently do not replace original ones. i.e.
you have to save them explicitly using your editor's save
command if you do not want the effects of your editing to be lost.
EDITOR environment variable.
VISUAL environment variable.
The `#' character introduces an end-of-line comment. All characters until and including the end of line are ignored.
The `echo' (`ec') command prints its arguments to stdout.
The command `source filename' reads commands from the named file. Its minimal abbreviation is `so'.
The mail variables may be set using `set' (`se') command. The command takes a list of assignments. The syntax of an assignment is
True value.
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
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:
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
reply, except that the composed message is sent only to
originators of the specified messages.
followup, but reply message is sent only to
originators of messages in msglist.
The incorporate (inc) command incorporates newly arrived
messages to the displayed list of messages. This is done automatically
before returning to `mail' command prompt if the variable
autoinc is set.
To run arbitrary shell command from `mail' command prompt, use
shell (sh) command. If no arguments are specified, the
command starts the user login shell. Otherwise, it uses its first
argument as a file name to execute and all subsequent arguments are
passed as positional parameters to this command. The shell
command can also be spelled as !.
Following variables control the behavior of GNU `mail':
Sign
~A
escape.
appenddeadletter
True, the contents of canceled letter is
appended to the user's `dead.letter' file. Otherwise it overwrites
its contents.
askbcc
True the user will be prompted to enter Bcc
field before composing the message.
askcc
True the user will be prompted to enter Cc
field before composing the message.
asksub
True the user will be prompted to enter Subject
field before composing the message.
autoinc
autoprint
cmd
pipe.
columns
COLUMNS is used.
This variable contains the number of columns on terminal screen.
crt
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
True, causes `mail' to interpret a period alone on a line as the
terminator of a message you are sending.
escape
folder
header
headers command automatically after entering
interactive mode.
hold
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
True, `mail' will ignore keyboard interrupts
when composing messages. Otherwise an interrupt will be taken as a
signal to abort composing.
ignoreeof
indentprefix
~m tilde escape for indenting quoted messages.
keepsave
metoo
mode
noregex
True enables use of regular expressions in
`/.../' message specifications.
outfolder
save,
write, etc. commands will be stored. When unset, current
directory is assumed.
page
True, the pipe command will emit a linefeed
character after printing each message.
prompt
quiet
quit
rc
record
save
appenddeadletter.
screen
LINES is used.
This variable contains the number of lines on terminal screen.
sendmail
sign
~a escape. Use
Sign variable, if your signature occupies more than one line.
subject
asksub is
off.
toplines
top and Top commands.
verbose
Upon startup, `mail' reads the contents of the two command files: the system-wide configuration file, and the user's configuration file. Each line read from these files is processed like a usual `mail' command.
When run with `--norc' (`-N') option, `mail' does not read the contents of system-wide configuration file. The user's file, if it exists, is always processed.
The user's configuration file is located in the user's home directory and is named `.mailrc'. The location and name of the system-wide configuration file is determined when configuring the package via `--with-mail-rc' option. It defaults to `sysconfdir/mail.rc'.
Messages 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:
The program is currently in development
The program is currently in development
`Guimb' is for mailboxes what `awk' is for text files. It processes mailboxes, applying the user-supplied scheme procedures to each of them in turn and saves the resulting output in mailbox format.
The Scheme program or expression to be executed is passed to `guimb' via the following options:
You can specify both of them. In this case, the PROGFILE is executed first.
There are four basic ways of passing mailboxes to `guimb'.
guimb [OPTIONS] [mailbox...]
guimb [OPTIONS] --mailbox DEFMBOX
guimb [OPTIONS] --mailbox DEFMBOX mailbox [mailbox...]
guimb [OPTIONS] --user USER [mailbox...]
If no mailboxes are specified in the command line, `guimb' reads and processes its standard input.
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.
This is a short summary of the command line options available to `guimb'.
Email bug reports to bug-mailutils@gnu.org. Be sure to include the word "mailutils" somewhere in the "Subject:" field.
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@,{c}ois Pinard pinard@IRO.UMontreal.CA.
This is a general index of all issues discussed in this manual
This is an alphabetical list of all MAILUTILS functions.
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.
Caution: Some Internet Service Providers do not permit to leave mail on server and the message will be deleted once downloaded.
This document was generated on 19 October 2001 using the texi2html translator version 1.54.