Skip to content

John McEleney / mailutils

Go to a project
Toggle navigation
Toggle navigation pinning
Commit 65164155 65164155a2a16498b5dcb473b6b3c58037d9f044 by Wojciech Polak
Options

Major reorganization in the documentation.

1 parent f8bb91cf
Expand all
Inline Side-by-side
Showing 36 changed files with 523 additions and 533 deletions
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{address_} is reserved */}
@code{#include <mailutils/address.h>}
@end smallexample
@end example
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
......@@ -15,10 +15,10 @@ 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.
RFC 822 for the details. @samp{[]} pairs mean "optional", @samp{/} means
"one or the other", and double-quoted characters are literals.
@example
@smallexample
addr-spec = local-part "@" domain
mailbox = addr-spec ["(" display-name ")"] /
[display-name] "<" [route] addr-spec ">"
......@@ -26,7 +26,7 @@ mailbox-list = mailbox ["," mailbox-list]
group = display-name ":" [mailbox-list] ";"
address = mailbox / group / unix-mbox
address-list = address ["," address-list]
@end example
@end smallexample
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
......@@ -75,7 +75,6 @@ The @code{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.
@end deftp
@deftypefun int address_create (address_t *@var{addr}, const char *@var{string})
......@@ -104,9 +103,6 @@ The return value is @code{0} on success and a code number on error conditions:
@end table
@end deftypefun
@deftypefun void address_destroy (address_t *@var{addr})
The @var{addr} is destroyed.
@end deftypefun
......@@ -154,7 +150,7 @@ 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.
@code{address_get_email()}, and all the rest, will return zero-length output.
The return value is @code{0} on success and a code number on error conditions:
@table @code
......@@ -163,7 +159,6 @@ The return value is @code{0} on success and a code number on error conditions:
@end table
@end deftypefun
@deftypefun int address_get_comments (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})
Accesses the comments extracted while parsing the @var{no}th email address.
......@@ -176,7 +171,6 @@ The return value is @code{0} on success and a code number on error conditions:
@end table
@end deftypefun
@deftypefun int address_get_email (address_t *@var{addr}, size_t @var{no}, char* @var{buf}, size_t @var{len}, size_t* @var{n})
Accesses the email addr-spec extracted while
......@@ -220,7 +214,7 @@ The return value is @code{0} on success and a code number on error conditions:
Accesses the route of an email addr-spec extracted while
parsing the @var{no}th 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>.
a string, those wishing to parse it should look at @file{mailutils/parse822.h}.
The return value is @code{0} on success and a code number on error conditions:
@table @code
......@@ -259,7 +253,6 @@ The return value is @code{0} on success and a code number on error conditions:
@end table
@end deftypefun
@deftypefun int address_get_count (address_t @var{addr}, size_t* @var{count})
Returns a count of the addresses in the address list.
......@@ -270,8 +263,7 @@ not @code{null}, the count will be written to *@var{count}.
The return value is @code{0}.
@end deftypefun
@section Example
@example
@subheading Example
@smallexample
@include addr.inc
@end example
@end smallexample
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{attribute_} is reserved */}
@code{#include <mailutils/attribute.h>}
@end example
@end smallexample
@deftypefun int attribute_create (attribute_t *@var{pattribute})
@end deftypefun
......@@ -56,7 +56,6 @@
@deftypefun int attribute_set_read (attribute_t @var{attribute})
@end deftypefun
@deftypefun int attribute_unset_seen (attribute_t @var{attribute})
@end deftypefun
......@@ -89,4 +88,3 @@
@deftypefun int attribute_to_string (attribute_t @var{attr}, char *@var{buf}, size_t @var{len}, size_t *@var{pwriten})
@end deftypefun
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{auth_} is reserved */}
@code{#include <mailutils/auth.h>}
@end example
@end smallexample
There are many ways to authenticate to a server. To be flexible the
authentication process is provided by two objects @code{auth_t} and
......@@ -34,11 +35,13 @@ if not set, this function can be overridden by a custom method.
@deftypefun int auth_epilogue (auth_t @var{auth})
@end deftypefun
@sp 1
A simple example of an authenticate function:
@example
#include <mailutils/auth.h>
@smallexample
#include <stdio.h>
#include <string.h>
#include <mailutils/auth.h>
int
my_authenticate (auth_t auth, char **user, char **passwd)
......@@ -64,4 +67,4 @@ my_authenticate (auth_t auth, char **user, char **passwd)
*passwd = strdup (p);
return 0;
@}
@end example
@end smallexample
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{body_} is reserved */}
@code{#include <mailutils/body.h>}
@end example
@end smallexample
@deftypefun int body_create (body_t *@var{body}, void *@var{owner})
Initialize an object @var{bdy}.
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
......@@ -61,4 +61,3 @@
@section Parse822
@cindex Parse822
@include parse822.texi
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{envelope_} is reserved */}
@code{#include <mailutils/envelope.h>}
@end example
@end smallexample
@deftypefun 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.
something close to ANSI @code{ctime()} format: Mon Jul 05 13:08:27 1999.
@end deftypefun
@deftypefun 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.
@end deftypefun
@deftypefun int envelope_get_message (envelope_t, message_t *);
......@@ -34,17 +31,13 @@ Primarily for internal use.
@end deftypefun
@deftypefun 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.
the sender to be set by the creator of an @code{envelope_t}.
@end deftypefun
@deftypefun 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.
the date to be set by the creator of an @code{envelope_t}.
@end deftypefun
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{folder_} is reserve */}
@code{#include <mailutils/folder.h>}
@end example
@end smallexample
@example
@smallexample
@group
folder_t url_t
-/var/mail- +---//---->/-----------------\ +-->/-----------\
......@@ -27,7 +28,7 @@
| mailbox_t(n) |
\-----------------/
@end group
@end example
@end smallexample
@deftypefun int folder_create (folder_t *, const char *@var{url})
@end deftypefun
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@menu
* Folder:: Folder.
* Mailbox:: Mailbox.
* Mailer:: Protocol Used to Send Mail.
* Message:: Message.
* Envelope:: Envelope.
* Headers:: Headers.
* Body:: Body.
* Attribute:: Attribute.
* Stream:: Stream.
* Iterator:: Iterator.
* Authenticator:: Authenticator.
* Address:: Address.
* Locker:: Locker.
* URL:: Uniform Resource Locators.
* Parse822:: Parsing RFC 822 headers.
* Mailcap:: Parsing RFC 1524 file.
* Folder:: Folder.
* Mailbox:: Mailbox.
* Mailer:: Protocol Used to Send Mail.
* Message:: Message.
* Envelope:: Envelope.
* Headers:: Headers.
* Body:: Body.
* Attribute:: Attribute.
* Stream:: Stream.
* Iterator:: Iterator.
* Authenticator:: Authenticator.
* Address:: Address.
* Locker:: Locker.
* URL:: Uniform Resource Locators.
* Parse822:: Parsing RFC 822 headers.
* Mailcap:: Parsing RFC 1524 file.
@end menu
Wherever the mail is and whatever format it is stored in, it is operated
upon using the same set of functions. To unified the C API,
@sc{gnu} Mailutils offers a heteroclite set of objects that work in
aggregation to do operations on
emails. Each object does a specific task and delegates non-related tasks to
others. The object comes alive by specifying a @emph{URL} parameter when
created, it will indicate the storage format or protocol
(POP3, IMAP4, MH, MAILDIR, etc ..).
aggregation to do operations on emails.
Each object does a specific task and delegates non-related tasks to others.
The object comes alive by specifying a @emph{URL} parameter when created,
it will indicate the storage format or protocol (POP3, IMAP4, MH, MAILDIR,
etc ..).
@example
@smallexample
@group
folder_t url_t
-/var/mail- +- .. ->+-----------------+ +-->+------------+
( alain *-)-+ | | url_t *-|---+ | port |
......@@ -67,130 +67,102 @@ created, it will indicate the storage format or protocol
| stream_t |
+--------------+
@end group
@end example
@end smallexample
As an example, here is a simplified version of @code{from} command. It
lists the @samp{From} and @samp{Subject} headers of every mail in a mailbox.
@example
@smallexample
@include sfrom.inc
@end example
@end smallexample
Here is a sample output produced by this program:
@example
@smallexample
@cartouche
% MAIL=pop://alain@@localhost ./sfrom
% ./sfrom pop://alain@@localhost
Passwd: xxxx
Jim Meyering <meyering@@foo.org> fetish(shellutils) beta
Fran@,{c}ois Pinard <pinard@@bar.org> recode new alpha
@dots{}
@end cartouche
@end example
@end smallexample
@node Folder
@comment node-name, next, previous, up
@section Folder
@subsection Folder
@cindex Folder
@include folder.texi
@node Mailbox
@comment node-name, next, previous, up
@section Mailbox
@subsection Mailbox
@cindex Mailbox
@include mailbox.texi
@node Mailer
@comment node-name, next, previous, up
@section Mailer
@subsection Mailer
@cindex Mailer
@include mailer.texi
@node Message
@comment node-name, next, previous, up
@section Message
@subsection Message
@cindex Message
@include message.texi
@node Envelope
@comment node-name, next, previous, up
@section Envelope
@subsection Envelope
@cindex Envelope
@include envelope.texi
@node Headers
@comment node-name, next, previous, up
@section Headers
@subsection Headers
@cindex Headers
@include headers.texi
@node Body
@comment node-name, next, previous, up
@section Body
@subsection Body
@cindex Body
@include body.texi
@node Attribute
@comment node-name, next, previous, up
@section Attribute
@subsection Attribute
@cindex Attribute
@include attribute.texi
@node Stream
@comment node-name, next, previous, up
@section Stream
@subsection Stream
@cindex Stream
@include stream.texi
@node Iterator
@comment node-name, next, previous, up
@section Iterator
@subsection Iterator
@cindex Iterator
@include iterator.texi
@node Authenticator
@comment node-name, next, previous, up
@section Authenticator
@subsection Authenticator
@cindex Authenticator
@include auth.texi
@node Address
@comment node-name, next, previous, up
@section Address
@subsection Address
@cindex Address
@include address.texi
@node Locker
@comment node-name, next, previous, up
@section Locker
@subsection Locker
@cindex Locker
@include locker.texi
@node URL
@comment node-name, next, previous, up
@section URL
@subsection URL
@cindex URL
@include url.texi
@node Parse822
@section Parse822 --- Functions for Parsing RFC 822 Headers
@subsection Parse822
@include parse822.texi
@node Mailcap
@section Mailcap --- Functions for Parsing RFC 1524 Files
@subsection Mailcap
@include mailcap.texi
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{header_} is reserved */}
@code{#include <mailutils/header.h>}
@end example
@end smallexample
So far we plan support for RFC822 and plan for RFC1522. with RFC1522 non ASCII
characters will be encoded.
......@@ -79,7 +80,6 @@ Content-Type
@item MU_HEADER_MIME_VERSION
MIME-Version
@end table
@end deftypefun
@deftypefun int header_get_value (header_t @var{hdr}, const char *@var{fn}, char *@var{fv}, size_t @var{len}, size_t *@var{n})
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{imap4_} is reserved */}
@code{#include <mailutils/imap4.h>}
@end example
@end smallexample
Internet Message Access Protocol - Version (4rev1). In IMAP4, the client
must be prepared to accept any responses at all times. The server responses
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{iterator_} is reserved */}
@code{#include <mailutils/iterator.h>}
@end example
@end smallexample
@deftypefun int iterator_create (iterator_t *)
@end deftypefun
......@@ -25,4 +25,3 @@
@deftypefun int iterator_is_done (iterator_t)
@end deftypefun
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
......@@ -11,24 +11,22 @@ about Scheme programming language, @xref{Top,,,r4rs,Revised(4) Report on
the Algorithmic Language Scheme}.
@menu
Functions Provided by libmu_scm
Functions Provided by @file{libmu_scm}
* Address Functions::
* Mailbox Functions::
* Message Functions::
* MIME Functions::
* Log Functions::
* Logging Functions::
Using libmu_scm
Using @file{libmu_scm}
* Direct Linking::
* Dynamic Linking::
@end menu
@node Address Functions
@section Address Functions
@subsection Address Functions
@deffn {Scheme Function} mu-address-get-personal ADDRESS NUM
Return personal part of an email address.
......@@ -54,14 +52,14 @@ Return number of parts in email address.
@end deffn
@node Mailbox Functions
@section Mailbox Functions
@subsection Mailbox Functions
@deffn {Scheme Function} mu-mailbox-open URL MODE
Opens a mailbox specified by URL.
Opens a mailbox specified by @var{URL}.
@end deffn
@deffn {Scheme Function} mu-mailbox-close MBOX
Closes mailbox MBOX
Closes mailbox @var{MBOX}.
@end deffn
@deffn {Scheme Function} mu-mailbox-get-url MBOX
......@@ -69,14 +67,14 @@ Returns the URL of the mailbox.
@end deffn
@deffn {Scheme Function} mu-mailbox-get-port MBOX MODE
Returns a port associated with the contents of the MBOX.
MODE is a string defining operation mode of the stream. It may
Returns a port associated with the contents of the @var{MBOX}.
@var{MODE} is a string defining operation mode of the stream. It may
contain any of the two characters: @samp{r} for reading, @samp{w} for
writing.
@end deffn
@deffn {Scheme Function} mu-mailbox-get-message MBOX MSGNO
Retrieve from MBOX message # MSGNO.
Retrieve from @var{MBOX} message # @var{MSGNO}.
@end deffn
@deffn {Scheme Function} mu-mailbox-messages-count MBOX
......@@ -96,17 +94,17 @@ Appends the message to the mailbox
@end deffn
@node Message Functions
@section Message Functions
@subsection Message Functions
@deffn {Scheme Function} mu-message-copy MESG
Creates the copy of the given message.
@end deffn
@deffn {Scheme Function} mu-message-set-header MESG HEADER VALUE REPLACE
Sets new VALUE to the header HEADER of the message MESG.
If the HEADER is already present in the message its value
is replaced with the supplied one if the optional REPLACE is
#t. Otherwise new header is created and appended.
Sets new @var{VALUE} to the header @var{HEADER} of the message @var{MESG}.
If the @var{HEADER} is already present in the message its value
is replaced with the supplied one if the optional @var{REPLACE}
is @code{#t}. Otherwise new header is created and appended.
@end deffn
@deffn {Scheme Function} mu-message-get-size MESG
......@@ -118,146 +116,146 @@ Returns number of lines in the given message.
@end deffn
@deffn {Scheme Function} mu-message-get-sender MESG
Returns the sender email address for the message MESG.
Returns the sender email address for the message @var{MESG}.
@end deffn
@deffn {Scheme Function} mu-message-get-header MESG HEADER
Returns the header value of the HEADER in the MESG.
Returns the header value of the @var{HEADER} in the @var{MESG}.
@end deffn
@deffn {Scheme Function} mu-message-get-header-fields MESG HEADERS
Returns the list of headers in the MESG. If optional HEADERS is
specified it should be a list of header names to restrict return
Returns the list of headers in the @var{MESG}. If optional @var{HEADERS}
is specified it should be a list of header names to restrict return
value to.
@end deffn
@deffn {Scheme Function} mu-message-set-header-fields MESG LIST REPLACE
Set the headers in the message MESG from LIST
LIST is a list of (cons HEADER VALUE)
Optional parameter REPLACE specifies whether the new header
values should replace the headers already present in the
message.
Set the headers in the message @var{MESG} from @var{LIST}.
@var{LIST} is a list of @code{(cons @var{HEADER} @var{VALUE})}.
Optional parameter @var{REPLACE} specifies whether the new header
values should replace the headers already present in the message.
@end deffn
@deffn {Scheme Function} mu-message-delete MESG FLAG
Mark given message as deleted. Optional FLAG allows to toggle deleted mark
The message is deleted if it is #t and undeleted if it is #f
Mark given message as deleted. Optional @var{FLAG} allows to toggle
deleted mark. The message is deleted if it is @code{#t} and undeleted
if it is @code{#f}.
@end deffn
@deffn {Scheme Function} mu-message-get-flag MESG FLAG
Return value of the attribute FLAG.
Return value of the attribute @var{FLAG}.
@end deffn
@deffn {Scheme Function} mu-message-set-flag MESG FLAG VALUE
Set the given attribute of the message. If optional VALUE is #f, the
attribute is unset.
Set the given attribute of the message. If optional @var{VALUE}
is @code{#f}, the attribute is unset.
@end deffn
@deffn {Scheme Function} mu-message-get-user-flag MESG FLAG
Returns value of the user attribute FLAG.
Returns value of the user attribute @var{FLAG}.
@end deffn
@deffn {Scheme Function} mu-message-set-user-flag MESG FLAG VALUE
Set the given user attribute of the message. If optional VALUE is
#f, the attribute is unset.
Set the given user attribute of the message. If optional @var{VALUE}
is @code{#f}, the attribute is unset.
@end deffn
@deffn {Scheme Function} mu-message-get-port MESG MODE FULL
Returns a port associated with the given MESG. MODE is a string
Returns a port associated with the given @var{MESG}. @var{MODE} is a string
defining operation mode of the stream. It may contain any of the
two characters: @samp{r} for reading, @samp{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
If optional @var{FULL} argument specified, it should be a boolean value.
If it is @code{#t} then the returned port will allow access to any
part of the message (including headers). If it is @code{#f} then the port
accesses only the message body (the default).
@end deffn
@deffn {Scheme Function} mu-message-get-body MESG
Returns the message body for the message MESG.
Returns the message body for the message @var{MESG}.
@end deffn
@deffn {Scheme Function} mu-message-send MESG MAILER
Sends the message MESG. Optional MAILER overrides default
mailer settings in mu-mailer.
Sends the message @var{MESG}. Optional @var{MAILER}
overrides default mailer settings in @code{mu-mailer}.
@end deffn
@node MIME Functions
@section MIME Functions
@subsection MIME Functions
@deffn {Scheme Function} mu-mime-create FLAGS MESG
Creates a new MIME object.
@end deffn
@deffn {Scheme Function} mu-mime-multipart? MIME
Returns #t if MIME is a multipart object.
Returns @code{#t} if @var{MIME} is a multipart object.
@end deffn
@deffn {Scheme Function} mu-mime-get-num-parts MIME
Returns number of parts in a MIME object.
Returns number of parts in a @var{MIME} object.
@end deffn
@deffn {Scheme Function} mu-mime-get-part MIME PART
Returns part number PART from a MIME object.
Returns part number @var{PART} from a @var{MIME} object.
@end deffn
@deffn {Scheme Function} mu-mime-add-part MIME MESG
Adds MESG to the MIME object.
Adds @var{MESG} to the @var{MIME} object.
@end deffn
@deffn {Scheme Function} mu-mime-get-message MIME
Converts MIME object to a message.
Converts @var{MIME} object to a message.
@end deffn
@node Log Functions
@section Log Functions
@node Logging Functions
@subsection Logging Functions
@deffn {Scheme Function} mu-openlog IDENT OPTION FACILITY
Opens a connection to the system logger for Guile program.
@end deffn
@deffn {Scheme Function} mu-logger PRIO TEXT
Generates a log message to be distributed via syslogd.
Generates a log message to be distributed via @code{syslogd}.
@end deffn
@deffn {Scheme Function} mu-closelog
Closes the channel to the system logger open by mu-openlog.
Closes the channel to the system logger open by @code{mu-openlog}.
@end deffn
@node Direct Linking
@section Direct Linking
@subsection Direct Linking
If you plan to link your program directly to @file{libguile}, it will
probably make sense to link @file{libmu_scm} directly as well. The
arguments to the program loader may be obtained by running
@example
@smallexample
mailutils-config --link guile
@end example
@end smallexample
@noindent
@xref{mailutils-config}, for more information about this utility.
Here is a sample Makefile fragment:
@example
@smallexample
MU_LDFLAGS=`mailutils-config --link guile`
MU_INCLUDES=`mailutils-config --include`
myprog: myprog.c
$(CC) -omyprog $(CFLAGS) $(MU_INCLUDES) myprog.c $(MU_LDFLAGS)
@end example
@end smallexample
@node Dynamic Linking
@section Dynamic Linking
@subsection Dynamic Linking
Dynamic linking is the preferred method of using @file{libmu_scm}. It
uses Guile ``use-modules'' mechanism. An interface module
@file{mailutils.scm} is provided in order to facilitate using this
method. This module is installed in the package data directory (by
default it is @var{prefix}/share/mailutils). A sample use of
default it is @file{@var{prefix}/share/mailutils}). A sample use of
this module is:
@example
@smallexample
(set! %load-path (list "/usr/local/share/mailutils"))
(use-modules (mailutils))
......@@ -265,11 +263,8 @@ this module is:
(let ((mb (mu-mailbox-open "/var/spool/mail/gray" "r")))
...
@end example
@end smallexample
@emph{Note}, that you should explicitly modify the @code{%load-path}
before calling @code{use-modules}, otherwise Guile will not be able to
find @file{mailutils.scm}.
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
......@@ -13,15 +13,15 @@ library mechanism.
@menu
* Data Types::
* Initializing the libmuauth::
* Initializing libmuauth::
* Module Creation and Destruction::
* Obtaining Authorization Information::
* Existing Modules::
* Using Libmuauth in Your Programs::
* Using libmuauth in Your Programs::
@end menu
@node Data Types
@section Data Types
@subsection Data Types
@cindex libmuauth, data types
@deftp {Data Type} mu_auth_fp
......@@ -29,12 +29,12 @@ library mechanism.
This is a pointer to authentication or authorization data. It
is defined as follows:
@example
@smallexample
typedef int (*mu_auth_fp) (void *@var{return_data},
void *@var{key},
void *@var{func_data},
void *@var{call_data});
@end example
@end smallexample
@noindent
Its arguments are:
......@@ -74,7 +74,7 @@ The @code{mu_auth_data} is used to return the information about the
user. It is similar to system @code{struct passwd}, except that it
is more mailutils-specific. Its definition is:
@example
@smallexample
@group
struct mu_auth_data @{
/* These are from struct passwd */
......@@ -90,7 +90,7 @@ struct mu_auth_data @{
int change_uid; /* Should the uid be changed? */
@};
@end group
@end example
@end smallexample
@end deftp
@deftp {Data Type} mu_auth_module
......@@ -98,7 +98,7 @@ struct mu_auth_data @{
The @code{mu_auth_module} structure contains full information about a
libmuauth module. It is declared as follows:
@example
@smallexample
@group
struct mu_auth_module @{
char *name; /* Module name */
......@@ -111,11 +111,11 @@ struct mu_auth_module @{
void *auth_by_uid_data; /* ... and its specific data */
@};
@end group
@end example
@end smallexample
@end deftp
@node Initializing the libmuauth
@section Initializing the libmuauth
@node Initializing libmuauth
@subsection Initializing @file{libmuauth}
@deftypefun void mu_auth_init (void)
......@@ -131,7 +131,7 @@ This macro registers all default modules and calls @code{mu_auth_init()}.
@end deftypefun
@node Module Creation and Destruction
@section Module Creation and Destruction
@subsection Module Creation and Destruction
@deftypefun int mu_auth_data_alloc (struct mu_auth_data **ptr, const char *name, const char *passwd, uid_t uid, gid_t gid, const char *gecos, const char *dir, const char *shell, const char *mailbox, int change_uid)
......@@ -151,7 +151,7 @@ Register the module defined by the @var{mod} argument.
@end deftypefun
@node Obtaining Authorization Information
@section Obtaining Authorization Information
@subsection Obtaining Authorization Information
@cindex libmuauth, obtaining authorization information
@deftypefun int mu_auth_runlist (list_t @var{flist}, void *@var{return_data}, void *@var{key}, void *@var{call_data});
......@@ -188,7 +188,7 @@ Authenticate the user whose data are in @var{auth_data} using password
@end deftypefun
@node Existing Modules
@section Existing Modules
@subsection Existing Modules
@cindex libmuauth modules
@deftypefun int mu_auth_nosupport (void *return_data, void *key, void *func_data, void *call_data);
......@@ -240,31 +240,31 @@ module.
@end defvar
@node Using Libmuauth in Your Programs
@section Using Libmuauth in Your Programs
@cindex using libmuauth
@cindex linking with libmuauth
@node Using libmuauth in Your Programs
@subsection Using @file{libmuauth} in Your Programs
@cindex Using @file{libmuauth}
@cindex Linking with @file{libmuauth}
@cindex libmuauth, linking with
To link your program against @file{libmuauth}, obtain loader arguments
by running @command{mailutils-config} as follows:
@example
@smallexample
mailutils-config --link auth
@end example
@end smallexample
@noindent
@xref{mailutils-config}, for more information about this utility.
Here is a sample Makefile fragment:
@example
@smallexample
MU_LDFLAGS=`mailutils-config --link auth`
MU_INCLUDES=`mailutils-config --include`
myprog: myprog.c
$(CC) -omyprog $(CFLAGS) $(MU_INCLUDES) myprog.c $(MU_LDFLAGS)
@end example
@end smallexample
If your program will be using only default modules provided by the
library, then it will suffice to call
......@@ -272,7 +272,7 @@ library, then it will suffice to call
your program. As an example, consider the following code fragment
(it is taken from the @command{imap4d} daemon):
@example
@smallexample
@group
int
main (int argc, char **argv)
......@@ -287,13 +287,13 @@ main (int argc, char **argv)
NULL, &daemon_param);
@dots{}
@end group
@end example
@end smallexample
Otherwise, if your program will use it's own modules, first register
them with @code{mu_auth_register_module} and then call
@code{mu_auth_init()}, e.g.:
@example
@smallexample
@group
struct mu_auth_module radius_module = @{
@dots{}
......@@ -312,12 +312,12 @@ main (int argc, char **argv)
@dots{}
@end group
@end example
@end smallexample
These two approaches may be combined, allowing you to use both your
modules and the ones provided by Mailutils. Consider the example below:
@example
@smallexample
@group
int
main (int argc, char **argv)
......@@ -329,7 +329,4 @@ main (int argc, char **argv)
@dots{}
@}
@end group
@end example
@end smallexample
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{locker_} is reserved */}
@code{#include <mailutils/locker.h>}
@end example
@end smallexample
@deftypefun int locker_create (locker_t * @var{plocker}, char *@var{filename}, size_t @var{len}, int @var{flags})
@end deftypefun
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{mailbox_} is reserved */}
@code{#include <mailutils/mailbox.h>}
@end example
@end smallexample
@deftp {Data Type} mailbox_t
The @code{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.
@end deftp
@example
@smallexample
@group
mailbox_t url_t
-/var/mail- +---//---->/-----------------\ +-->/-----------\
......@@ -32,9 +33,9 @@ from the data structure.
| message_t(n) |
\-----------------/
@end group
@end example
@end smallexample
@deftypefun int mailbox_append_message (mailbox_t @var{mbox}, message_t @var{message})
@deftypefun int mailbox_append_message (mailbox_t @var{mbox}, message_t @var{message})
The @var{message} is appended to the mailbox @var{mbox}.
The return value is @code{0} on success and a code number on error conditions:
......
@comment GNU Mailutils -- a suite of utilities for electronic mail
@comment Copyright (C) 1999, 2000, 2001 Free Software Foundation, Inc.
@comment Copyright (C) 1999, 2000, 2001, 2004 Free Software Foundation, Inc.
@comment
@comment GNU Mailutils is free software; you can redistribute it and/or modify
@comment it under the terms of the GNU General Public License as published by
......@@ -21,13 +21,13 @@
#include <mailutils/error.h>
int
main(int argc, char **argv)
main (int argc, char **argv)
@{
stream_t stream = NULL;
int status = 0;
char *file = argc == 1 ? "/etc/mailcap" : argv[1];
mu_mailcap_t mailcap = NULL;
status = file_stream_create (&stream, file, MU_STREAM_READ);
if (status)
@{
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{mu_mailcap_} is reserved */}
@code{#include <mailutils/mailcap.h>}
@end example
@end smallexample
The standard rfc1524(A User Agent Configuration Mechanism) suggests a file format
The standard @cite{RFC 1524} (A User Agent Configuration Mechanism) suggests a file format
to be used to inform a mail user agent about facilities for handling mail in various
format. The configuration file is known also as mailcap and it is tipically found
in UNIX platforms, a example of @file{/etc/mailcap}:
@example
@smallexample
application/pgp; gpg < %s | metamail; needsterminal; \
test=test %@{encapsulation@}=entity ; copiousoutput
@end example
@end smallexample
A mailcap file consits of a set of mailcap entries per line, lines beginning with @emph{#} are
A mailcap file consits of a set of mailcap entries per line, lines beginning with @samp{#} are
considered comments and ignored. Long mailcap entry may be continued on multiple lines if
each line ends with a backslash character @emph{\}, the multiline will be considered a single
each line ends with a backslash character @samp{\}, the multiline will be considered a single
mailcap entry. The overall format in BNF:
@example
@smallexample
Mailcap-File = *Mailcap-Line
Mailcap-Line = Comment | Mailcap-Entry
Comment = NEWLINE | "#" * CHAR NEWLINE
NEWLINE = <newline as defined by OS convention>
@end example
@end smallexample
Each mailcap entry consists of a number of fields, separated by semi-colons.
The first two filds are required and must occur in the secified order, the remaining
fields are optional.
@example
@smallexample
Mailcap-Entry = typefield ";" view-command ";" *[ ";" field ]
@end example
@end smallexample
@deftp {Data Type} mu_mailcap_t, mu_mailcap_entry_t
The @code{mu_mailcap_t} and @code{mu_mailcap_entry_t} objects are used to hold information
and it is an opaque data structure to the user. Functions are provided to retrieve information
from the data structure.
@end deftp
@example
@smallexample
@group
mu_mailcap_t mu_mailcap_entry_t
-/etc/mailcap- +----->/------------------------\ +-->/--------------------\
......@@ -51,12 +56,12 @@ from the data structure.
\------------------------/ | field[n] |
\--------------------/
@end group
@end example
@end smallexample
An example of parsing a mailcap file.
@example
@subheading An example of parsing a mailcap file:
@smallexample
@include mailcap.inc
@end example
@end smallexample
@deftypefun int mu_mailcap_create (mu_mailcap_t *@var{mailcap}, stream_t @var{stream})
The function allocates, parses the buffer from the @var{stream} and initializes @var{mailcap}.
......@@ -69,7 +74,6 @@ The return value is @code{0} on success and a code number on error conditions:
@deftypefun void mu_mailcap_destroy (mu_mailcap_t *@var{mailcap})
Release any resources from the mailcap object.
@end deftypefun
@deftypefun int mu_mailcap_entries_count (mu_mailcap_t @var{mailcap}, size_t *@var{count})
......@@ -104,4 +108,3 @@ The return value is @code{0} on success and a code number on error conditions:
@deftypefun int mu_mailcap_entry_get_field (mu_mailcap_entry_t @var{entry}, size_t @var{no}, char * @var{buffer}, size_t @var{buflen}, size_t * @var{pn})
@end deftypefun
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{maildir_} is reserved */}
@code{#include <mailutils/maildir.h>}
@end example
@end smallexample
QMail mailbox format. Not implemented.
QMail mailbox format.
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{mailer_} is reserved */}
@code{#include <mailutils/mailer.h>}
@end example
@end smallexample
The API is still changing.
......@@ -40,7 +41,6 @@ and "Bcc:" fields, this is equivalent to sendmail's @var{-t} flag.
Note: the previous implementation of mailer_send_message() was equivalent
to having both @var{from} and @var{to} be @var{NULL}.
@end deftypefun
@deftypefun int mailer_get_property (mailer_t, property_t *)
......@@ -64,7 +64,8 @@ to having both @var{from} and @var{to} be @var{NULL}.
@deftypefun int mailer_get_url (mailer_t, url_t *)
@end deftypefun
@subheading Some usage notes.
@sp 1
@subheading Some Usage Notes
Some possible use cases the API must support are:
......@@ -104,23 +105,24 @@ Some possible use cases the API must support are:
Don't want mail loops, so the null but valid SMTP address of <> is
the envelope from.
@subheading The sendmail mailer.
@subheading The Sendmail Mailer
/sbin/sendmail isn't always sendmail... sometimes its a sendmail-compatible
wrapper, so assume /sbin/sendmail understands only a recipient
list, -f and -oi, these seem to be pretty basic. Cross fingers.
@file{/sbin/sendmail} isn't always sendmail... sometimes its a
sendmail-compatible wrapper, so assume @file{/sbin/sendmail} understands
only a recipient list, @option{-f} and @option{-oi}, these seem
to be pretty basic. Cross fingers.
Pipe to "/sbin/sendmail -oi [-f from] [to...]", supplying -f if there
was a from, and supplying the recipient list from the to (if there
is no recipient list, assume it will read the message contents for
the recipients).
Pipe to "/sbin/sendmail -oi [-f from] [to...]", supplying @option{-f}
if there was a from, and supplying the recipient list from the to
(if there is no recipient list, assume it will read the message
contents for the recipients).
Note: since the stdout and stderr of sendmail is closed, we have no
way of ever giving feedback on failure. Also, what should the return
code be from mailer_send_message() when sendmail returns 1? 1 maps to EPERM,
which is less than descriptive!
@subheading The SMTP mailer.
@subheading The SMTP Mailer
This mailer does NOT canonicalize the message. This must be done before
sending the message, or it may be assumed that the MTA will do so.
......@@ -130,13 +132,12 @@ It does blind out the Bcc: header before sending, though.
Note: mutt always puts the recipient addresses on the command line, even
bcc ones, do we strip the bcc before forwarding with SMTP?
@subheading Non-RFC822 addresses.
@subheading Non-RFC822 Addresses
An address that has no domain is not and RFC822 email address. What
do I do with them? Should the user of the API be responsible for
determining what is mean by email to "john" means? Or should the
be able to configure sendmail to decide globally what this means. If so, we
can pass the address to sendmail, but we have to decide for SMTP! So,
right now these addresses are rejected. This could be changed.
be able to configure sendmail to decide globally what this means.
If so, we can pass the address to sendmail, but we have to decide
for SMTP! So, right now these addresses are rejected.
This could be changed.
......
......@@ -2,7 +2,7 @@
@c %**start of header
@setfilename mailutils.info
@settitle GNU Mailutils Manual
@setchapternewpage off
@setchapternewpage odd
@finalout
@c %**end of header
......@@ -47,7 +47,8 @@ Published by the Free Software Foundation,
59 Temple Place - Suite 330
Boston, MA 02111-1307, USA
Copyright @copyright{} 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004
Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
......@@ -84,20 +85,20 @@ documents GNU Mailutils Version @value{VERSION}.
@end ifinfo
@menu
* Introduction:: GNU Mailutils.
* libmailbox:: Main library.
* libmuauth:: Auxiliary library for authenticating users.
* libmu_scm:: Interface with Guile.
* libsieve:: GNU implementation of Sieve mail filtering.
* Programs:: Programs.
* Reporting Bugs:: How to report a bug.
* News:: Where to get information about @sc{gnu} Mailutils.
* Introduction:: Preliminary Information.
* Programs:: Mailutils Programs.
* Libraries:: Mailutils Libraries.
* Sieve Language:: The Sieve Language.
* Reporting Bugs:: How to Report a Bug.
* News:: Getting News About @sc{gnu} Mailutils.
* Acknowledgement:: Thanks and Credits.
Appendices
* References:: References.
* GNU FDL:: This manual is under the GNU Free
Documentation License.
Indices
* Function Index:: All Mailutils Functions.
......@@ -106,22 +107,152 @@ Indices
@end menu
@node Introduction, libmailbox, Top, Top
@node Introduction, Programs, Top, Top
@comment node-name, next, previous, up
@chapter Introduction
@cindex Introduction
@sc{gnu} Mailutils offers a general purpose library whose aim is to
provide a rich set of functions for accessing different mailbox formats and
mailers.
@sc{gnu} Mailutils contains a series of useful mail clients, servers,
and libraries. These are the primary mail utilities of the GNU system.
Specifically, this package contains a POP3 server, an IMAP4 server,
and a Sieve mail filter. It also provides a POSIX `mailx' client,
and a collection of other tools. The central library is capable of
accessing different mailbox formats and mailers as well as off of
local or remote POP3 and IMAP4 servers.
This software is part of the GNU Project and belongs to the Free
Software Foundation. All libraries are licensed using the GNU LGPL.
The documentation is licensed under the GNU FDL, and everything
else is licensed using the GNU GPL.
@subheading Why use this package?
This package started off to try and handle large mailbox files more
gracefully then current POP3 servers did. While it handles this task,
it also allows you to support a variety of different mailbox formats
without any real effort on your part. Also, if a new format is added
at a later date, your program will support that new format
automatically as soon as it is compiled against the new library.
@node Programs, Libraries, Introduction, Top
@comment node-name, next, previous, up
@chapter Mailutils Programs
@cindex Programs
@include programs.texi
@node Libraries, Sieve Language, Programs, Top
@comment node-name, next, previous, up
@chapter Mailutils Libraries
@cindex Libraries
@menu
* libmailbox:: The Core Library.
* libmuauth:: Auxiliary Library for Authenticating Users.
* libmu_scm:: Mailutils to Scheme Interface.
* libsieve:: GNU Implementation of Sieve Mail Filtering.
@end menu
@node libmailbox, libmuauth, Libraries, Libraries
@comment node-name, next, previous, up
@section Framework
@cindex Framework
@include framework.texi
@node libmuauth, libmu_scm, libmailbox, Libraries
@comment node-name, next, previous, up
@section Authentication Library
@cindex Authentication Library
@cindex libmuauth
@include libmuauth.texi
@node libmu_scm, libsieve, libmuauth, Libraries
@comment node-name, next, previous, up
@section Mailutils to Scheme Interface
@cindex Scheme
@cindex libmu_scm
@include libmu_scm.texi
@node libsieve, , libmu_scm, Libraries
@comment node-name, next, previous, up
@section Sieve Library
@cindex Sieve Library
@cindex libsieve
@include libsieve.texi
@node Sieve Language, Reporting Bugs, Libraries, Top
@comment node-name, next, previous, up
@chapter Sieve Language
@cindex Sieve Language
@include sieve.texi
@node Reporting Bugs, News, Sieve Language, Top
@comment node-name, next, previous, up
@chapter Reporting Bugs
Email bug reports to @email{bug-mailutils@@gnu.org}.
Be sure to include the word ``mailutils'' somewhere
in the ``Subject:'' field.
@section References
As the purpose of bug reporting is to improve software, please be sure
to include maximum information when reporting a bug. The information
needed is:
For more information on,
@itemize
@item Version of the package you are using.
@item Compilation options used when configuring the package.
@item Conditions under which the bug appears.
@end itemize
The archives of bug-mailutils mailing list are available from
@url{http://mail.gnu.org/@/mailman/@/listinfo/@/bug-mailutils}.
@node News, Acknowledgement, Reporting Bugs, Top
@comment node-name, next, previous, up
@chapter Getting News About @sc{gnu} Mailutils
The two places to look for any news regarding @sc{gnu} Mailutils are the
Mailutils homepage at @url{http://www.gnu.org/@/software/@/mailutils}, and the
project page at @url{http://savannah.gnu.org/@/projects/@/mailutils}.
The updated versions of this manual are available online from
@url{http://www.gnu.org/@/software/@/mailutils/@/manual}.
@node Acknowledgement, References, News, Top
@comment node-name, next, previous, up
@chapter Acknowledgement
In no particular order,
@itemize @bullet
@item
SMTP
Jakob Kaivo @email{jkaivo@@ndn.net},
@item
Jeff Bailey @email{jbailey@@gnu.org},
@item
Sean Perry @email{shaleh@@debian.org},
@item
Thomas Fletcher @email{thomasf@@qnx.com},
@item
Dave Inglis @email{dinglis@@qnx.com},
@item
Brian Edmond @email{briane@@qnx.com},
@item
Sam Roberts @email{sroberts@@uniserve.com},
@item
Sergey Poznyakoff @email{gray@@Mirddin.farlep.net},
@item
Fran@,{c}ois Pinard @email{pinard@@IRO.UMontreal.CA}.
@item
Jordi Mallach @email{jordi@@sindominio.net}
@item
Wojciech Polak @email{polak@@gnu.org}
@end itemize
@node References, GNU FDL, Acknowledgement, Top
@comment node-name, next, previous, up
@appendix References
@itemize @bullet
@item SMTP
@itemize @minus
@item
......@@ -131,8 +262,7 @@ SMTP
@cite{RFC 2368: The mailto URL scheme}
@end itemize
@item
POP3
@item POP3
@itemize @minus
@item
......@@ -152,8 +282,7 @@ Protocol (POP3)}
@cite{RFC 2384: POP URL Scheme}
@end itemize
@item
IMAP4
@item IMAP4
@itemize @minus
@item
......@@ -179,11 +308,9 @@ IMAP4
@item
@cite{RFC 2245: Anonymous SASL Mechanism}
@end itemize
@item
message formats
@item message formats
@itemize @minus
@item
......@@ -209,8 +336,7 @@ Conformance Criteria and Examples}
@cite{RFC 2111: Content-ID and Message-ID Uniform Resource Locators}
@end itemize
@item
miscellaneous related topics
@item miscellaneous related topics
@itemize @minus
@item
......@@ -231,112 +357,10 @@ Notifications}
@end itemize
@end itemize
@node libmailbox, libmuauth, Introduction, Top
@comment node-name, next, previous, up
@chapter Framework
@cindex Framework
@include framework.texi
@node libmuauth, libmu_scm, libmailbox, Top
@chapter Authentication Library
@cindex Authentication Library
@cindex libmuauth
@include libmuauth.texi
@node libmu_scm, libsieve, libmuauth, Top
@chapter Mailutils to Scheme interface
@cindex Scheme
@cindex libmu_scm
@include libmu_scm.texi
@node libsieve, Programs, libmu_scm, Top
@chapter Sieve Library
@cindex Sieve Library
@cindex libsieve
@include libsieve.texi
@node Programs, Reporting Bugs, libsieve, Top
@comment node-name, next, previous, up
@chapter Programs
@cindex Programs
@include programs.texi
@page
@node Reporting Bugs, News, Programs, Top
@comment node-name, next, previous, up
@chapter Reporting Bugs
@cindex Reporting Bugs
Email bug reports to @email{bug-mailutils@@gnu.org}.
Be sure to include the word ``mailutils'' somewhere in the ``Subject:''
field.
As the purpose of bug reporting is to improve software, please be sure
to include maximum information when reporting a bug. The information
needed is:
@itemize
@item Version of the package you are using.
@item Compilation options used when configuring the package.
@item Conditions under which the bug appears.
@end itemize
The archives of bug-mailutils mailing list are available from
@url{http://mail.gnu.org/mailman/listinfo/bug-mailutils}.
@node News, Acknowledgement, Reporting Bugs, Top
@chapter Getting News About @sc{gnu} Mailutils
The two places to look for any news regarding @sc{gnu} Mailutils are the
Mailutils homepage at @url{http://www.gnu.org/software/mailutils}, and the
project page at @url{http://savannah.gnu.org/projects/mailutils}.
The updated versions of this manual are available online from
@url{http://www.gnu.org/software/mailutils/manual}.
@node Acknowledgement, GNU FDL, News, Top
@comment node-name, next, previous, up
@chapter Acknowledgement
@cindex Acknowledgement
In no particular order,
@itemize @bullet
@item
Jakob Kaivo @email{jkaivo@@ndn.net},
@item
Jeff Bailey @email{jbailey@@gnu.org},
@item
Sean Perry @email{shaleh@@debian.org},
@item
Thomas Fletcher @email{thomasf@@qnx.com},
@item
Dave Inglis @email{dinglis@@qnx.com},
@item
Brian Edmond @email{briane@@qnx.com},
@item
Sam Roberts @email{sroberts@@uniserve.com},
@item
Sergey Poznyakoff @email{gray@@Mirddin.farlep.net},
@item
Fran@,{c}ois Pinard @email{pinard@@IRO.UMontreal.CA}.
@item
Jordi Mallach @email{jordi@@sindominio.net}
@item
Wojciech Polak @email{polak@@gnu.org}
@end itemize
@page
@node GNU FDL, Function Index, Acknowledgement, Top
@node GNU FDL, Function Index, References, Top
@comment node-name, next, previous, up
@include fdl.texi
@node Function Index, Program Index, GNU FDL, Top
@comment node-name, next, previous, up
@unnumbered Function Index
......@@ -353,15 +377,12 @@ This is an alphabetical list of all Mailutils functions.
@printindex pg
@page
@node Concept Index, , Program Index, Top
@node Concept Index, , Program Index, Top
@comment node-name, next, previous, up
@unnumbered Concept Index
This is a general index of all issues discussed in this manual
@printindex cp
@page
@contents
@bye
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{mbox_} is reserved */}
@code{#include <mailutils/mbox.h>}
@end example
@end smallexample
The most common mailbox format on UNIX platform is @emph{mbox}. Mbox is a
text file that contains messages separated by a special format string.
@example
From SP envelope-sender SP date [SP moreinfo]
@end example
@smallexample
From SP envelope-sender SP date [SP moreinfo]
@end smallexample
@table @code
@item "From "
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@code{#include <mailutils/message.h>}
@smallexample
@code{/* Prefix @emph{message_} is reserve */}
@code{#include <mailutils/message.h>}
@end example
@end smallexample
The @code{message_t} object is a convenient way to manipulate messages. It
encapsulates the @code{envelope_t}, the @code{header_t} and the @code{body_t}.
@example
@smallexample
@group
mailbox_t
__________ message_t
......@@ -27,7 +28,7 @@ encapsulates the @code{envelope_t}, the @code{header_t} and the @code{body_t}.
| stream_t |
+-----------------------+
@end group
@end example
@end smallexample
@deftypefun void message_create (message_t *@var{msg}, void *@var{owner})
@end deftypefun
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{mh_} is reserved */}
@code{#include <mailutils/mh.h>}
@end example
@end smallexample
Mail Handler mailbox format. Not implemented.
Mail Handler mailbox format.
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{pop3_} is reserve */}
@code{#include <mailutils/pop3.h>}
@end example
@end smallexample
Multipurpose Internet Mail Extensions (MIME).
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
......@@ -16,7 +16,7 @@ Every Mailutils object has a corresponding C structure holding its interface
and specific data. For example mu_object_t, is the root object and all mailutils objects
extends it:
@example
@smallexample
struct _mu_object;
typedef struct _mu_object* mu_object_t;
......@@ -33,13 +33,13 @@ struct _mu_object
struct _mu_object_vtable *vtable;
int type;
@}
@end example
@end smallexample
The @var{vtable} is an array of pointers to function, it provides the interface
or the list of function for this object. The library provides wrapper to
access the functions instead using the @var{vtable} directly.
@example
@smallexample
int mu_object_notify(mu_object object, int event, void *data)
@{
if (object == NULL || object->vtable == NULL
......@@ -47,14 +47,14 @@ int mu_object_notify(mu_object object, int event, void *data)
return MU_ERR_NOT_SUPPORTED;
return object->vtable->notify (object, event, data);
@}
@end example
@end smallexample
Instead of using macros or the vtable directly.
@example
@smallexample
#define mu_object_notify(o, evt, d) ((o)->vtable->notify(o, evt, d))
@end example
@end smallexample
@section Implementing an interface
@section Implementing an Interface
@comment ***********************************************************
@comment This is not a very good/usefull example, we should do one using
......@@ -69,7 +69,7 @@ For a more concrete implementation, lets say we are implementing some caching ma
but we need to keep a better track of the objects in our implementation.
We take the approach of simple reference counting and extend the mu_object_t.
@example
@smallexample
#include <mailutils/sys/object.h>
struct my_object;
......@@ -129,13 +129,13 @@ my_mu_object_create (mu_object_t *pobject)
*pobject = &ref->base.vtable
return 0;
@}
@end example
@end smallexample
The interface adds a @code{decrement} and @code{increment} to the @code{mu_object_t}
interface. Creating a @code{refcount_t} can be savely typecast to @code{mu_object_t},
for example:
@example
@smallexample
refcount_t ref;
mu_object_t obj;
refcount_create (&ref);
......@@ -143,4 +143,4 @@ refcount_create (&ref);
/* send a notification to the listeners of an event. */
mu_object_notify ((mu_object_t)ref, 5, NULL)
@end example
@end smallexample
......
......@@ -2,7 +2,7 @@
@c %**start of header
@setfilename muint.info
@settitle GNU Mailutils, the architecture and development
@setchapternewpage off
@setchapternewpage odd
@finalout
@c %**end of header
......@@ -20,7 +20,7 @@ Published by the Free Software Foundation,
59 Temple Place - Suite 330
Boston, MA 02111-1307, USA
Copyright @copyright{} 2003 Free Software Foundation, Inc.
Copyright @copyright{} 2003, 2004 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{nntp_} is reserved */}
@code{#include <mailutils/nntp.h>}
@end example
@end smallexample
Network News Transfer Protocol. Not implemented.
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{parse822_} is reserved */}
@code{#include <mailutils/parse822.h>}
@end example
@end smallexample
Internet Message Format, see Address node for the discussion.
......@@ -55,7 +56,6 @@ Internet Message Format, see Address node for the discussion.
@deftypefun int parse822_quote_local_part (char** quoted, const char* raw)
@end deftypefun
@deftypefun int parse822_field_body (const char** p, const char *e, char** fieldbody)
@end deftypefun
......
......@@ -4,20 +4,24 @@
@finalout
@comment This is part of the GNU Mailutils manual.
@comment Copyright (C) 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc.
@comment Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@comment See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix "mu_pop3_" is reserved */}
@code{#include <mailutils/pop3.h>}
@end example
@end smallexample
The purpose of the Post Office Protocol Version 3 (POP3) is to permit a client
to download a maildrop from a remote server, the protocol 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.
The purpose of the Post Office Protocol Version 3 (POP3) is to permit a client to download a maildrop from a remote
server, the protocol 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.
@itemize @bullet
@item
Authorization state
......@@ -94,7 +98,7 @@ To reset the state or break the downloading, the user should disconnect @code{mu
location after a sudden disconnect, it may be necessary to wait before working on the same mailbox, if not the user may
receive a ``Mailbox busy'' error code}.
@example
@smallexample
@group
/* Example on how to implement a callback mechanism on top of the library. */
int pop3_list_cb (mu_pop3_t pop3, int msgno, int (*callback_list)(int msgno, size_t octet))
......@@ -108,7 +112,7 @@ int pop3_list_cb (mu_pop3_t pop3, int msgno, int (*callback_list)(int msgno, siz
return status;
@}
@end group
@end example
@end smallexample
@subsubsection Initialization
@cindex POP3 Initialization
......@@ -296,7 +300,7 @@ Errors:
@end table
@end deftypefun
@example
@smallexample
#include <stdio.h>
#include <mailutils/pop3.h>
......@@ -316,7 +320,7 @@ print_message (mu_pop3_t pop3, unsigned int msgno)
@}
return status;
@}
@end example
@end smallexample
@cindex POP3 TOP
......@@ -333,7 +337,7 @@ Errors:
@end table
@end deftypefun
@example
@smallexample
#include <stdio.h>
#include <mailutils/pop3.h>
......@@ -351,7 +355,7 @@ print_top (mu_pop3_t pop3, unsigned int msgno, unsigned int lines)
@}
return status;
@}
@end example
@end smallexample
@cindex POP3 RSET
......@@ -410,7 +414,7 @@ Errors:
@end table
@end deftypefun
@example
@smallexample
#include <stdio.h>
#include <stdlib.h>
#include <mailutils/pop3.h>
......@@ -442,7 +446,7 @@ void print_uidl (mu_pop3_t pop3)
@}
@}
@end example
@end smallexample
@subsubsection Update State
......@@ -529,4 +533,3 @@ Errors:
@end table
@end deftypefun
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{sendmail_} is reserved */}
@code{#include <mailutils/sendmail.h>}
@end example
@end smallexample
Spawning Sendmail daemon to deliver mail. Not implemented.
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@example
@smallexample
@code{/* Prefix @emph{smtp_} is reserved */}
@code{#include <mailutils/smtp.h>}
@end example
@end smallexample
Simple Mail Transfer Protocol. Not implemented.
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@smallexample
@code{#include <mailutils/stream.h>}
@end smallexample
These generic flags are interpreted as appropriate to the specific
streams.
......@@ -54,7 +57,7 @@ Stream doesn't close it's underlying resource when it is closed or destroyed.
@end deftypefun
@deftypefun int stdio_stream_create (stream_t *@var{pstream}, FILE* @var{stdio}, int @var{flags})
If MU_STREAM_NO_CLOSE is specified, fclose() will not be called on
If @code{MU_STREAM_NO_CLOSE} is specified, @code{fclose()} will not be called on
@var{stdio} when the stream is closed.
@end deftypefun
......@@ -118,6 +121,6 @@ Last action was @code{stream_close}.
An example using @code{tcp_stream_create} to make a simple web client:
@example
@smallexample
@include http.inc
@end example
@end smallexample
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
@c Copyright (C) 1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
......@@ -8,94 +8,94 @@ A mailbox or a mailer can be described in a URL, the string will contain the
necessary information to initialize @code{mailbox_t}, or @code{mailer_t}
properly.
@subsection POP3
@subheading POP3
The POP URL scheme contains a POP server, optional port number
and the authentication mechanism. The general form is
@example
@smallexample
@url{pop://[<user>[;AUTH=<auth>]@@]<host>[:<port>]}
or
@url{pop://[<user>[:<passwd>]@@]<host>[:<port>]}
@end example
@end smallexample
If @emph{:port} is omitted the default value is 110. Different forms of
authentication can be specified with @emph{;AUTH=type}.
The special string @emph{;AUTH=*} indicates that the client will use
a default scheme base on the capability of the server.
@example
@smallexample
@url{pop://obelix@@gaulois.org}
@url{pop://asterix;AUTH=*@@france.com}
@url{pop://falbala;AUTH=+APOP@@france.com}
@url{pop://obelix;AUTH=+APOP@@village.gaulois.org:2000}
@url{pop://obelix:menhir@@village.gaulois.org:2000}
@end example
@end smallexample
For more complete information see @cite{rfc2368}.
For more complete information see @cite{RFC 2368}.
@subsection IMAP
@subheading IMAP
The IMAP URL scheme contains an IMAP server, optional port number
and the authentication mechanism. The general form is
@example
@smallexample
@url{imap://[<user>[;AUTH=<type>]]@@<host>[:port][/<mailbox>]}
or
@url{imap://[<user>[:<passwd>]]@@<host>[:port][/<mailbox>]}
@end example
@end smallexample
If @emph{:port} is omitted the default value is 220. Different forms of
authentication can be specified with @emph{;AUTH=type}.
The special string @emph{;AUTH=*} indicates that the client will use
a default scheme base on the capability of the server.
@example
@smallexample
@url{imap://obelix@@imap.gaulois.org}
@url{imap://asterix;AUTH=*@@imap.france.com}
@url{imap://asterix:potion@@imap.france.com}
@end example
@end smallexample
For more complete information see @cite{rfc2192}.
For more complete information see @cite{RFC 2192}.
@subsection File
@subheading 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.
@example
@smallexample
@url{file://path}
@url{file://var/mail/user}
@url{file://home/obelix/Mail}
@end example
@end smallexample
For MMDF, MH local mailboxes URLs are provided, but it is preferable to
use @url{file://path} and let the library figure out which one.
@example
@smallexample
@url{mmdf://path}
@url{mh://path}
@end example
@end smallexample
@subsection Mailto
@subheading Mailto
After setting a mailer, @url{mailto:} is used to tell the mailer where
and to whom the message is for.
@example
@smallexample
@url{mailto://hostname}
@end example
@end smallexample
Mailto can be used to generate short messages, for example to subscribe
to mailing lists.
@example
@smallexample
@url{mailto://bug-mailutils@@gnu.org?body=subscribe}
@url{mailto://bug-mailutils@@gnu.org?Subject=hello&body=subscribe}
@end example
@end smallexample
For more complete information see @cite{rfc2368}.
For more complete information see @cite{RFC 2368}.
@subsection URL functions
@subheading URL functions
Helper functions are provided to retrieve and set the @emph{URL} fields.
......@@ -110,10 +110,10 @@ Destroy the url and free it's resources.
@deftypefun int url_parse (url_t @var{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:
The syntax, condensed from @cite{RFC 1738}, and extended with the ;auth=
of @cite{RFC 2384} (for POP) and @cite{RFC 2192} (for IMAP) is:
@example
@smallexample
url =
scheme ":" [ "//"
......@@ -122,7 +122,7 @@ url =
host [ ":" port ]
[ ( "/" urlpath ) | ( "?" query ) ] ]
@end example
@end smallexample
This is a generalized URL syntax, and may not be exactly appropriate
for any particular scheme.
......@@ -154,13 +154,12 @@ for any particular scheme.
@end deftypefun
@deftypefun char* url_decode (const char* @var{string})
Decodes an RFC 1738 % encoded string, returning the decoded string in
allocated memory. If the string is not encoded, this degenerates to
a strdup().
Decodes an @cite{RFC 1738} % encoded string, returning the decoded string
in allocated memory. If the string is not encoded, this degenerates to
a @code{strdup()}.
@end deftypefun
@section Example
@example
@subheading Example
@smallexample
@include url-parse.inc
@end example
@end smallexample
......