Skip to content

John McEleney / mailutils

Go to a project
Toggle navigation
Toggle navigation pinning
Commit b88c148d b88c148d185d11e0bdcf876e586e309ef8ea78f2 by Sergey Poznyakoff
Options

Rewrite default mailbox format support to make sure it does not break format aut… 

…odetection. Improve the docs.

* configure.ac (MU_DEFAULT_SCHEME): New configuration variable.
* mailbox/version.c (mu_conf_opt): Include default scheme.

* examples/mimetest.c, examples/mta.c, libmu_scm/mu_scm.c: Remove
mu_path_record. Use mu_registrar_set_default_record.

* libproto/mbox/folder.c (_path_is_scheme): Rename to
_mbox_is_scheme. Minor changes as well.
(_path_record, mu_path_record): Removed.
(_mbox_record): Use _mbox_is_scheme.

* libsieve/actions.c: Remove unused variable.

* include/mailutils/Makefile.am (types.h rule): Replace
_MU_DEFAULT_RECORD_. Change MU_OFF_TYPE replacement pattern to
_MU_OFF_TYPE_.

* include/mailutils/mailbox.h (mu_mailbox_set_default_proto)
(mu_mailbox_get_default_proto): Remove. See below.
* include/mailutils/registrar.h (mu_registrar_set_default_scheme)
(mu_registrar_get_default_scheme)
(mu_registrar_get_default_record)
(mu_registrar_set_default_record)
(mu_registrar_lookup_scheme): New prototypes.
(mu_path_record): Remove.
(mu_register_all_mbox_formats): Remove mu_path_record.
Set default scheme using mu_registrar_set_default_record.
(mu_register_local_mbox_formats): Likewise.
* include/mailutils/types.hin (MU_OFF_TYPE): Rename to
_MU_OFF_TYPE_.
(MU_DEFAULT_RECORD): New define.

* mailbox/mailbox.c (mu_mailbox_set_default_proto)
(mu_mailbox_get_default_proto): Remove.
(mu_mailbox_create): Remove default_proto kludge. mu_registrar
stuff is responsible for finding the correct record.
* mailbox/registrar.c (mu_registrar_set_default_record)
(mu_registrar_get_default_record)
(mu_registrar_set_default_scheme)
(mu_registrar_get_default_scheme)
(mu_registrar_lookup_scheme): New functions.
(mu_registrar_lookup_url): Fall back to default record if no
matching record is found and the URL was not set explicitly
(i.e. does not begin with a scheme).

* mailbox/gocs.c: Use mu_registrar_set_default_scheme instead of
mu_mailbox_set_default_proto.
* libsieve/extensions/pipe.c, libsieve/extensions/spamd.c,
libsieve/extensions/vacation.c: Fix comments.

* doc/texinfo/getdate.texi: New file (from gnulib).
* doc/texinfo/Makefile.am (mailutils_TEXINFOS): Add getdate.texi
(fix-sentence-spacing): New rule. Forces single-space
inter-sentence spacing.
(check-tabs, check-sentence-spacing): New rules.
(check-format): Depend on the above two.
(check-refs, check-fixmes, check-unrevised): Fix copy-paste
errors. Print diagnostics to stderr.

* doc/texinfo/auth.texi, doc/texinfo/fdl.texi,
doc/texinfo/framework.texi, doc/texinfo/imap4.texi,
doc/texinfo/libmuauth.texi, doc/texinfo/mailbox.texi,
doc/texinfo/mailcap.texi, doc/texinfo/mailutils.texi,
doc/texinfo/mbox.texi, doc/texinfo/message.texi,
doc/texinfo/mom.texi, doc/texinfo/mu_message.texi,
doc/texinfo/mu_mime.texi, doc/texinfo/mu_scm.texi,
doc/texinfo/muint.texi, doc/texinfo/pop3.texi,
doc/texinfo/rendition.texi, doc/texinfo/sieve.texi,
doc/texinfo/url.texi, doc/texinfo/usage.texi: Use GNU instead of
@sc{gnu}, because latter looks awful when typeset (especially when
followed by a capitalized word). Fix format by running `make final'.

* doc/texinfo/programs.texi: Document more config statements.
* doc/texinfo/libsieve.texi: Document loadable actions and tests.
1 parent 8b4b2e28
Inline Side-by-side
Showing 42 changed files with 1900 additions and 576 deletions
2008-11-09 Sergey Poznyakoff <gray@gnu.org.ua>
Rewrite default mailbox format support to make sure it does not
break format autodetection. Improve the docs.
* configure.ac (MU_DEFAULT_SCHEME): New configuration variable.
* mailbox/version.c (mu_conf_opt): Include default scheme.
* examples/mimetest.c, examples/mta.c, libmu_scm/mu_scm.c: Remove
mu_path_record. Use mu_registrar_set_default_record.
* libproto/mbox/folder.c (_path_is_scheme): Rename to
_mbox_is_scheme. Minor changes as well.
(_path_record, mu_path_record): Removed.
(_mbox_record): Use _mbox_is_scheme.
* libsieve/actions.c: Remove unused variable.
* include/mailutils/Makefile.am (types.h rule): Replace
_MU_DEFAULT_RECORD_. Change MU_OFF_TYPE replacement pattern to
_MU_OFF_TYPE_.
* include/mailutils/mailbox.h (mu_mailbox_set_default_proto)
(mu_mailbox_get_default_proto): Remove. See below.
* include/mailutils/registrar.h (mu_registrar_set_default_scheme)
(mu_registrar_get_default_scheme)
(mu_registrar_get_default_record)
(mu_registrar_set_default_record)
(mu_registrar_lookup_scheme): New prototypes.
(mu_path_record): Remove.
(mu_register_all_mbox_formats): Remove mu_path_record.
Set default scheme using mu_registrar_set_default_record.
(mu_register_local_mbox_formats): Likewise.
* include/mailutils/types.hin (MU_OFF_TYPE): Rename to
_MU_OFF_TYPE_.
(MU_DEFAULT_RECORD): New define.
* mailbox/mailbox.c (mu_mailbox_set_default_proto)
(mu_mailbox_get_default_proto): Remove.
(mu_mailbox_create): Remove default_proto kludge. mu_registrar
stuff is responsible for finding the correct record.
* mailbox/registrar.c (mu_registrar_set_default_record)
(mu_registrar_get_default_record)
(mu_registrar_set_default_scheme)
(mu_registrar_get_default_scheme)
(mu_registrar_lookup_scheme): New functions.
(mu_registrar_lookup_url): Fall back to default record if no
matching record is found and the URL was not set explicitly
(i.e. does not begin with a scheme).
* mailbox/gocs.c: Use mu_registrar_set_default_scheme instead of
mu_mailbox_set_default_proto.
* libsieve/extensions/pipe.c, libsieve/extensions/spamd.c,
libsieve/extensions/vacation.c: Fix comments.
* doc/texinfo/getdate.texi: New file (from gnulib).
* doc/texinfo/Makefile.am (mailutils_TEXINFOS): Add getdate.texi
(fix-sentence-spacing): New rule. Forces single-space
inter-sentence spacing.
(check-tabs, check-sentence-spacing): New rules.
(check-format): Depend on the above two.
(check-refs, check-fixmes, check-unrevised): Fix copy-paste
errors. Print diagnostics to stderr.
* doc/texinfo/auth.texi, doc/texinfo/fdl.texi,
doc/texinfo/framework.texi, doc/texinfo/imap4.texi,
doc/texinfo/libmuauth.texi, doc/texinfo/mailbox.texi,
doc/texinfo/mailcap.texi, doc/texinfo/mailutils.texi,
doc/texinfo/mbox.texi, doc/texinfo/message.texi,
doc/texinfo/mom.texi, doc/texinfo/mu_message.texi,
doc/texinfo/mu_mime.texi, doc/texinfo/mu_scm.texi,
doc/texinfo/muint.texi, doc/texinfo/pop3.texi,
doc/texinfo/rendition.texi, doc/texinfo/sieve.texi,
doc/texinfo/url.texi, doc/texinfo/usage.texi: Use GNU instead of
@sc{gnu}, because latter looks awful when typeset (especially when
followed by a capitalized word). Fix format by running `make final'.
* doc/texinfo/programs.texi: Document more config statements.
* doc/texinfo/libsieve.texi: Document loadable actions and tests.
2008-11-07 Sergey Poznyakoff <gray@gnu.org.ua>
Bugfix
......
......@@ -1095,6 +1095,29 @@ if test "$EMACS" != "no"; then
fi
AC_SUBST(lisp_LISP)
# Default mailbox record
# Note: 1. Support for mbox type is always enabled.
# 2. Only local mailbox types are allowed for MU_DEFAULT_SCHEME
AC_ARG_VAR([MU_DEFAULT_SCHEME],
[Default mailbox record. Allowed values are: mbox (default), mh, and maildir.])
if test -z "$MU_DEFAULT_SCHEME"; then
MU_DEFAULT_SCHEME=mbox
fi
case $MU_DEFAULT_SCHEME in
mbox)
;;
mh|maildir)
eval testval=\$mu_cv_enable_$MU_DEFAULT_SCHEME
if test "$testval" != yes; then
AC_MSG_ERROR([Cannot set default mailbox record type: support for $MU_DEFAULT_SCHEME is disabled])
fi
;;
*) AC_MSG_ERROR([Unknown or not allowed mailbox scheme: $MU_DEFAULT_SCHEME]);;
esac
AC_DEFINE_UNQUOTED(MU_DEFAULT_SCHEME, "$MU_DEFAULT_SCHEME",
[Default mailbox scheme.])
AC_SUBST(MU_DEFAULT_RECORD,mu_${MU_DEFAULT_SCHEME}_record)
AC_ARG_VAR([DEFAULT_CUPS_CONFDIR],
[Set the location of CUPS configuration directory. Default is \$sysconfdir/cups])
......@@ -1134,6 +1157,7 @@ cat <<EOF
*******************************************************************
GNU Mailutils configured with the following settings:
Default mailbox scheme......... $status_scheme
Use PAM........................ $status_pam
Use -ltdl...................... $status_ltdl
Use DBM........................ $status_dbm
......@@ -1168,7 +1192,8 @@ Sendmail....................... $status_sendmail
Before proceeding, verify if these satisfy your requirements.
EOF
],
[status_pam=$status_pam
[status_scheme=$MU_DEFAULT_SCHEME
status_pam=$status_pam
status_ltdl=$status_ltdl
status_dbm="$status_dbm"
status_ldap=$status_ldap
......
......@@ -41,6 +41,7 @@ mailutils_TEXINFOS = \
fdl.texi\
folder.texi\
framework.texi\
getdate.texi\
headers.texi\
imap4.texi\
iterator.texi\
......@@ -115,40 +116,57 @@ master-menu:
untabify:
emacs -batch -l untabify.el $(info_TEXINFOS) $(mailutils_TEXINFOS)
fix-sentence-spacing:
for file in $(info_TEXINFOS) $(mailutils_TEXINFOS); \
do \
if grep -q '\. [@A-Z]' $$file; then \
mv $$file $${file}~; \
sed -r 's/\. ([@A-Z])/. \1/g' $${file}~ > $$file; \
fi; \
done
final: untabify master-menu
# Checks
check-format:
check-tabs:
@if test -n "`cat $(info_TEXINFOS) $(mailutils_TEXINFOS) |\
tr -d -c '\t'`"; then \
echo "Sources contain tabs; run make untabify"; \
echo >&2 "Sources contain tabs; run make untabify"; \
false; \
fi
check-sentence-spacing:
@if grep -q '\. [@A-Z]' $(info_TEXINFOS) $(mailutils_TEXINFOS); then \
echo >&2 "Sources contain double-space sentence separators"; \
echo >&2 "Run make fix-sentence-spacing to fix"; \
fi
check-format: check-tabs check-sentence-spacing
check-refs:
@for file in $(info_TEXINFOS) $(dico_TEXINFOS); \
@for file in $(info_TEXINFOS) $(mailutils_TEXINFOS); \
do \
sed -e = $$file | \
sed -n 'N;/@FIXME-.*ref/{s/\(^[0-9][0-9]*\).*@FIXME-.*ref{\([^}]*\)}.*/'$$file':\1: \2/gp}'; \
done > $@-t; \
if [ -s $@-t ]; then \
echo "Unresolved cross-references:"; \
cat $@-t;\
echo >&2 "Unresolved cross-references:"; \
cat $@-t >&2;\
rm $@-t; \
else \
rm -f $@-t; \
fi
check-fixmes:
@for file in $(info_TEXINFOS); \
@for file in $(info_TEXINFOS) $(mailutils_TEXINFOS); \
do \
sed -e = $$file | \
sed -n 'N;/@FIXME{/{s/\(^[0-9][0-9]*\).*@FIXME{\([^}]*\).*/'$$file':\1: \2/gp}'; \
done > $@-t; \
if [ -s $@-t ]; then \
echo "Unresolved FIXMEs:"; \
cat $@-t; \
echo >&2 "Unresolved FIXMEs:"; \
cat $@-t >&2; \
rm $@-t; \
false; \
else \
......@@ -156,10 +174,10 @@ check-fixmes:
fi
check-unrevised:
@grep -Hn @UNREVISED $(info_TEXINFOS) $(dico_TEXINFOS) > $@-t; \
@grep -Hn @UNREVISED $(info_TEXINFOS) $(mailutils_TEXINFOS) > $@-t; \
if [ -s $@-t ]; then \
echo "Unrevised nodes:"; \
cat $@-t; \
echo >&2 "Unrevised nodes:"; \
cat $@-t >&2; \
rm $@-t; \
false;\
else \
......
......@@ -10,14 +10,14 @@
@end smallexample
There are many ways to authenticate to a server. To be flexible the
There are many ways to authenticate to a server. To be flexible the
authentication process is provided by three objects @code{mu_authority_t},
@code{mu_ticket_t}, and @code{mu_wicket_t}. The @code{mu_authority_t} can implement
@code{mu_ticket_t}, and @code{mu_wicket_t}. The @code{mu_authority_t} can implement
different protocol like APOP, MD5-AUTH, One Time Passwd, etc. By default
if a mailbox does not understand or know how to authenticate it falls back
to user/passwd authentication. The @code{mu_ticket_t} is a way for
to user/passwd authentication. The @code{mu_ticket_t} is a way for
Mailboxes and Mailers provide a way to authenticate when the URL does not
contain enough information. The default action is to call the function
contain enough information. The default action is to call the function
@code{mu_authority_authenticate()} which will get the @emph{user} and @emph{passwd}
if not set, this function can be overridden by a custom method.
......
......@@ -25,16 +25,16 @@ to get credit for their work, while not being considered responsible
for modifications made by others.
This License is a kind of ``copyleft'', which means that derivative
works of the document must themselves be free in the same sense. It
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does. But this License is not limited to software manuals;
software does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License
whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
@item
......@@ -42,11 +42,11 @@ APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License. Such a notice grants a
distributed under the terms of this License. Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein. The ``Document'', below,
refers to any such manual or work. Any member of the public is a
licensee, and is addressed as ``you''. You accept the license if you
work under the conditions stated herein. The ``Document'', below,
refers to any such manual or work. Any member of the public is a
licensee, and is addressed as ``you''. You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.
......@@ -67,15 +67,15 @@ them.
The ``Invariant Sections'' are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License. If a
that says that the Document is released under this License. If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant
allowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant
Sections then there are none.
The ``Cover Texts'' are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License. A Front-Cover Text may
the Document is released under this License. A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.
A ``Transparent'' copy of the Document means a machine-readable copy,
......@@ -85,19 +85,19 @@ straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
to text formatters. A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text. A copy that is not ``Transparent'' is called ``Opaque''.
of text. A copy that is not ``Transparent'' is called ``Opaque''.
Examples of suitable formats for Transparent copies include plain
@sc{ascii} without markup, Texinfo input format, La@TeX{} input
format, @acronym{SGML} or @acronym{XML} using a publicly available
@acronym{DTD}, and standard-conforming simple @acronym{HTML},
PostScript or @acronym{PDF} designed for human modification. Examples
PostScript or @acronym{PDF} designed for human modification. Examples
of transparent image formats include @acronym{PNG}, @acronym{XCF} and
@acronym{JPG}. Opaque formats include proprietary formats that can be
@acronym{JPG}. Opaque formats include proprietary formats that can be
read and edited only by proprietary word processors, @acronym{SGML} or
@acronym{XML} for which the @acronym{DTD} and/or processing tools are
not generally available, and the machine-generated @acronym{HTML},
......@@ -106,7 +106,7 @@ output purposes only.
The ``Title Page'' means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
this License requires to appear in the title page. For works in
formats which do not have any title page as such, ``Title Page'' means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
......@@ -120,7 +120,7 @@ of such a section when you modify the Document means that it remains a
section ``Entitled XYZ'' according to this definition.
The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document. These Warranty
states that this License applies to the Document. These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
......@@ -133,10 +133,10 @@ You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License. You may not use
conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and
......@@ -150,10 +150,10 @@ printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent and
visible. You may add other material on the covers in addition.
visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
......@@ -188,14 +188,14 @@ the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it. In addition, you must do these things in the Modified Version:
of it. In addition, you must do these things in the Modified Version:
@enumerate A
@item
Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document). You may use the same title as a previous version
of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.
@item
......@@ -231,7 +231,7 @@ Include an unaltered copy of this License.
@item
Preserve the section Entitled ``History'', Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
publisher of the Modified Version as given on the Title Page. If
there is no section Entitled ``History'' in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
......@@ -241,7 +241,7 @@ Version as stated in the previous sentence.
Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the ``History'' section.
it was based on. These may be placed in the ``History'' section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
......@@ -254,11 +254,11 @@ dedications given therein.
@item
Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.
@item
Delete any section Entitled ``Endorsements''. Such a section
Delete any section Entitled ``Endorsements''. Such a section
may not be included in the Modified Version.
@item
......@@ -272,7 +272,7 @@ Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
......@@ -284,9 +284,9 @@ standard.
You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version. Only one passage of
of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document already
through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
......@@ -308,7 +308,7 @@ license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
......@@ -318,7 +318,7 @@ Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled ``History''
in the various original documents, forming one section Entitled
``History''; likewise combine any sections Entitled ``Acknowledgements'',
and any sections Entitled ``Dedications''. You must delete all
and any sections Entitled ``Dedications''. You must delete all
sections Entitled ``Endorsements.''
@item
......@@ -363,11 +363,11 @@ distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers. In case of a disagreement between
of those notices and disclaimers. In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.
......@@ -380,9 +380,9 @@ title.
TERMINATION
You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License. Any other attempt to
as expressly provided for under this License. Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License. However,
automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.
......@@ -391,9 +391,9 @@ parties remain in full compliance.
FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new
of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
differ in detail to address new problems or concerns. See
@uref{http://www.gnu.org/copyleft/}.
Each version of the License is given a distinguishing version number.
......@@ -401,7 +401,7 @@ If the Document specifies that a particular numbered version of this
License ``or any later version'' applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.
@end enumerate
......
......@@ -25,7 +25,7 @@
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
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,
......
@c GNU date syntax documentation
@c Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
@c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.2 or
@c any later version published by the Free Software Foundation; with no
@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
@c Texts. A copy of the license is included in the ``GNU Free
@c Documentation License'' file as part of this distribution.
@cindex date input formats
@findex get_date
First, a quote:
@quotation
Our units of temporal measurement, from seconds on up to months, are so
complicated, asymmetrical and disjunctive so as to make coherent mental
reckoning in time all but impossible. Indeed, had some tyrannical god
contrived to enslave our minds to time, to make it all but impossible
for us to escape subjection to sodden routines and unpleasant surprises,
he could hardly have done better than handing down our present system.
It is like a set of trapezoidal building blocks, with no vertical or
horizontal surfaces, like a language in which the simplest thought
demands ornate constructions, useless particles and lengthy
circumlocutions. Unlike the more successful patterns of language and
science, which enable us to face experience boldly or at least
level-headedly, our system of temporal calculation silently and
persistently encourages our terror of time.
@dots{} It is as though architects had to measure length in feet, width
in meters and height in ells; as though basic instruction manuals
demanded a knowledge of five different languages. It is no wonder then
that we often look into our own immediate past or future, last Tuesday
or a week from Sunday, with feelings of helpless confusion. @dots{}
--- Robert Grudin, @cite{Time and the Art of Living}.
@end quotation
This section describes the textual date representations that @sc{gnu}
programs accept. These are the strings you, as a user, can supply as
arguments to the various programs. The C interface (via the
@code{get_date} function) is not described here.
@menu
* General date syntax:: Common rules.
* Calendar date items:: 19 Dec 1994.
* Time of day items:: 9:20pm.
* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}.
* Day of week items:: Monday and others.
* Relative items in date strings:: next tuesday, 2 years ago.
* Pure numbers in date strings:: 19931219, 1440.
* Seconds since the Epoch:: @@1078100502.
* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
@end menu
@node General date syntax
@section General date syntax
@cindex general date syntax
@cindex items in date strings
A @dfn{date} is a string, possibly empty, containing many items
separated by whitespace. The whitespace may be omitted when no
ambiguity arises. The empty string means the beginning of today (i.e.,
midnight). Order of the items is immaterial. A date string may contain
many flavors of items:
@itemize @bullet
@item calendar date items
@item time of day items
@item time zone items
@item day of the week items
@item relative items
@item pure numbers.
@end itemize
@noindent We describe each of these item types in turn, below.
@cindex numbers, written-out
@cindex ordinal numbers
@findex first @r{in date strings}
@findex next @r{in date strings}
@findex last @r{in date strings}
A few ordinal numbers may be written out in words in some contexts. This is
most useful for specifying day of the week items or relative items (see
below). Among the most commonly used ordinal numbers, the word
@samp{last} stands for @math{-1}, @samp{this} stands for 0, and
@samp{first} and @samp{next} both stand for 1. Because the word
@samp{second} stands for the unit of time there is no way to write the
ordinal number 2, but for convenience @samp{third} stands for 3,
@samp{fourth} for 4, @samp{fifth} for 5,
@samp{sixth} for 6, @samp{seventh} for 7, @samp{eighth} for 8,
@samp{ninth} for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and
@samp{twelfth} for 12.
@cindex months, written-out
When a month is written this way, it is still considered to be written
numerically, instead of being ``spelled in full''; this changes the
allowed strings.
@cindex language, in dates
In the current implementation, only English is supported for words and
abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first},
@samp{January}, @samp{Sunday}, @samp{tomorrow}, and @samp{year}.
@cindex language, in dates
@cindex time zone item
The output of the @command{date} command
is not always acceptable as a date string,
not only because of the language problem, but also because there is no
standard meaning for time zone items like @samp{IST}. When using
@command{date} to generate a date string intended to be parsed later,
specify a date format that is independent of language and that does not
use time zone items other than @samp{UTC} and @samp{Z}. Here are some
ways to do this:
@example
$ LC_ALL=C TZ=UTC0 date
Mon Mar 1 00:21:42 UTC 2004
$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
2004-03-01 00:21:42Z
$ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension.
2004-02-29 16:21:42,692722128-0800
$ date --rfc-2822 # a GNU extension
Sun, 29 Feb 2004 16:21:42 -0800
$ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension.
2004-02-29 16:21:42 -0800
$ date +'@@%s.%N' # %s and %N are GNU extensions.
@@1078100502.692722128
@end example
@cindex case, ignored in dates
@cindex comments, in dates
Alphabetic case is completely ignored in dates. Comments may be introduced
between round parentheses, as long as included parentheses are properly
nested. Hyphens not followed by a digit are currently ignored. Leading
zeros on numbers are ignored.
Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are
rejected. In the typical case of a host that does not support leap
seconds, a time like @samp{23:59:60} is rejected even if it
corresponds to a valid leap second.
@node Calendar date items
@section Calendar date items
@cindex calendar date item
A @dfn{calendar date item} specifies a day of the year. It is
specified differently, depending on whether the month is specified
numerically or literally. All these strings specify the same calendar date:
@example
1972-09-24 # @sc{iso} 8601.
72-9-24 # Assume 19xx for 69 through 99,
# 20xx for 00 through 68.
72-09-24 # Leading zeros are ignored.
9/24/72 # Common U.S. writing.
24 September 1972
24 Sept 72 # September has a special abbreviation.
24 Sep 72 # Three-letter abbreviations always allowed.
Sep 24, 1972
24-sep-72
24sep72
@end example
The year can also be omitted. In this case, the last specified year is
used, or the current year if none. For example:
@example
9/24
sep 24
@end example
Here are the rules.
@cindex @sc{iso} 8601 date format
@cindex date format, @sc{iso} 8601
For numeric months, the @sc{iso} 8601 format
@samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is
any positive number, @var{month} is a number between 01 and 12, and
@var{day} is a number between 01 and 31. A leading zero must be present
if a number is less than ten. If @var{year} is 68 or smaller, then 2000
is added to it; otherwise, if @var{year} is less than 100,
then 1900 is added to it. The construct
@samp{@var{month}/@var{day}/@var{year}}, popular in the United States,
is accepted. Also @samp{@var{month}/@var{day}}, omitting the year.
@cindex month names in date strings
@cindex abbreviations for months
Literal months may be spelled out in full: @samp{January},
@samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June},
@samp{July}, @samp{August}, @samp{September}, @samp{October},
@samp{November} or @samp{December}. Literal months may be abbreviated
to their first three letters, possibly followed by an abbreviating dot.
It is also permitted to write @samp{Sept} instead of @samp{September}.
When months are written literally, the calendar date may be given as any
of the following:
@example
@var{day} @var{month} @var{year}
@var{day} @var{month}
@var{month} @var{day} @var{year}
@var{day}-@var{month}-@var{year}
@end example
Or, omitting the year:
@example
@var{month} @var{day}
@end example
@node Time of day items
@section Time of day items
@cindex time of day item
A @dfn{time of day item} in date strings specifies the time on a given
day. Here are some examples, all of which represent the same time:
@example
20:02:00.000000
20:02
8:02pm
20:02-0500 # In @sc{est} (U.S. Eastern Standard Time).
@end example
More generally, the time of day may be given as
@samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
a number between 0 and 23, @var{minute} is a number between 0 and
59, and @var{second} is a number between 0 and 59 possibly followed by
@samp{.} or @samp{,} and a fraction containing one or more digits.
Alternatively,
@samp{:@var{second}} can be omitted, in which case it is taken to
be zero. On the rare hosts that support leap seconds, @var{second}
may be 60.
@findex am @r{in date strings}
@findex pm @r{in date strings}
@findex midnight @r{in date strings}
@findex noon @r{in date strings}
If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.}
or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
@samp{:@var{minute}} may be omitted (taken to be zero). @samp{am}
indicates the first half of the day, @samp{pm} indicates the second
half of the day. In this notation, 12 is the predecessor of 1:
midnight is @samp{12am} while noon is @samp{12pm}.
(This is the zero-oriented interpretation of @samp{12am} and @samp{12pm},
as opposed to the old tradition derived from Latin
which uses @samp{12m} for noon and @samp{12pm} for midnight.)
@cindex time zone correction
@cindex minutes, time zone correction by
The time may alternatively be followed by a time zone correction,
expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+}
or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number
of zone minutes.
The zone minutes term, @var{mm}, may be omitted, in which case
the one- or two-digit correction is interpreted as a number of hours.
You can also separate @var{hh} from @var{mm} with a colon.
When a time zone correction is given this way, it
forces interpretation of the time relative to
Coordinated Universal Time (@sc{utc}), overriding any previous
specification for the time zone or the local time zone. For example,
@samp{+0530} and @samp{+05:30} both stand for the time zone 5.5 hours
ahead of @sc{utc} (e.g., India).
This is the best way to
specify a time zone correction by fractional parts of an hour.
The maximum zone correction is 24 hours.
Either @samp{am}/@samp{pm} or a time zone correction may be specified,
but not both.
@node Time zone items
@section Time zone items
@cindex time zone item
A @dfn{time zone item} specifies an international time zone, indicated
by a small set of letters, e.g., @samp{UTC} or @samp{Z}
for Coordinated Universal
Time. Any included periods are ignored. By following a
non-daylight-saving time zone by the string @samp{DST} in a separate
word (that is, separated by some white space), the corresponding
daylight saving time zone may be specified.
Alternatively, a non-daylight-saving time zone can be followed by a
time zone correction, to add the two values. This is normally done
only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to
@samp{+05:30}.
Time zone items other than @samp{UTC} and @samp{Z}
are obsolescent and are not recommended, because they
are ambiguous; for example, @samp{EST} has a different meaning in
Australia than in the United States. Instead, it's better to use
unambiguous numeric time zone corrections like @samp{-0500}, as
described in the previous section.
If neither a time zone item nor a time zone correction is supplied,
time stamps are interpreted using the rules of the default time zone
(@pxref{Specifying time zone rules}).
@node Day of week items
@section Day of week items
@cindex day of week item
The explicit mention of a day of the week will forward the date
(only if necessary) to reach that day of the week in the future.
Days of the week may be spelled out in full: @samp{Sunday},
@samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday},
@samp{Friday} or @samp{Saturday}. Days may be abbreviated to their
first three letters, optionally followed by a period. The special
abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for
@samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are
also allowed.
@findex next @var{day}
@findex last @var{day}
A number may precede a day of the week item to move forward
supplementary weeks. It is best used in expression like @samp{third
monday}. In this context, @samp{last @var{day}} or @samp{next
@var{day}} is also acceptable; they move one week before or after
the day that @var{day} by itself would represent.
A comma following a day of the week item is ignored.
@node Relative items in date strings
@section Relative items in date strings
@cindex relative items in date strings
@cindex displacement of dates
@dfn{Relative items} adjust a date (or the current date if none) forward
or backward. The effects of relative items accumulate. Here are some
examples:
@example
1 year
1 year ago
3 years
2 days
@end example
@findex year @r{in date strings}
@findex month @r{in date strings}
@findex fortnight @r{in date strings}
@findex week @r{in date strings}
@findex day @r{in date strings}
@findex hour @r{in date strings}
@findex minute @r{in date strings}
The unit of time displacement may be selected by the string @samp{year}
or @samp{month} for moving by whole years or months. These are fuzzy
units, as years and months are not all of equal duration. More precise
units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7
days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes,
@samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or
@samp{sec} worth one second. An @samp{s} suffix on these units is
accepted and ignored.
@findex ago @r{in date strings}
The unit of time may be preceded by a multiplier, given as an optionally
signed number. Unsigned numbers are taken as positively signed. No
number at all implies 1 for a multiplier. Following a relative item by
the string @samp{ago} is equivalent to preceding the unit by a
multiplier with value @math{-1}.
@findex day @r{in date strings}
@findex tomorrow @r{in date strings}
@findex yesterday @r{in date strings}
The string @samp{tomorrow} is worth one day in the future (equivalent
to @samp{day}), the string @samp{yesterday} is worth
one day in the past (equivalent to @samp{day ago}).
@findex now @r{in date strings}
@findex today @r{in date strings}
@findex this @r{in date strings}
The strings @samp{now} or @samp{today} are relative items corresponding
to zero-valued time displacement, these strings come from the fact
a zero-valued time displacement represents the current time when not
otherwise changed by previous items. They may be used to stress other
items, like in @samp{12:00 today}. The string @samp{this} also has
the meaning of a zero-valued time displacement, but is preferred in
date strings like @samp{this thursday}.
When a relative item causes the resulting date to cross a boundary
where the clocks were adjusted, typically for daylight saving time,
the resulting date and time are adjusted accordingly.
The fuzz in units can cause problems with relative items. For
example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01,
because 2003-06-31 is an invalid date. To determine the previous
month more reliably, you can ask for the month before the 15th of the
current month. For example:
@example
$ date -R
Thu, 31 Jul 2003 13:02:39 -0700
$ date --date='-1 month' +'Last month was %B?'
Last month was July?
$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
Last month was June!
@end example
Also, take care when manipulating dates around clock changes such as
daylight saving leaps. In a few cases these have added or subtracted
as much as 24 hours from the clock, so it is often wise to adopt
universal time by setting the @env{TZ} environment variable to
@samp{UTC0} before embarking on calendrical calculations.
@node Pure numbers in date strings
@section Pure numbers in date strings
@cindex pure numbers in date strings
The precise interpretation of a pure decimal number depends
on the context in the date string.
If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no
other calendar date item (@pxref{Calendar date items}) appears before it
in the date string, then @var{yyyy} is read as the year, @var{mm} as the
month number and @var{dd} as the day of the month, for the specified
calendar date.
If the decimal number is of the form @var{hh}@var{mm} and no other time
of day item appears before it in the date string, then @var{hh} is read
as the hour of the day and @var{mm} as the minute of the hour, for the
specified time of day. @var{mm} can also be omitted.
If both a calendar date and a time of day appear to the left of a number
in the date string, but no relative item, then the number overrides the
year.
@node Seconds since the Epoch
@section Seconds since the Epoch
If you precede a number with @samp{@@}, it represents an internal time
stamp as a count of seconds. The number can contain an internal
decimal point (either @samp{.} or @samp{,}); any excess precision not
supported by the internal representation is truncated toward minus
infinity. Such a number cannot be combined with any other date
item, as it specifies a complete time stamp.
@cindex beginning of time, for @acronym{POSIX}
@cindex epoch, for @acronym{POSIX}
Internally, computer times are represented as a count of seconds since
an epoch---a well-defined point of time. On @acronym{GNU} and
@acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
@samp{@@0} represents this time, @samp{@@1} represents 1970-01-01
00:00:01 @sc{utc}, and so forth. @acronym{GNU} and most other
@acronym{POSIX}-compliant systems support such times as an extension
to @acronym{POSIX}, using negative counts, so that @samp{@@-1}
represents 1969-12-31 23:59:59 @sc{utc}.
Traditional Unix systems count seconds with 32-bit two's-complement
integers and can represent times from 1901-12-13 20:45:52 through
2038-01-19 03:14:07 @sc{utc}. More modern systems use 64-bit counts
of seconds with nanosecond subcounts, and can represent all the times
in the known lifetime of the universe to a resolution of 1 nanosecond.
On most hosts, these counts ignore the presence of leap seconds.
For example, on most hosts @samp{@@915148799} represents 1998-12-31
23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
@sc{utc}, and there is no way to represent the intervening leap second
1998-12-31 23:59:60 @sc{utc}.
@node Specifying time zone rules
@section Specifying time zone rules
@vindex TZ
Normally, dates are interpreted using the rules of the current time
zone, which in turn are specified by the @env{TZ} environment
variable, or by a system default if @env{TZ} is not set. To specify a
different set of default time zone rules that apply just to one date,
start the date with a string of the form @samp{TZ="@var{rule}"}. The
two quote characters (@samp{"}) must be present in the date, and any
quotes or backslashes within @var{rule} must be escaped by a
backslash.
For example, with the @acronym{GNU} @command{date} command you can
answer the question ``What time is it in New York when a Paris clock
shows 6:30am on October 31, 2004?'' by using a date beginning with
@samp{TZ="Europe/Paris"} as shown in the following shell transcript:
@example
$ export TZ="America/New_York"
$ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
Sun Oct 31 01:30:00 EDT 2004
@end example
In this example, the @option{--date} operand begins with its own
@env{TZ} setting, so the rest of that operand is processed according
to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31
06:30} as if it were in Paris. However, since the output of the
@command{date} command is processed according to the overall time zone
rules, it uses New York time. (Paris was normally six hours ahead of
New York in 2004, but this example refers to a brief Halloween period
when the gap was five hours.)
A @env{TZ} value is a rule that typically names a location in the
@uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}.
A recent catalog of location names appears in the
@uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time
Gateway}. A few non-@acronym{GNU} hosts require a colon before a
location name in a @env{TZ} setting, e.g.,
@samp{TZ=":America/New_York"}.
The @samp{tz} database includes a wide variety of locations ranging
from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
if you are at sea and have your own private time zone, or if you are
using a non-@acronym{GNU} host that does not support the @samp{tz}
database, you may need to use a @acronym{POSIX} rule instead. Simple
@acronym{POSIX} rules like @samp{UTC0} specify a time zone without
daylight saving time; other rules can specify simple daylight saving
regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
libc, The GNU C Library}.
@node Authors of get_date
@section Authors of @code{get_date}
@cindex authors of @code{get_date}
@cindex Bellovin, Steven M.
@cindex Salz, Rich
@cindex Berets, Jim
@cindex MacKenzie, David
@cindex Meyering, Jim
@cindex Eggert, Paul
@code{get_date} was originally implemented by Steven M. Bellovin
(@email{smb@@research.att.com}) while at the University of North Carolina
at Chapel Hill. The code was later tweaked by a couple of people on
Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com})
and Jim Berets (@email{jberets@@bbn.com}) in August, 1990. Various
revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering,
Paul Eggert and others.
@cindex Pinard, F.
@cindex Berry, K.
This chapter was originally produced by Fran@,{c}ois Pinard
(@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code,
and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).
......@@ -10,8 +10,8 @@
@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
Internet Message Access Protocol - Version (4rev1). In IMAP4, the client
must be prepared to accept any responses at all times. The server responses
have three forms: status responses, server data and command continuation
request. Untagged responses, for historical reasons are also call
"unsolicited responses".
......
......@@ -9,7 +9,7 @@ the system user database. The library @file{libmuauth} extends this
functionality, allowing @file{libmailbox} functions to obtain
information about a user from several places, like @sc{sql} database,
etc. The method used is described in detail in @ref{Auth Statement,
authentication}. This chapter contains a very succinct description of
authentication}. This chapter contains a very succinct description of
the underlying library mechanism.
@menu
......
......@@ -4,7 +4,7 @@
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@code{Libsieve} is @sc{gnu} implementation of the mail filtering
@code{Libsieve} is GNU implementation of the mail filtering
language Sieve. The library is built around a @dfn{Sieve Machine} --- an
abstract computer constructed specially to handle mail filtering tasks.
This computer has two registers: program counter and numeric accumulator;
......@@ -620,7 +620,7 @@ string @var{str}.
@deftypefun {void *} mu_sieve_mrealloc (mu_sieve_machine_t @var{mach}, void *@var{ptr}, size_t @var{size})
Changes the size of the memory block pointed to by @var{ptr} to
@var{size} bytes. The contents will be unchanged to the minimum of the
@var{size} bytes. The contents will be unchanged to the minimum of the
old and new sizes; newly allocated memory will be uninitialized. If
@var{ptr} is @code{NULL}, the call is equivalent to
@code{mu_sieve_malloc(@var{mach}, @var{size})}; if @var{size} is equal to
......@@ -664,7 +664,7 @@ Dump the disassembled code of the sieve machine @var{mach}.
@subsection Writing Loadable Commands
This section contains an example of how to write external loadable
commands for @sc{gnu} libsieve.
commands for GNU libsieve.
@smallexample
@include numaddr.inc
......
......@@ -69,7 +69,7 @@ Destroys and releases resources held by @var{mbox}.
@deftypefun int mu_mailbox_open (mu_mailbox_t @var{mbox}, int @var{flag})
A connection is open, if no stream was provided, a stream
is created based on the @var{mbox} type. The @var{flag} can be OR'ed.
is created based on the @var{mbox} type. The @var{flag} can be OR'ed.
See @code{stream_create()} for @var{flag}'s description.
The return value is @code{0} on success and a code number on error conditions:
......
......@@ -12,7 +12,7 @@
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
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}:
......@@ -24,10 +24,10 @@ application/pgp; gpg < %s | metamail; needsterminal; \
@end smallexample
A mailcap file consits of a set of mailcap entries per line, lines
beginning with @samp{#} are considered comments and ignored. Long
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 @samp{\}, the multiline will be considered
a single mailcap entry. The overall format in @acronym{BNF}:
a single mailcap entry. The overall format in @acronym{BNF}:
@smallexample
@group
......
......@@ -55,11 +55,11 @@ Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below. A copy of the license
and with the Back-Cover Texts as in (a) below. A copy of the license
is included in the section entitled ``GNU Free Documentation License''.
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software. Copies published by the Free
this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development.''
@end copying
......@@ -97,6 +97,7 @@ This edition of the @cite{GNU Mailutils Manual}, last updated on
Appendices
* References:: References.
* Date Input Formats::
* Usage Vars:: Configuring Help Summary
* GNU FDL:: This manual is under the GNU Free
Documentation License.
......@@ -388,6 +389,29 @@ Preprocessor
* #include:: Include the contents of a file.
* #searchpath:: Modify the current search path.
Tests
* Built-in Tests::
* External Tests::
Actions
* Built-in Actions::
* External Actions::
Date Input Formats
* General date syntax:: Common rules.
* Calendar date items:: 19 Dec 1994.
* Time of day items:: 9:20pm.
* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}.
* Day of week items:: Monday and others.
* Relative items in date strings:: next tuesday, 2 years ago.
* Pure numbers in date strings:: 19931219, 1440.
* Seconds since the Epoch:: @@1078100502.
* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
@end detailmenu
@end menu
......@@ -395,10 +419,10 @@ Preprocessor
@chapter Introduction
GNU Mailutils contains a series of useful mail clients, servers,
and libraries. These are the primary mail utilities of the GNU system.
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. All utilities can manipulate the
and a Sieve mail filter. It also provides a POSIX `mailx' client,
and a collection of other tools. All utilities can manipulate the
mailboxes of various formats, both local, stored on the hard disk,
and remote, accessed via network protocols, such as POP3 or IMAP4.
......@@ -406,7 +430,7 @@ The GNU Mailutils libraries supply a rich set of primitives for
handling electronic mail in programs written in C, C++ or Scheme.
This software is part of the GNU Project and belongs to the Free
Software Foundation. All libraries are licensed using the GNU LGPL.
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.
......@@ -420,17 +444,17 @@ else is licensed using the GNU GPL.
@UNREVISED
@FIXME{This is more a plan on how the document should be structured,
than a description of its actual structure. However it is:}
than a description of its actual structure. However it is:}
This book addresses a wide audience of both system administrators
and users that aim to use Mailutils programs, and programmers who wish
to use Mailutils libraries in their programs. Given this audience,
to use Mailutils libraries in their programs. Given this audience,
the book is divided in three major parts.
The first part provides a detailed description of each Mailutils
utility, and advices on how to use them in various situations. This
utility, and advices on how to use them in various situations. This
part is intended for users and system administrators who are using
Mailutils programs. If you are not interested in programming using
Mailutils programs. If you are not interested in programming using
Mailutils, this is the only part you need to read.
Subsequent parts address programmers.
......@@ -447,9 +471,9 @@ reference.
@UNREVISED
This package started off to try and handle large mailbox files more
gracefully then current POP3 servers did. While it handles this task,
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
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.
......@@ -673,6 +697,10 @@ Notifications}
@end itemize
@end itemize
@node Date Input Formats
@appendix Date Input Formats
@include getdate.texi
@include usage.texi
@include fdl.texi
......
......@@ -10,7 +10,7 @@
@end smallexample
The most common mailbox format on UNIX platform is @emph{mbox}. Mbox is a
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.
@smallexample
......@@ -34,7 +34,7 @@ check to see if the format is a valid format or an empty file. The scanning
of the mailbox is done by @code{mu_mbox_scan ()}, the function, takes callback
functions called during the scanning to provide information on progress and
new messages found. The scanning will cache some of the headers fields for
speed, new fields could be add with @code{mu_mbox_add_hcache ()}. On Closing
speed, new fields could be add with @code{mu_mbox_add_hcache ()}. On Closing
the @var{mu_mbox_t}, @code{mu_mbox_close ()} will free any resources like, headers
cache, locks etc ... The messages with attributes marked deleted will only
be removed on @code{mu_mbox_expunge ()}, if there is a need to save the
......@@ -68,8 +68,8 @@ reclaim memory.
@deftypefun int mu_mbox_set_carrier (mu_mbox_t, stream_t @var{carrier});
Another type of stream can be provided, the @var{carrier}
is set in the @var{mu_mbox_t} handle. Any previous @var{carrier} stream in
the handle, will be close and destroy. Since the parsing code
is set in the @var{mu_mbox_t} handle. Any previous @var{carrier} stream in
the handle, will be close and destroy. Since the parsing code
maintain only the offsets off the message the @var{carrier} stream must be
seekable.
......@@ -80,7 +80,7 @@ seekable.
@deftypefun int mu_mbox_get_carrier (mu_mbox_t, stream_t *@var{carrier});
Return the @var{mu_mbox_t} carrier. If none was set, a new file stream will be
Return the @var{mu_mbox_t} carrier. If none was set, a new file stream will be
created.
@table @code
......@@ -91,7 +91,7 @@ created.
@deftypefun int mu_mbox_open (mu_mbox_t, const char *@var{filename}, int @var{flags})
Open carrier stream with @var{filename} and @var{flags}. The stream will be
Open carrier stream with @var{filename} and @var{flags}. The stream will be
quickly examine to see if it is a mbox format.
@table @code
......@@ -285,7 +285,7 @@ Add to the current cache for the scan, the fields in @var{array}.
@deftypefun int mu_mbox_value_hcache (mu_mbox_t, unsigned int @var{msgno}, const char *@var{field}, char *@var{buffer}, size_t @var{buflen}, size_t *@var{writen})
Get the value of @var{field} in the header cache for @var{msgno}. The
Get the value of @var{field} in the header cache for @var{msgno}. The
result is copied in a @var{buffer} of @var{buflen} and @var{writen} is set
to the number of byte put in @var{buffer}.
......@@ -329,7 +329,7 @@ NULL to get the default.
@deftypefun int mu_mbox_append_hb (mu_mbox_t, const char *@var{sep}, stream_t @var{hstream}, stream_t @var{bstream})
Append to the mailbox an rfc822 message represented by a header, @var{hstream},
and a body, @var{bstream}. The variable @var{sep} should contain a valid
and a body, @var{bstream}. The variable @var{sep} should contain a valid
"From " separator or NULL to get the default.
@table @code
......@@ -339,11 +339,11 @@ and a body, @var{bstream}. The variable @var{sep} should contain a valid
@deftypefun int mu_mbox_scan (mu_mbox_t, unsigned int @var{start}, unsigned int *@var{count})
Start scanning the mailbox for new messages. The variable @var{start} can be
a message number starting point. The result of the scanning will be in
@var{count}. The scanning will trigger the @code{mu_mbox_newmsg_cb()} callback
Start scanning the mailbox for new messages. The variable @var{start} can be
a message number starting point. The result of the scanning will be in
@var{count}. The scanning will trigger the @code{mu_mbox_newmsg_cb()} callback
for each new message and @code{mu_mbox_progress_cb ()} at different interval
to notify progression. The return values of the those callback should be
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.
......@@ -361,8 +361,8 @@ Same as @code{mu_mbox_scan ()} but does not call the callbacks.
@end deftypefun
@deftypefun int mu_mbox_set_progress_cb (mu_mbox_t, int (*@var{callback}) (int @var{percentage}, void *)), void *@var{arg})
Set the callback function for progress. The variable @var{arg} will be pass
back in the callback as the second argument. The first argument of the
Set the callback function for progress. The variable @var{arg} will be pass
back in the callback as the second argument. The first argument of the
callback represents a @var{percentage} of the scanning progress.
@table @code
......@@ -372,8 +372,8 @@ callback represents a @var{percentage} of the scanning progress.
@deftypefun int mu_mbox_set_newmsg_cb (mu_mbox_t, int (*@var{callback}) (int @var{count}, void *)), void *@var{arg})
Set the callback function for new messages. The variable @var{arg} will be
pass back in the callback as the second argument. The first argument
Set the callback function for new messages. The variable @var{arg} will be
pass back in the callback as the second argument. The first argument
is the total of messages found.
@table @code
......@@ -383,7 +383,7 @@ is the total of messages found.
@deftypefun int mu_mbox_set_error_cb (mu_mbox_t, int (*@var{callback}) (int, void *)), void *@var{arg})
Set the callback function for errors. The variable @var{arg} will be
Set the callback function for errors. The variable @var{arg} will be
pass back in the callback as the second argument.
@table @code
......
......@@ -10,7 +10,7 @@
@end smallexample
The @code{mu_message_t} object is a convenient way to manipulate messages. It
The @code{mu_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}.
@smallexample
......
......@@ -14,7 +14,7 @@ but by using structures and pointers to function, it is possible to provide
a simple framework.
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
and specific data. For example mu_object_t, is the root object and all mailutils objects
extends it:
@smallexample
......@@ -37,7 +37,7 @@ struct _mu_object
@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
or the list of function for this object. The library provides wrapper to
access the functions instead using the @var{vtable} directly.
@smallexample
......
......@@ -57,7 +57,7 @@ Returns the list of headers in the message @var{mesg}. Optional argument
@c snarfed from "mu_message.c":510
@deffn {Scheme procedure} mu-message-set-header-fields mesg list replace
Set the headers in the message @var{mesg} from @var{list}
@var{list} is a list of conses (cons HEADER VALUE). The function sets
@var{list} is a list of conses (cons HEADER VALUE). The function sets
these headers in the message @var{mesg}.
Optional parameter @var{replace} specifies whether the new header
values should replace the headers already present in the
......
@c snarfed from "mu_mime.c":95
@deffn {Scheme procedure} mu-mime-create flags mesg
Creates a new @acronym{MIME} object. Both arguments are optional.
Creates a new @acronym{MIME} object. Both arguments are optional.
@var{flags} specifies the type of the object to create (@samp{0} is a reasonable
value). @var{mesg} gives the message to create the @acronym{MIME} object from.
value). @var{mesg} gives the message to create the @acronym{MIME} object from.
@end deffn
@c snarfed from "mu_mime.c":131
......
@c snarfed from "mu_scm.c":130
@deffn {Scheme procedure} mu-register-format rest
Registers desired mailutils formats. Any number of arguments can be given.
Registers desired mailutils formats. Any number of arguments can be given.
Each argument must be one of the following strings:
@multitable @columnfractions 0.3 0.6
......
......@@ -11,7 +11,7 @@
@ifinfo
@dircategory GNU libraries
@direntry
* mailutils-int: (muint). The internals of GNU Mailutils.
* mailutils-int: (muint). The internals of GNU Mailutils.
@end direntry
@end ifinfo
......@@ -26,11 +26,11 @@ Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below. A copy of the license
and with the Back-Cover Texts as in (a) below. A copy of the license
is included in the section entitled ``GNU Free Documentation License''.
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software. Copies published by the Free
this GNU Manual, like GNU software. Copies published by the Free
Software Foundation raise funds for GNU development.''
@end copying
......@@ -51,7 +51,7 @@ Software Foundation raise funds for GNU development.''
@chapter Scope of this Document
This document describes the internals of the GNU Mailutils. It
This document describes the internals of the GNU Mailutils. It
includes description of Mailutils' architecture, algorithms and
data structures. It is intended primarily for Mailutils developers
and those who wish to participate in the development of the package.
......
......@@ -17,9 +17,9 @@
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
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,
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.
......@@ -72,16 +72,16 @@ and closes the TCP connection.
@cindex mu_pop3_t
An opaque structure @code{mu_pop3_t} is use as a handle for the session, it is allocated and initialize by
calling @code{mu_pop3_create()}. All Functions will wait for a reply from the POP3 server before returning.
calling @code{mu_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 @code{mu_pop3_set_timeout()}, the default is 2 minutes.
On the server side, there is also an idle timeout of 10 minutes before the POP3 server closes the connection,
although the @cite{RFC 1939} specifies that the minimum
default timeout to be ten minutes, many servers have shorter idle period, care should be taken to at least send a
@code{mu_pop3_noop()} between lengthy period of idle time. Once a successful connection is established with
@code{mu_pop3_noop()} between lengthy period of idle time. Once a successful connection is established with
@code{mu_pop3_connect()}, two built-ins authentications are provided @code{mu_pop3_apop ()} or
@code{mu_pop3_user()}/@code{mu_pop3_pass()}. The @code{mu_pop3_stat()} and @code{mu_pop3_list ()} functions can be use to
@code{mu_pop3_user()}/@code{mu_pop3_pass()}. The @code{mu_pop3_stat()} and @code{mu_pop3_list ()} functions can be use to
get the number and size of messages. The functions @code{mu_pop3_list_all()}, @code{mu_pop3_uidl_all ()} and
@code{mu_pop3_capa()} save the information in an @code{mu_iterator_t}. Downloading of messages is done
@code{mu_pop3_capa()} save the information in an @code{mu_iterator_t}. Downloading of messages is done
via a two methods @code{mu_pop3_retr()} or @code{mu_pop3_top()};
@strong{Caution: Some Internet Service Providers do not permit to leave mail on server and the message will be
deleted once downloaded}.
......@@ -91,7 +91,7 @@ all the functions will return @code{EINPROGRESS} if an other operation is in pro
@subsubsection Callbacks
The POP3 library does not provide any callbacks, the approach is to leave flow control and policy outside of the
library. The functions do minimal state checking, for example when sending RETR with @code{mu_pop3_retr()}
library. The functions do minimal state checking, for example when sending RETR with @code{mu_pop3_retr()}
it is the responsibility of the user to go through the entire buffer of the stream to terminate the RETR command,
any other operation will fail, while the RETR is in progress.
To reset the state or break the downloading, the user should disconnect @code{mu_pop3_disconnect()} and reconnect
......@@ -136,7 +136,7 @@ When a POP3 session is finished, any data use by the library is release.
@deftypefun int mu_pop3_connect (mu_pop3_t @var{pop3})
A connection is established on the carrier, if there was any previous connection it is close first. If non-blocking the
A connection is established on the carrier, if there was any previous connection it is close first. If non-blocking the
function should be recall until the return value is not EAGAIN or EINPROGRESS.
Errors:
......@@ -191,8 +191,8 @@ Errors:
@deftypefun int mu_pop3_apop (mu_pop3_t @var{pop3}, const char *@var{user}, const char *@var{secret})
APOP offers an alternative to USER/PASS authentication. For intermittent use of POP3, like checking for new mail, it is the
preferred way to authenticate. It reduces the risk of password capture. The @var{user} and the shared @var{secret} are pass
APOP offers an alternative to USER/PASS authentication. For intermittent use of POP3, like checking for new mail, it is the
preferred way to authenticate. It reduces the risk of password capture. The @var{user} and the shared @var{secret} are pass
to @code{mu_pop3_apop()}, the MD5 digest is calculated by applying the time-stamp given by the server in the greeting
followed by the @var{secret}.
......@@ -331,7 +331,7 @@ print_message (mu_pop3_t pop3, unsigned int msgno)
@deftypefun int mu_pop3_top (mu_pop3_t @var{pop3}, unsigned int @var{msgno}, unsigned int @var{lines}, mu_stream_t *@var{stream})
If successful @code{stream} should be call to download the header, byte-stuff lines or handle internally, CRLFs are
converted to LF. All other operations will failed until the operation is completed by the caller.
converted to LF. All other operations will failed until the operation is completed by the caller.
Errors:
@table @code
......@@ -410,7 +410,7 @@ Errors:
@deftypefun int mu_pop3_uidl_all (mu_pop3_t @var{pop3}, mu_iterator_t *@var{iterator})
A UIDL command is executed. The call should iterate through the @code{iterator} to fetch the response.
A UIDL command is executed. The call should iterate through the @code{iterator} to fetch the response.
Errors:
@table @code
......@@ -517,7 +517,7 @@ Errors:
@deftypefun int mu_pop3_set_timeout (mu_pop3_t @var{pop3}, int @var{timeout})
Set the timeout time for I/O on the carrier. The default is 10 minutes. The @var{timeout} is given in milliseconds.
Set the timeout time for I/O on the carrier. The default is 10 minutes. The @var{timeout} is given in milliseconds.
Errors:
@table @code
......
......@@ -5,12 +5,12 @@
@comment *******************************************************************
GNU Mailutils provides a broad set of utilities for handling
electronic mail. These utilities address the needs of both system
electronic mail. These utilities address the needs of both system
adminsitrators and users.
All utilities are built around a single core subsistem and share many
common aspects. All of them are able to work with almost any existing
mailbox formats. They use a common configuration file syntax, and
common aspects. All of them are able to work with almost any existing
mailbox formats. They use a common configuration file syntax, and
their configuration files are located in a single subdirectory.
In this chapter we will discuss each utility, and give some advices on
......@@ -59,7 +59,7 @@ syntax.
@subsection Basic Notions About Command Line Options
Many command line options have two forms, called short and long
forms. Both forms are absolutely identical in function; they are
forms. Both forms are absolutely identical in function; they are
interchangeable.
The @dfn{short} form is a traditional form for UNIX utilities.
......@@ -68,45 +68,45 @@ single letter, e.g. @option{-c}.
Short options which require arguments take their arguments
immediately following the option letter, optionally separated by white
space. For example, you might write @option{-f name}, or @option{-fname}.
space. For example, you might write @option{-f name}, or @option{-fname}.
Here, @option{-f} is the option, and @option{name} is its argument.
Short options which allow optional arguments take their arguments
immediately following the option letter, @emph{without any intervening
white space characters}. This is important, so that the command line
white space characters}. This is important, so that the command line
parser might discern that the text following option is its argument,
not the next command line parameter. For example, if option @option{-d}
not the next command line parameter. For example, if option @option{-d}
took an optional argument, then @option{-dname} would mean the option
with its argument (@option{name} in this case), and @option{-d name} would
mean the @option{-d} option without any argument, followed by command
line argument @option{name}.
Short options' letters may be clumped together, but you are not
required to do this. When short options are clumped as a set, use one
required to do this. When short options are clumped as a set, use one
(single) dash for them all, e.g. @option{-cvl} is equivalent to @option{-c
-v -l}. However, only options that do not take arguments may be
clustered this way. If an option takes an argument, it can only be
-v -l}. However, only options that do not take arguments may be
clustered this way. If an option takes an argument, it can only be
the last option in such a cluster, otherwise it would be impossible to
specify the argument for it. Anyway, it is much more readable to
specify the argument for it. Anyway, it is much more readable to
specify such options separated.
The @dfn{long} option names are probably easier to memorize than
their short counterparts. They consist of two dashes, followed by a
their short counterparts. They consist of two dashes, followed by a
multi-letter option name, which is usually selected to be a mnemonics
for the operation it requests. For example, @option{--verbose} is a
long option that increases the verbosity of a utility. In addition,
for the operation it requests. For example, @option{--verbose} is a
long option that increases the verbosity of a utility. In addition,
long option names can abbreviated, provided that such an abbreviation
is unique among the options understood by a given utility. For
is unique among the options understood by a given utility. For
example, if a utility takes options @option{--foreground} and
@option{--forward}, then the shortest possible abbreviations for these
options are @option{--fore} and @option{--forw}, correspondingly. If
options are @option{--fore} and @option{--forw}, correspondingly. If
you try to use @option{--for}, the utility will abort and inform you
that the abbreviation you use is ambiguous, so it is not clear which
of the options you intended to use.
Long options which require arguments take those arguments following
the option name. There are two ways of specifying a mandatory
argument. It can be separated from the option name either by an equal
the option name. There are two ways of specifying a mandatory
argument. It can be separated from the option name either by an equal
sign, or by any amount of white space characters. For example, if the
@option{--file} option requires an argument, and you wish to supply
@file{name} as its argument, then you can do so using any of the
......@@ -127,8 +127,8 @@ equal sign.
Display a short summary of the command line options understood by
this utilities, along with a terse description of each.
The output of this option consists of three major parts. First, a
usage synopsis is displayed. For example:
The output of this option consists of three major parts. First, a
usage synopsis is displayed. For example:
@smallexample
@group
......@@ -139,10 +139,10 @@ GNU sieve -- a mail filtering tool
The first line tells that the @command{sieve} utility takes any
number of options (brackets indicate optional part) and a single
mandatory argument (@samp{SCRIPT}). The second lines summarizes the
mandatory argument (@samp{SCRIPT}). The second lines summarizes the
purpose of the utility.
Following this header is an option summary. It consists of two
Following this header is an option summary. It consists of two
columns:
@verbatim
......@@ -153,10 +153,10 @@ columns:
The leftmost column contains a comma-separated list of option
names. Short options are listed first. The options are ordered
alphabetically. Arguments, if any, are specified after the last
names. Short options are listed first. The options are ordered
alphabetically. Arguments, if any, are specified after the last
option name in the list, so that, e.g. the option @samp{-e} in the
example above requires an argument: @samp{-e ADDRESS}. Optional
example above requires an argument: @samp{-e ADDRESS}. Optional
arguments are enclosed in square brackets, as in @option{--debug}
option in the example above.
......@@ -168,9 +168,9 @@ notices and lists the email address for reporting bugs.
@xopindex{usage, described}
@item --usage
Display a short summary of options. In the contrast to the
Display a short summary of options. In the contrast to the
@option{--help} option, only option names and arguments
are printed, without any textual description. For example:
are printed, without any textual description. For example:
@smallexample
@group
......@@ -181,7 +181,7 @@ Usage: sieve [-cv?V] [--compile-only] [--debug[=FLAGS]]
@end table
The exact formatting of the output produced by these two options is
configurable. @xref{Usage Vars}, for a detailed descriptions of it.
configurable. @xref{Usage Vars}, for a detailed descriptions of it.
@table @option
@xopindex{version, described}
......@@ -191,15 +191,15 @@ Print program version and exit.
@xopindex{show-config-options, described}
@item --show-config-options
Show configuration options used when compiling the package. You can
Show configuration options used when compiling the package. You can
use this option to verify if support for a particular mailbox format
or other functionality is compiled in the binary. The output of this
or other functionality is compiled in the binary. The output of this
option is intended to be both machine-readable and understandable by
humans.
@end table
The following command line options affect parsing of configuration
files. Here we provide a short summary, the next section will
files. Here we provide a short summary, the next section will
describe them in detail.
@table @option
......@@ -235,7 +235,7 @@ Do not load user configuration file.
@UNREVISED
Configuration files are the principal means of configuring any GNU
Mailutil component. When started, each utility tries to load its
Mailutil component. When started, each utility tries to load its
configuration from the following locations, in that order:
@enumerate 1
......@@ -267,7 +267,7 @@ command line option was given.
A per user configuration file is located in the user home directory
and is named @samp{.@var{prog}}, where @var{prog} is the name of the
utility. For example, the per-user configuration file for
utility. For example, the per-user configuration file for
@command{sieve} utility is named @file{.sieve}.
@xopindex{no-user-config, described}
......@@ -280,7 +280,7 @@ command line option was given.
@end enumerate
The order in which configuration files are loaded defines the
precedence of their settings. Thus, the settings from additional
precedence of their settings. Thus, the settings from additional
configuration file override those set in per-user configuration file.
The latter, in their turn, take precedence over the settings from the
site-wide configuration file.
......@@ -290,7 +290,7 @@ Neither site-wide nor user configuration files are required to
exist. If any or both of them are absent, GNU Mailutils does not
complain, and the utility falls back to its default settings. To make
configuration processing more verbose, use the
@option{--config-verbose} command line option. Here is an example of
@option{--config-verbose} command line option. Here is an example of
what you might get using this option:
@smallexample
......@@ -299,7 +299,7 @@ imap4d: Info: finished parsing file `/etc/mailutils.rc'
@end smallexample
Specifying this option more than once adds more verbosity to this
output. If this option is given two times, GNU Mailutils will print
output. If this option is given two times, GNU Mailutils will print
any configuration file statement it parsed, along with the exact
location where it occurred (the exact meaning of each statement will
be described later in this chapter):
......@@ -321,17 +321,17 @@ imap4d: Info: parsing file `/etc/mailutils.d/imap4d'
@xopindex{config-lint, described}
To test configuration file without actually starting the utility,
use the @option{--config-lint} command line option. With this option,
use the @option{--config-lint} command line option. With this option,
any Mailutils utility exits after finishing parsing of the
configuration files. Any errors occurred during parsing are displayed
on the standard error output. This option can be combined with
configuration files. Any errors occurred during parsing are displayed
on the standard error output. This option can be combined with
@option{--config-verbose} to obtain more detailed output.
@xopindex{config-help, described}
The @option{--config-help} command line option produces on the
standard output the summary of all configuration statements understood
by the utility, with detailed comments and in the form suitable for
configuration file. For example, the simplest way to write a
configuration file. For example, the simplest way to write a
configuration file for, say, @command{imap4d} is to run
@smallexample
......@@ -364,9 +364,9 @@ and to edit the @file{imap4d.rc} file with your editor of choice.
@node conf-syntax
@subsection Configuration File Syntax
@UNREVISED
Configuration files consist of a series of statements. Blanks,
Configuration files consist of a series of statements. Blanks,
tabs, newlines and comments, collectively called @dfn{white space} are
ignored except as they serve to separate tokens. Some white space is
ignored except as they serve to separate tokens. Some white space is
required to separate otherwise adjacent keywords and values.
@menu
......@@ -381,8 +381,8 @@ required to separate otherwise adjacent keywords and values.
@cindex comments, single-line
@cindex single-line comments
@dfn{Comments} may appear anywhere where white space may appear in the
configuration file. There are two kinds of comments:
single-line and multi-line comments. @dfn{Single-line} comments start
configuration file. There are two kinds of comments:
single-line and multi-line comments. @dfn{Single-line} comments start
with @samp{#} or @samp{//} and continue to the end of the line:
@smallexample
......@@ -396,7 +396,7 @@ with @samp{#} or @samp{//} and continue to the end of the line:
characters @samp{/*} (slash, star) and continue until the first
occurrence of @samp{*/} (star, slash).
Multi-line comments cannot be nested. However, single-line comments
Multi-line comments cannot be nested. However, single-line comments
are allowed to appear within a multi-line one.
@node Statements
......@@ -406,7 +406,7 @@ are allowed to appear within a multi-line one.
@cindex statement, simple
@cindex simple statements
A @dfn{simple statement}, consists of a keyword and value
separated by any amount of whitespace. Simple statement is terminated
separated by any amount of whitespace. Simple statement is terminated
with a semicolon (@samp{;}), unless it contains a @dfn{here-document}
(see below), in which case semicolon is optional.
......@@ -445,7 +445,7 @@ following characters: @samp{_}, @samp{-}, @samp{.}, @samp{/},
@cindex string, quoted
@cindex escape sequence
A quoted string is any sequence of characters enclosed in
double-quotes (@samp{"}). A backslash appearing within a quoted
double-quotes (@samp{"}). A backslash appearing within a quoted
string introduces an @dfn{escape sequence}, which is replaced
with a single character according to the following rules:
......@@ -465,7 +465,7 @@ with a single character according to the following rules:
@end float
In addition, the sequence @samp{\@var{newline}} is removed from
the string. This allows to split long strings over several
the string. This allows to split long strings over several
physical lines, e.g.:
@smallexample
......@@ -480,7 +480,7 @@ above, the backslash is ignored and a warning is issued.
Two or more adjacent quoted strings are concatenated, which gives
another way to split long strings over several lines to improve
readability. The following fragment produces the same result as the
readability. The following fragment produces the same result as the
example above:
@smallexample
......@@ -498,8 +498,8 @@ strings of text containing embedded newlines.
The @code{<<@var{word}} construct instructs the parser to read all
the lines that follow up to the line containing only @var{word}, with
possible trailing blanks. Any lines thus read are concatenated
together into a single string. For example:
possible trailing blanks. Any lines thus read are concatenated
together into a single string. For example:
@smallexample
@group
......@@ -517,9 +517,9 @@ the text is read as is, without interpretation of escape sequences.
If @var{word} is prefixed with @code{-} (a dash), then all leading
tab characters are stripped from input lines and the line containing
@var{word}. Furthermore, if @code{-} is followed by a single space,
all leading whitespace is stripped from them. This allows to indent
here-documents in a natural fashion. For example:
@var{word}. Furthermore, if @code{-} is followed by a single space,
all leading whitespace is stripped from them. This allows to indent
here-documents in a natural fashion. For example:
@smallexample
@group
......@@ -531,8 +531,8 @@ TEXT
@end smallexample
It is important that the terminating delimiter be the only token on
its line. The only exception to this rule is allowed if a
here-document appears as the last element of a statement. In this
its line. The only exception to this rule is allowed if a
here-document appears as the last element of a statement. In this
case a semicolon can be placed on the same line with its terminating
delimiter, as in:
......@@ -547,8 +547,8 @@ EOT;
@anchor{list values}
@item list
@cindex list
A @dfn{list} is a comma-separated list of values. Lists are
enclosed in parentheses. The following example shows a statement
A @dfn{list} is a comma-separated list of values. Lists are
enclosed in parentheses. The following example shows a statement
whose value is a list of strings:
@smallexample
......@@ -557,7 +557,7 @@ shared-namespace ("/home", "/var/spool/common");
In any case where a list is appropriate, a single value is allowed
without being a member of a list: it is equivalent to a list with a
single member. This means that, e.g. @samp{shared-namespace /home;} is
single member. This means that, e.g. @samp{shared-namespace /home;} is
equivalent to @samp{shared-namespace (/home);}.
@end table
......@@ -565,7 +565,7 @@ equivalent to @samp{shared-namespace (/home);}.
@subsubsection Block Statements
@cindex block statement, configuration file
A @dfn{block statement} introduces a logical group of another
statements. It consists of a keyword, followed by an optional value,
statements. It consists of a keyword, followed by an optional value,
and a sequence of statements enclosed in curly braces, as shown in
example below:
......@@ -587,14 +587,14 @@ this is not required.
@cindex include statement, configuration file
@kwindex include
An @dfn{include statement} is a special statement that causes
inclusion of a named file. This statement has the following syntax:
inclusion of a named file. This statement has the following syntax:
@smallexample
include @var{file};
@end smallexample
If @var{file} names a regular file, the contents of this file is
included in this point. Otherwise, if @var{file} names a directory,
included in this point. Otherwise, if @var{file} names a directory,
Mailutils searches in that directory for a file whose name coincides
with the name of utility being executed, and includes this file, if it
exists.
......@@ -607,7 +607,7 @@ include /etc/mailutils.d;
@end smallexample
This allows each particular utility to have its own configuration
file. Thus. @command{imap4d} will read
file. Thus. @command{imap4d} will read
@file{/etc/mailutils.d/imap4d}, etc.
@node Logging Statement
......@@ -625,7 +625,7 @@ logging @{
@subheading Description
The @code{logging} block statement provides configuration for
programs that use @command{syslog} for diagnostics. The default
programs that use @command{syslog} for diagnostics. The default
syslog facility is determined at compile time, it can be inspected
using the following command:
......@@ -635,14 +635,14 @@ $ mailutils-config --info log_facility
@anchor{syslog facility}
@deffn {Configuration} facility name
Use syslog facility @var{name}. Valid argument values are: @samp{user},
Use syslog facility @var{name}. Valid argument values are: @samp{user},
@samp{daemon}, @samp{auth}, @samp{authpriv}, @samp{mail}, @samp{cron},
@samp{local0} through @samp{local7} (all names case-insensitive), or
a facility number.
@end deffn
@deffn {Configuration} tag text
Tag syslog messages with @var{text}. By default, program name is used
Tag syslog messages with @var{text}. By default, program name is used
as syslog tag.
@end deffn
......@@ -660,17 +660,17 @@ debug @{
@end smallexample
@subheading Description
The @code{debug} statement configures debugging output. Although it
The @code{debug} statement configures debugging output. Although it
is mostly useful for Mailutils developers, it may be of interest for
casual users as well. In particular, you may use it to obtain more
casual users as well. In particular, you may use it to obtain more
information about Mailutils actions, which may help in configuring it,
or in filling a bug report.
Debugging output is controlled by a set of levels, each of which can be
enabled or disabled independently of others. A @dfn{debugging
enabled or disabled independently of others. A @dfn{debugging
level} consists of a module name, which defines a Mailutils module
affected by this level, and a level number, which defines the
verbosity of the debugging output. Valid debugging levels are:
verbosity of the debugging output. Valid debugging levels are:
@float Table, debugging levels
@caption{Debugging levels}
......@@ -694,7 +694,7 @@ The most important debugging modules are:
Debug access control lists. @FIXME-xref{Debugging ACLs}.
@item config
Debug configuration parser and/or lexical analizer. The following
Debug configuration parser and/or lexical analizer. The following
levels are supported:
@table @asis
......@@ -709,9 +709,9 @@ Trace execution of the configuration parser.
@end table
Due to its specific nature, this debugging module cannot be enabled
using @code{level} statement below. The @option{--debug-level}
using @code{level} statement below. The @option{--debug-level}
command line option should be used instead
(@FIXME-pxref{debug-level}). Alternatively, you may use the following
(@FIXME-pxref{debug-level}). Alternatively, you may use the following
hook, provided to facilitate debugging of the configuration parser: a
@dfn{pragmatic comment} in form:
......@@ -723,29 +723,29 @@ is understood as a request to set debugging level of module
@samp{config} to @var{level}.
@item ip_server
IP based servers, such as @command{imap4d} and @command{pop3d}. This
module supports @samp{trace0} and @samp{error} levels. @xref{Server
IP based servers, such as @command{imap4d} and @command{pop3d}. This
module supports @samp{trace0} and @samp{error} levels. @xref{Server
Settings}, for more information about servers.
@item udp_server
UDP based servers, such as @command{comsatd}. This module supports
@samp{trace0} and @samp{error} levels. @xref{Server Settings}, for
UDP based servers, such as @command{comsatd}. This module supports
@samp{trace0} and @samp{error} levels. @xref{Server Settings}, for
more information about servers.
@item mailbox
Operations over mailboxes. This module supports the following levels:
@samp{error}, @samp{trace0}, @samp{trace1}, and @samp{proto}. The
Operations over mailboxes. This module supports the following levels:
@samp{error}, @samp{trace0}, @samp{trace1}, and @samp{proto}. The
latter is used by remote mailbox support libraries.
@item sieve
Debug Sieve parser and run-time evaluator. Currently supported levels
Debug Sieve parser and run-time evaluator. Currently supported levels
are @samp{error}, @samp{trace1} and @samp{trace7}.
@end table
@deffn {Configuration} level spec
This statement enables debugging levels given by @var{spec}. The
This statement enables debugging levels given by @var{spec}. The
argument is an list of debugging specifications or a string with
specifications delimited by semicolons. The syntax of a specification
specifications delimited by semicolons. The syntax of a specification
is:
@smallexample
......@@ -754,23 +754,23 @@ is:
@noindent
where @var{module} is the name of a module, and @var{level} is the
level to be set. The level may be optionally prefixed with the
level to be set. The level may be optionally prefixed with the
following symbols:
@table @samp
@item !
All levels except this one. E.g. @samp{config=!trace7} means
All levels except this one. E.g. @samp{config=!trace7} means
set all debugging levels, except @samp{trace7} for the @samp{config}
module.
@item <
All levels up to and including this. The words @samp{up to} refer to
All levels up to and including this. The words @samp{up to} refer to
the position of levels in @ref{debugging levels} table, so that, e.g.
@samp{<trace2} means levels @samp{error}, @samp{trace0}, @samp{trace1}
and @samp{trace2}.
@end table
Both prefixes can be used together, in this order: @samp{!<}. This
Both prefixes can be used together, in this order: @samp{!<}. This
means all levels except this one and ones listed before it in
the table.
......@@ -832,7 +832,7 @@ The mailbox location can be specified using @code{mail-spool} or
@deffn {Configuration} mail-spool @var{path}
The @code{mail-spool} statement specifies directory that holds user
mailboxes. Once this statement is given, the @command{libmailutils}
mailboxes. Once this statement is given, the @command{libmailutils}
library will assume that the mailbox of user @var{login} is kept in
file @file{@var{path}/@var{login}}.
......@@ -843,12 +843,12 @@ favor of @code{mailbox-pattern} statement.
@deffn {Configuration} mailbox-pattern @var{pattern}
The @code{mailbox-pattern} statement is a modern way of configuring
mailbox locations. It superceeds @code{mail-spool} statement.
mailbox locations. It superceeds @code{mail-spool} statement.
The @var{pattern} is valid @dfn{mailbox URL}, which
may contain references to @samp{user} macro-variable
(@FIXME-pxref{macro-variables}). This macro-variable will be expanded
to the actual user name. The full syntax for @var{pattern} is:
(@FIXME-pxref{macro-variables}). This macro-variable will be expanded
to the actual user name. The full syntax for @var{pattern} is:
@smallexample
[@var{type}://]@var{path}[;@var{args}]
......@@ -859,8 +859,8 @@ where:
@table @var
@item type
Specifies the mailbox type. It must be one of mailbox types,
supported by Mailutils. @FIXME-xref{Mailbox URLs}. By default,
Specifies the mailbox type. It must be one of mailbox types,
supported by Mailutils. @FIXME-xref{Mailbox URLs}. By default,
@samp{local} is assumed. @FIXME{Verify this}.
@item path
......@@ -876,9 +876,9 @@ mailboxes, which allowes for faster access in case of very large
number of users.
By default, all user mailboxes are stored in a single directory and
are named after user login names. To find the mailbox for a given
are named after user login names. To find the mailbox for a given
user, the system scans the directory for the corresponding
file. This usually implies linear search, so the time needed to
file. This usually implies linear search, so the time needed to
locate a mailbox is directly proportional to the ordinal number of
the mailbox in the directory.
......@@ -888,7 +888,7 @@ GNU Mailutils supports three types of indexed directories:
@cindex direct indexing
@cindex indexing, direct
In direct indexed directory structure, @var{path} contains 26 subdirectories
named with lower-case letters of Latin alphabet. The location of the
named with lower-case letters of Latin alphabet. The location of the
user mailbox is determined using the following algorithm:
@enumerate 1
......@@ -902,7 +902,7 @@ For example, using this algorithm, the mailbox of the user
@samp{smith} is stored in file @file{@var{path}/s/smith}.
If each of single-letter subirectories contains the
indexed directory structure, we have second level of indexing. In
indexed directory structure, we have second level of indexing. In
this case the file name of @samp{smith}'s mailbox is
@file{@var{path}/s/m/smith}.
......@@ -910,7 +910,7 @@ this case the file name of @samp{smith}'s mailbox is
@cindex indexing, reverse
The @dfn{reverse} indexed structure uses the same principles, but the
indexing letters are taken from the @emph{end} of the user name,
instead of from the beginning. For example, in the 2nd level reverse
instead of from the beginning. For example, in the 2nd level reverse
indexed structure, the @samp{smith}'s mailbix is located in
@file{@var{path}/h/t/smith}.
......@@ -918,9 +918,9 @@ indexed structure, the @samp{smith}'s mailbix is located in
@cindex indexing, hashed
Finally, the @dfn{hashed} structure consists of 256 subdirectories
under @var{path}, named by 2-letter hex codes from @samp{00} to
@samp{FF}. Mailboxes are stored in these subdirectories. The name
@samp{FF}. Mailboxes are stored in these subdirectories. The name
of the subdirectory is computed by hashing first @var{level} letters
of the user name. The hashing alorithm is:
of the user name. The hashing alorithm is:
@enumerate 1
@item Take next letter from the user name
......@@ -946,7 +946,7 @@ Specifies indexing level.
@kwindex user
@item user=@var{string}
Specifies indexing key. The only meaningful value, as of Mailutils
Specifies indexing key. The only meaningful value, as of Mailutils
version @value{VERSION} is @samp{user=$@{user@}}.
@end table
......@@ -989,23 +989,22 @@ separator, and the user name.
The built-in mail spool directory name is determined at compile
time, using @samp{_PATH_MAILDIR} define from the include file
@file{paths.h}. If this value is not defined, @file{/var/mail} or
@file{paths.h}. If this value is not defined, @file{/var/mail} or
@file{/usr/spool/mail} is used.
@end enumerate
@deffn {Configuration} mailbox-type @var{type}
Specifies type of mailboxes. By default, @samp{mbox} (UNIX mailbox)
is assumed.
Notice that, in Mailutils version @value{VERSION}, using this
statement effectively disables mailbox type autodetection. @FIXME{More
info on this.}
@vrindex MU_DEFAULT_SCHEME
Specifies type of mailboxes. By default, @samp{mbox} (UNIX mailbox)
is assumed. This can be changed while configuring the package by
setting @code{MU_DEFAULT_SCHEME} configuration variable. The default
value can be verified by running @command{mailutils-config --info scheme}.
@end deffn
@deffn {Configuration} folder @var{dir}
@cindex plus expansion
Sets user mail folder directory. Its value is using when expanding
@samp{plus-notation}, i.e. such mailbox names as @file{+inbox}. The
Sets user mail folder directory. Its value is using when expanding
@samp{plus-notation}, i.e. such mailbox names as @file{+inbox}. The
@samp{+} sign is replaced by @var{dir}, followed by a directory
separator (@samp{/}).
......@@ -1039,26 +1038,26 @@ This block statement configures various parameters used when locking
UNIX mailboxes in order to prevent simultaneous writes.
It is important to note, that locking applies only to maildrops in
UNIX mailbox format. All other mailbox types do not require locking.
UNIX mailbox format. All other mailbox types do not require locking.
@deffn {Configuration} flags @var{string}
Set locking flags. Argument is a string consisting of one or more of
Set locking flags. Argument is a string consisting of one or more of
the following letters:
@table @asis
@item E
Use an external program to manage locks. The program is given by
Use an external program to manage locks. The program is given by
@code{external-locker} statement (see below).
@item R
If the locking attempt failed, retry it. This is the default. The
If the locking attempt failed, retry it. This is the default. The
number of retries, and time interval between the two successive
attempts is given by @code{retry-count} and @code{retry-timeout}
statements, correspondingly.
@item T
If a lock file exists, check its modification time and, if it is
older than a predefined amount of time, remove the lock. The amount
older than a predefined amount of time, remove the lock. The amount
of time is specified by @code{expire-timeout} statement.
@item P
......@@ -1067,22 +1066,22 @@ Store the PID of the locking process in a lock file.
@end deffn
@deffn {Configuration} retry-count @var{number}
Number of locking attemtps. The @samp{P} flag must be set for this to
Number of locking attemtps. The @samp{P} flag must be set for this to
take effect.
@end deffn
@deffn {Configuration} retry-timeout @var{seconds}
Time interval, in seconds, between the two successive locking
attempts. The @samp{P} flag must be set for this to take effect.
attempts. The @samp{P} flag must be set for this to take effect.
@end deffn
@deffn {Configuration} expire-timeout @var{seconds}
Remove existing lock file, if it is created more than this number of
seconds ago. The @samp{T} flag must be set for this to take effect.
seconds ago. The @samp{T} flag must be set for this to take effect.
@end deffn
@deffn {Configuration} external-locker @var{string}
Set command line of an external locker program. The @samp{E} flag
Set command line of an external locker program. The @samp{E} flag
must be set for this to take effect.
@end deffn
......@@ -1111,16 +1110,16 @@ acl @{
The ACL statement defines an @dfn{Access Control List}, a special
structure that controls who can access the given Mailutils resource.
The @code{acl} block contains a list of access controls. Each control
The @code{acl} block contains a list of access controls. Each control
can be regarded as a function that returns a tree-state value:
@samp{True}, @samp{False} and @samp{Don't know}. When a
@samp{True}, @samp{False} and @samp{Don't know}. When a
remote party connects to the server, each of controls is tried in
turn. If a control returns @samp{False}, access is denied. If it
retruns @samp{True}, access is allowed. If it returns @samp{Don't
know}, then the next control is tried. It is unclear whether to allow
access if the last control in list returned @samp{Don't know}. GNU
turn. If a control returns @samp{False}, access is denied. If it
retruns @samp{True}, access is allowed. If it returns @samp{Don't
know}, then the next control is tried. It is unclear whether to allow
access if the last control in list returned @samp{Don't know}. GNU
Mailutils @value{VERSION} issues a warning message and allows access.
This default may change in future versions. Users are advised to
This default may change in future versions. Users are advised to
write their ACLs so that the last control returns a definitive answer
(either @code{True} or @code{False}).
......@@ -1149,17 +1148,17 @@ Deny connections from IP addresses matching this @var{cidr} block.
@deffn {Configuration} ifexec [from] @var{cidr} @var{program}
When a connection from the @var{cidr} block is requested, execute
the program @var{program}. If its exit code is @samp{0}, then allow
connection. Otherwise, deny it.
the program @var{program}. If its exit code is @samp{0}, then allow
connection. Otherwise, deny it.
@end deffn
The following two controls are provided for logging purposes and as a
means of extensions. They always return a @samp{Don't know} answer,
means of extensions. They always return a @samp{Don't know} answer,
and therefore should not be used at the end of an ACL:
@deffn {Configuration} log [from] @var{cidr} [@var{string}]
Log connections from addresses in this @var{cidr}. The
@code{MU_DIAG_INFO} channel is used. If the logging goes to syslog,
Log connections from addresses in this @var{cidr}. The
@code{MU_DIAG_INFO} channel is used. If the logging goes to syslog,
it is translated to the @code{LOG_INFO} priority.
If @var{string} is not given, the format of the log entry depends on
......@@ -1167,30 +1166,30 @@ the connection family, as described in the table below:
@table @asis
@item @{AF_INET @var{ip}:@var{port}@}
For inet IPv4 connections. The variables @var{ip} and @var{port} are
For inet IPv4 connections. The variables @var{ip} and @var{port} are
replaced by the remote IP address and port number, correspondingly.
@item @{AF_UNIX@}
For connections over UNIX sockets. The socket name, if available, may
For connections over UNIX sockets. The socket name, if available, may
be printed before the closing curly brace.
@end table
If the @var{string} is specified, it undergoes macro expansion and the
result of it is used as the log entry. The following macro variables
result of it is used as the log entry. The following macro variables
are expanded:
@table @code
@item aclno
Ordinal number of the control in the ACL. Numbers begin from
Ordinal number of the control in the ACL. Numbers begin from
@samp{0}.
@item family
Connection family. Mailutils version @value{VERSION} supports two
Connection family. Mailutils version @value{VERSION} supports two
families: @samp{AF_INET} and @samp{AF_UNIX}.
@item address
Remote IP address (for @samp{AF_INET}) or socket name (for
@samp{AF_UNIX}). Notice that most Unices return empty string instead
@samp{AF_UNIX}). Notice that most Unices return empty string instead
of the @samp{AF_UNIX} socket name, so do not rely on it.
@item port
......@@ -1214,7 +1213,7 @@ above in your configuration files.
@deffn {Configuration} exec [from] @var{cidr} @var{program}
If a connection from the @var{cidr} block is requested, execute
the given @var{program}. Do not wait for it to teminate, and ignore
the given @var{program}. Do not wait for it to teminate, and ignore
its exit code.
@end deffn
......@@ -1241,43 +1240,43 @@ tcp-wrappers @{
@subsection Description
The @code{tcp-wrappers} statements provides an alternative way to
control accesses to the resources served by GNU Mailutils. This
control accesses to the resources served by GNU Mailutils. This
statement is enabled if Mailutils is compiled with TCP wrappers
library @command{libwrap}.
Access control using TCP wrappers is based on two files, called
@dfn{tables}, containing access rules. There are two tables: the
@dfn{tables}, containing access rules. There are two tables: the
@dfn{allow table}, usually stored in file @file{/etc/hosts.allow}, and
the @dfn{deny table}, kept in file @file{/etc/hosts.deny}. The rules
in each table begin with an identifier called @dfn{daemon name}. Each
the @dfn{deny table}, kept in file @file{/etc/hosts.deny}. The rules
in each table begin with an identifier called @dfn{daemon name}. Each
utility wishing to verify a connection, select the entries having
its daemon name from the allow table. A connection is allowed if it
matches any of these entries. Otherwise, the utility retrieves all
entries with its daemon name from the deny table. If any of these
matches the connection, then it is refused. Otherwise, if neither
its daemon name from the allow table. A connection is allowed if it
matches any of these entries. Otherwise, the utility retrieves all
entries with its daemon name from the deny table. If any of these
matches the connection, then it is refused. Otherwise, if neither
table contains matching entries, the connection is allowed.
Description of a TCP wrapper table format lies outside the scope of
this document. Please, see @ref{ACCESS CONTROL FILES,,ACCESS CONTROL FILES,
this document. Please, see @ref{ACCESS CONTROL FILES,,ACCESS CONTROL FILES,
hosts_access(5), hosts_access(5) man page}, for details.
@deffn {Configuration} enable @var{bool}
Enable access control using TCP wrappers. It is on by default.
Enable access control using TCP wrappers. It is on by default.
@end deffn
@deffn {Configuration} daemon @var{name}
Set daemon name for TCP wrapper lookups. By default, the name of the
utility is used. E.g. @command{imap4d} uses @samp{imap4d} as the
Set daemon name for TCP wrapper lookups. By default, the name of the
utility is used. E.g. @command{imap4d} uses @samp{imap4d} as the
daemon name.
@end deffn
@deffn {Configuration} allow-table @var{file}
Use @var{file} as allow table. By default, @file{/etc/hosts.allow} is
Use @var{file} as allow table. By default, @file{/etc/hosts.allow} is
used.
@end deffn
@deffn {Configuration} deny-table @var{file}
Use @var{file} as negative table. By default, @file{/etc/hosts.deny}
Use @var{file} as negative table. By default, @file{/etc/hosts.deny}
is used.
@end deffn
......@@ -1294,13 +1293,13 @@ Log denied accesses using syslog priority @var{prio}.
@cindex server settings, configuration
@cindex configuring servers
GNU Mailutils offers several server applications: @command{pop3d},
@command{imap4d}, @command{comsatd}, to name a few. Being quite
@command{imap4d}, @command{comsatd}, to name a few. Being quite
different in their purpose, they are very similar in some aspects of
their architecture. First of all, they all support two operating
their architecture. First of all, they all support two operating
mode: a @dfn{daemon} mode, where a program disconnects from the controlling
terminal and works in background, and an @dfn{inetd} mode, where it
remains in foreground and communicates with the remote party via
standard input and output streams. Secondly, when operating as
standard input and output streams. Secondly, when operating as
daemons, they listen to a preconfigured set of IP addresses and
ports, reacting to requests that arrive.
......@@ -1336,17 +1335,17 @@ timeout @var{time};
These statements configure general server-related issues.
@deffn {Configuration} mode @var{string};
Set operation mode of the server. Two operation modes are supported:
Set operation mode of the server. Two operation modes are supported:
@anchor{server mode}
@table @asis
@cindex daemon, server mode
@item daemon
Run as a standalone daemon, disconnecting from the controlling
terminal and continuing to run in the background. In this case, it is
terminal and continuing to run in the background. In this case, it is
the server that controls what IP addresses and ports to listen on, who
is allowed to connect and from where, how many clients are allowed to
connect simultaneously, etc. Most remaining configuration statements
connect simultaneously, etc. Most remaining configuration statements
are valid only in the daemon mode.
This is the preferred mode of operation for GNU Mailutils servers.
......@@ -1354,14 +1353,14 @@ This is the preferred mode of operation for GNU Mailutils servers.
@cindex inetd, server mode
@item inetd
Operate as a subprocess of UNIX internet super-server program,
@command{inetd}. @xref{Internet super-server,,,inetd(8), inetd(8) man
@command{inetd}. @xref{Internet super-server,,,inetd(8), inetd(8) man
page}, for a detailed description of the operation of @command{inetd}
and its configuration. In this case it is @command{inetd} that
and its configuration. In this case it is @command{inetd} that
controls all major connectivity aspects, the Mailutils server itself
communicates with it via standard input and output streams.
For historical reasons, this mode is the default, if no @code{mode}
statement is specified. This will change in the future.
statement is specified. This will change in the future.
@end table
@end deffn
......@@ -1382,22 +1381,22 @@ The default is 20 clients.
@deffn {Configuration} pidfile @var{file};
After startup, store the PID of the main server process in
@var{file}. When the process terminates, the file is removed. As of
@var{file}. When the process terminates, the file is removed. As of
version @value{VERSION}, GNU Mailutils servers make no further use of
this file. It is intended for use by automated startup scripts and
this file. It is intended for use by automated startup scripts and
controlling programs (@FIXME-pxref{mention pies}).
@end deffn
@deffn {Configuration} port @var{portspec};
@*[daemon mode only]
@*Set default port to listen to. The @var{portspec} argument is either
@*Set default port to listen to. The @var{portspec} argument is either
a port number in decimal, or a symbolic service name, as listed in
@file{/etc/services} (@pxref{Internet network services list,,,
services(5), services(5) man page}).
@end deffn
@deffn {Configuration} timeout @var{time};
Set maximum idle time out in seconds. If a client does not send any
Set maximum idle time out in seconds. If a client does not send any
requests during @var{time} seconds, the child process terminates.
@end deffn
......@@ -1421,16 +1420,16 @@ server @var{ipaddr}[:@var{port}] @{
@subsubheading Description
The @code{server} block statement configures a single TCP or UDP
server. It takes effect only in daemon mode (@pxref{server mode}).
server. It takes effect only in daemon mode (@pxref{server mode}).
The argument to this statement specifies the IP address, and,
optionally, the port, to listen on for requests. The @var{ipaddr}
optionally, the port, to listen on for requests. The @var{ipaddr}
part is either an IPv4 address in dotted-quad form, or a symbolic host
name which can be resolved to such an address via DNS. Specifying
name which can be resolved to such an address via DNS. Specifying
@samp{0.0.0.0} as the @var{ipaddr} means listen on all available
network interfaces. The @var{port} argument is either a port number
network interfaces. The @var{port} argument is either a port number
in decimal, or a symbolic service name, as listed in
@file{/etc/services} (@pxref{Internet network services
list,,,services(5), services(5) man page}). If @var{port} is omitted,
list,,,services(5), services(5) man page}). If @var{port} is omitted,
Mailutils uses the port set by @code{port} statement (@pxref{General
Server Configuration, port}), or, in its absence, the default port
number, which depends on a server being used (e.g. 110, for
......@@ -1444,28 +1443,28 @@ Statements within the @code{server} block statement configure this
particular server.
@deffn {Configuration} single-process @var{bool};
If set to true, this server will operate in single-process mode. This
If set to true, this server will operate in single-process mode. This
mode is intended for debugging only, do not use it on production
servers.
@end deffn
@deffn {Configuration} transcript @var{bool};
Enable transcript of the client-server interaction. This may generate
Enable transcript of the client-server interaction. This may generate
exessive amounts of logging, which in turn may slow down the operation
considerably.
Session transcripts are useful in fine-tuning your configurations and
in debugging. They should be turned off on most production servers.
in debugging. They should be turned off on most production servers.
@end deffn
@deffn {Configuration} timeout @var{time};
Set idle timeout for this server. This overrides global timeout
Set idle timeout for this server. This overrides global timeout
settings (@pxref{General Server Configuration, timeout}).
@end deffn
@deffn {Configuration} acl
This statement defines a per-server Access Control List. Its syntax
is as described in @ref{ACL Statement}. Per-server ACLs complement,
This statement defines a per-server Access Control List. Its syntax
is as described in @ref{ACL Statement}. Per-server ACLs complement,
but not override, global ACLs, i.e. if both global ACL and per-server
ACL are used, the connection is allowed only if both of them allow it,
and is denied if any one of them denies it.
......@@ -1489,22 +1488,22 @@ auth @{
@subheading Description
Some mail utilities provide access to their services only after
verifying that the user is actually the person he is claiming
to be. Such programs are, for example, @command{pop3d} and
@command{imap4d}. The process of the verification is broken
to be. Such programs are, for example, @command{pop3d} and
@command{imap4d}. The process of the verification is broken
down into two stages: @dfn{authorization} and @dfn{authentication}.
In @dfn{authorization} stage the program retrieves the information
about a particular user. In @dfn{authentication} stage, this
about a particular user. In @dfn{authentication} stage, this
information is compared against the user-supplied credentials. Only if
both stages succeed is the user allowed to use the service.
A set of @dfn{modules} is involved in performing each stage. For
A set of @dfn{modules} is involved in performing each stage. For
example, the authorization stage can retrieve the user description
from various sources: system database, sql database, virtual domain
table, etc. Each module is responsible for retrieving the description
from a particular source of information. The modules are arranged in
a @dfn{module list}. The modules from the list are invoked in turn,
table, etc. Each module is responsible for retrieving the description
from a particular source of information. The modules are arranged in
a @dfn{module list}. The modules from the list are invoked in turn,
until one of them succeeds or the list is exhausted. In the latter case
the authorization fails. Otherwise, the data returned by the succeeded
the authorization fails. Otherwise, the data returned by the succeeded
module are used in authentication.
Similarly, authentication may be performed in several ways. The
......@@ -1520,12 +1519,12 @@ For example, the authorization list
@noindent
means that first the system user database (@file{/etc/password}) is
searched for a description of a user in question. If the search fails,
the @acronym{sql} database is searched. Finally, if it also fails, the
searched for a description of a user in question. If the search fails,
the @acronym{sql} database is searched. Finally, if it also fails, the
search is performed in the virtual domain database.
@emph{Note}, that some authentication and/or authorization modules may
be disabled when configuring the package before compilation. The names
be disabled when configuring the package before compilation. The names
of the disabled modules are nevertheless available for use in runtime
configuration options, but they represent a ``fail-only'' functionality,
e.g. if the package was compiled without @acronym{sql} support then
......@@ -1535,7 +1534,7 @@ passing the execution on to the next module.
The @code{auth} statement configures authentication and authorization.
@deffn {Configuration} authorization @var{module-list}
Define a sequence of modules to use for authorization. Modules will
Define a sequence of modules to use for authorization. Modules will
be tried in the same order as listed in @var{module-list}.
The modules available for use in authorization list are:
......@@ -1546,13 +1545,22 @@ User credentials are retrieved from the system user database
(@file{/etc/password}).
@item sql
User credentials are retrieved from a @acronym{SQL} database.
Separate configuration statement, @code{sql}, is used to configure
A separate configuration statement, @code{sql}, is used to configure
it (@pxref{SQL Statement}).
@item virtdomain
User credentials are retrieved from a ``virtual domain'' user
database.
database. Virtual domains are configured using @code{virtdomain}
statement (@pxref{Virtdomain Statement}).
@item radius
User credentials are retrieved using @acronym{RADIUS}. @xref{Radius
Statement}, for a detailed description on how to configure it.
@item ldap
User credentials are retrieved from an @acronym{LDAP}
database. @xref{LDAP Statement}, for an information on how to
configure it.
@end table
@FIXME{This may be inaccurate:}
Unless overridden by @code{authorization} statement,
the default list of authorization modules is:
......@@ -1562,14 +1570,14 @@ the default list of authorization modules is:
@end deffn
@deffn {Configuration} authentication @var{module-list}
Define a sequence of modules to use for authentication. Modules will
Define a sequence of modules to use for authentication. Modules will
be tried in the same order as listed in @var{module-list}.
The following table lists modules available for use in @var{module-list}:
@table @asis
@item generic
The generic authentication type. User password is hashed and compared
The generic authentication type. User password is hashed and compared
against the hash value returned in authorization stage.
@item system
The hashed value of the user password is retrieved from
......@@ -1582,8 +1590,14 @@ statement (@pxref{SQL Statement, getpass}).
The user is authenticated via pluggable authentication module
(@acronym{PAM}). The @acronym{PAM} service name to be used is
configured in @code{pam} statement (@pxref{PAM Statement}).
@item radius
The user is authenticated on a remote @acronym{RADIUS}
server. @xref{Radius Statement}.
@item ldap
The user is authenticated using @acronym{LDAP}. @xref{LDAP Statement}.
@end table
@FIXME{This list is inaccurate:}
Unless overridden by @code{authentication} statement,
the list of authentication modules is:
......@@ -1604,11 +1618,11 @@ pam @{
@end smallexample
@subheading Description
The @code{pam} statement configures @acronym{PAM} authentication. It
The @code{pam} statement configures @acronym{PAM} authentication. It
contains a single sub-statement:
@deffn {Configuration} service @var{text}
Define service name to look for in @acronym{PAM} configuration. By
Define service name to look for in @acronym{PAM} configuration. By
default, the base name of the Mailutils binary is used.
@end deffn
......@@ -1634,9 +1648,9 @@ user name can be present in several domains and represent different
users.
When authenticating to a server with virtual domain support enabled,
users must supply their usernames with domain parts. The server strips
users must supply their usernames with domain parts. The server strips
off the domain part and uses it as a name of UNIX-format password
database file, located in the @dfn{domain password directory}. The
database file, located in the @dfn{domain password directory}. The
latter is set using @code{passwd-dir} statement.
@deffn {Configuration} passwd-dir @var{dir}
......@@ -1649,7 +1663,7 @@ This file must be in UNIX passwd format (@pxref{password
file,,,passwd(5), passwd(5) man page}), with encrypted passwords
stored in it (as of GNU Mailutils version @value{VERSION}, there is no
support for shadow files in virtual password directories, although
this is planned for future versions). Here is an example record from
this is planned for future versions). Here is an example record from
this file:
@smallexample
......@@ -1659,35 +1673,175 @@ smith:Wbld/G2Q2Le2w:1000:1000:Email Account:/var/mail/domain/smith:/dev/null
Notice, that it must contain user names without domain parts.
The @code{pw_dir} field (the 6th field) is used to determine the
location of the maildrop for this user. It is defined as
@file{@var{pw_dir}/INBOX}. In our example, the maildrop for user
location of the maildrop for this user. It is defined as
@file{@var{pw_dir}/INBOX}. In our example, the maildrop for user
@samp{smith} will be located in file @file{/var/mail/domain/smith}.
If user did not supply his domain name, or if no matching record was
found in the password file, or if the file matching the domain name
does not exist, then GNU Mailutils falls back to alternative method.
First, it tries to determine the IP address of the remote party. Then
First, it tries to determine the IP address of the remote party. Then
the domain name corresponding to that address is looked up in the DNS
system. Finally, this domain name is used as a name of the password
system. Finally, this domain name is used as a name of the password
file.
@node Radius Statement
@subsection Radius Statement
@UNREVISED
@kwindex radius
@subheading Syntax
@smallexample
radius @{
# Set radius configuration directory.
directory @var{dir};
# @r{Radius request for authorization.}
auth @var{request};
# @r{Radius request for getpwnam.}
getpwnam @var{request};
# Radius request for getpwuid.
getpwuid @var{request};
# Set radius configuration directory.
directory @var{dir};
@}
@end smallexample
@subheading Description
The @code{radius} block statement configures @acronym{RADIUS
authentication} and authorization.
Mailutils uses GNU Radius library, which is configured via
@file{raddb/client.conf} file (@pxref{client.conf, Client Configuration,
Client Configuration, radius, GNU Radius Reference Manual}). Its exact
location depends on configuration settings that were used while
compiling GNU Radius. Usually it is @file{/usr/local/etc}, or
@file{/etc}. This default can also be changed at run time using
@code{directory} statement:
@deffn {Configuration} directory @var{dir}
Set full path name to the GNU Radius configuration directory.
@end deffn
It authorization is used, the Radius dictionary file must declare the
the following attributes:
@multitable @columnfractions 0.4 0.2 0.4
@headitem Attribute @tab Type @tab Description
@kwindex GNU-MU-User-Name
@item GNU-MU-User-Name @tab string @tab User login name
@kwindex GNU-MU-UID
@item GNU-MU-UID @tab integer @tab UID
@kwindex GNU-MU-GID
@item GNU-MU-GID @tab integer @tab GID
@kwindex GNU-MU-GECOS
@item GNU-MU-GECOS @tab string @tab GECOS
@kwindex GNU-MU-Dir
@item GNU-MU-Dir @tab string @tab Home directory
@kwindex GNU-MU-Shell
@item GNU-MU-Shell @tab string @tab User shell
@kwindex GNU-MU-Mailbox
@item GNU-MU-Mailbox @tab string @tab User mailbox
@kwindex GNU-MU-Quota
@item GNU-MU-Quota @tab integer @tab Mail quota (in bytes)
@end multitable
@flindex mailutils.dict
A dictionary file with appropriate definitions is included in the
Mailutils distribution: @file{examples/config/mailutils.dict}. This
file is not installed by default, you will have to manually copy it to
the GNU Radius @file{raddb/dict} directory and include it in the main
dictionary file @file{raddb/dictionary} by adding the following
statement:
@smallexample
$INCLUDE dict/mailutils.dict
@end smallexample
Requests to use for authentication and authorization are
configured using three statements: @code{auth}, @code{getpwnam} and
@code{getpwuid}. Each statement takes a single argument: a string,
containing a comma-separated list of assignements. An assignement
specifies a particular @dfn{attribute-value pair} (@pxref{Overview,
RADIUS Attributes,, radius, GNU Radius Reference Manual}) to send to
the server. The left-hand side of the assignement is a symbolic attribute
name, as defined in one of Radius dictionaries (@pxref{dictionary
file, Dictionary of Attributes,, radius, GNU Radius Reference
Manual}). The value is specified by the right-hand side of
assignement. For example:
@smallexample
"Service-Type = Authenticate-Only, NAS-Identifier = \"mail\""
@end smallexample
An assignement may contain references to the following macro-variables
(@FIXME-pxref{macro-variables}):
@table @asis
@item user
The actual user name (for @code{auth} and @code{getpwnam}), or user ID
(for @code{getpwuid}). For example:
@smallexample
User-Name = $@{user@}
@end smallexample
@item passwd
User password. For examples:
@smallexample
User-Password = $@{passwd@}
@end smallexample
@end table
@deffn {Configuration} auth @var{pairlist}
Specifies the request to be sent to authenticate the user. For example:
@smallexample
auth "User-Name = $@{user@}, User-Password = $@{passwd@}";
@end smallexample
The user is authenticated only if this request returns
@code{Access-Accept} (@pxref{Authentication Requests, Access-Accept,,
radius, GNU Radius Reference Manual}). Any returned attribute-value
pairs are ignored.
@end deffn
@deffn {Configuration} getpwnam @var{pairlist}
Specifies the request that returns user information for the
given user name. For example:
@smallexample
getpwnam "User-Name = $@{user@}, State = getpwnam, "
"Service-Type = Authenticate-Only";
@end smallexample
If the requested user account exists, the Radius server must return
@code{Access-Accept} packet with the following attributes:
@code{GNU-MU-User-Name}, @code{GNU-MU-UID}, @code{GNU-MU-GID},
@code{GNU-MU-GECOS}, @code{GNU-MU-Dir}, @code{GNU-MU-Shell}.
The attributes @code{GNU-MU-Mailbox} and @code{GNU-MU-Quota} are
optional.
If @code{GNU-MU-Mailbox} is present, it must contain a
valid mailbox @acronym{URL} (@FIXME-pxref{urls}). If
@code{GNU-MU-Mailbox} is not present, Mailutils constructs the
mailbox name using the settings from the @code{mailbox} configuration
statement (@pxref{Mailbox Statement}), or built-in defaults, if it is
not present.
If @code{GNU-MU-Quota} is present, it specifies the maximum mailbox
size for this user, in bytes. In the absence of this attribute,
mailbox size is unlimited.
@end deffn
@deffn {Configuration} getpwuid @var{pairlist}
Specifies the request that returns user information for the
given user ID. In @var{pairlist}, the @samp{user} macro-variable is
expanded to the numeric value of ID. For example:
@smallexample
getpwuid "User-Name = $@{user@}, State = getpwuid, "
"Service-Type = Authenticate-Only";
@end smallexample
The reply to @code{getpwuid} request is the same as to @code{getpwnam}
request (see above).
@end deffn
@node SQL Statement
@subsection SQL Statement
......@@ -1698,12 +1852,6 @@ radius @{
sql @{
# @r{Set SQL interface to use.}
interface @samp{mysql|odbc|postgres};
# @r{SQL query to use for getpwnam requests.}
getpwnam @var{query};
# @r{SQL query to use for getpwuid requests.}
getpwuid @var{query};
# @r{SQL query returning the user's password.}
getpass @var{query};
# @r{SQL server host name.}
host @var{arg};
# @r{SQL user name.}
......@@ -1718,8 +1866,68 @@ sql @{
password-type @samp{plain | hash | scrambled};
# @r{Set a field-map for parsing SQL replies.}
field-map @var{map};
# @r{SQL query returning the user's password.}
getpass @var{query};
# @r{SQL query to use for getpwnam requests.}
getpwnam @var{query};
# @r{SQL query to use for getpwuid requests.}
getpwuid @var{query};
@}
@end smallexample
@subsection Description
The @code{sql} statement configures access credentials to
@acronym{SQL} database and the queries for authentication and
authorization.
GNU Mailutils supports three types of @acronym{SQL} interfaces:
MySQL, PostgreSQL and ODBC. The latter is a standard API for using
database management systems, which can be used to communicate with a
wide variety of DBMS.
@deffn {Configuration} interface @var{type}
Configures type of DBMS interface. Allowed values for @var{type} are:
@table @asis
@item mysql
Interface with a MySQL server (@uref{http://www.mysql.org}).
@item odbc
Use ODBC interface. See @uref{http://www.unixodbc.org}, for a detailed
description of ODBC configuration.
@item postgres
Interface with a PostgreSQL server (@uref{http://www.postgres.org}).
@end table
@end deffn
The database and database access credentials are configured using the
following statements:
@deffn {Configuration} host @var{arg}
The host running the @acronym{SQL} server. The value can be either a
host name or an IP address in dotted-quad notation, in which case an
@acronym{INET} connection is used, or a full pathname to a file, in
which case a connection to @acronym{UNIX} socket is used.
@end deffn
@deffn {Configuration} port @var{arg}
TCP port the server is listening on (for @acronym{INET}
connections). This parameter is optional. Its default value depends on
the type of database being used.
@end deffn
@deffn {Configuration} db @var{arg};
Name of the database.
@end deffn
@deffn {Configuration} user @var{arg}
@acronym{SQL} user name.
@end deffn
@deffn {Configuration} passwd @var{arg};
Password to access the database.
@end deffn
@node LDAP Statement
@subsection LDAP Statement
......@@ -2577,7 +2785,7 @@ contain in order to be piped through pager command specified
by environment variable @code{PAGER}. If @code{crt} is set to a numeric
value, this value is taken as the minimum number of lines. Otherwise,
if @code{crt} is set without a value then the height of the terminal
screen is used to compute the threshold. The number of lines on
screen is used to compute the threshold. The number of lines on
screen is controlled by @code{screen} variable.
@item Print [@var{msglist}]
@itemx P [@var{msglist}]
......@@ -2602,7 +2810,7 @@ Content-Type: message/delivery-status
@end smallexample
@item top [@var{msglist}]
@itemx to [@var{msglist}]
Prints the top few lines of each message in @var{msglist}. The number
Prints the top few lines of each message in @var{msglist}. The number
of lines printed is controlled by the variable @code{toplines} and
defaults to five.
@item pipe [@var{msglist}] [@var{shell-command}]
......@@ -2766,13 +2974,13 @@ With more than one argument, creates a new alias or changes an old one.
@item unalias [@var{alias}...]
@itemx una [@var{alias}...]
Takes a list of names defined by alias commands and discards the
remembered groups of users. The alias names no longer have any
remembered groups of users. The alias names no longer have any
significance.
@item alternates @var{name}...
@itemx alt @var{name}...
The alternates command is useful if you have accounts on several
machines. It can be used to inform mail that the listed addresses are
really you. When you reply to messages, mail will not send a copy of
really you. When you reply to messages, mail will not send a copy of
the message to any of the addresses listed on the alternates list.
If the alternates command is given with no argument, the current set of
alternate names is displayed.
......@@ -3094,7 +3302,7 @@ set
@node Mail Variables
@subsection How to Alter the Behavior of @command{mail}
Following variables control the behavior of @sc{gnu} @command{mail}:
Following variables control the behavior of GNU @command{mail}:
@table @code
@item appenddeadletter
......@@ -3201,7 +3409,7 @@ of the message must contain in order to be piped through pager command
specified by environment variable @code{PAGER}. If @code{crt} is set
to a numeric value, this value is taken as the threshold. Otherwise,
if @code{crt} is set without a value, then the height of the terminal
screen is used to compute the threshold. The number of lines on
screen is used to compute the threshold. The number of lines on
screen is controlled by @code{screen} variable.
@item decode-fallback
......@@ -3404,7 +3612,7 @@ type @samp{image/jpeg}.
@vrindex metoo, mail variable
Usually, when an alias is expanded that contains the sender, the sender
is removed from the expansion. Setting this option causes the sender to
is removed from the expansion. Setting this option causes the sender to
be included in the group.
@item mode
......@@ -3420,14 +3628,14 @@ Setting this variable does not affect the operation mode of the program.
@vrindex nullbody, mail variable
Controls whether @command{mail} accepts messages with an empty
body. The default value, @code{true}, means such messages are sent,
body. The default value, @code{true}, means such messages are sent,
and a warning (traditionally saying @samp{Null message body; hope
that's ok}) is displayed. The text of the warning can be set using
that's ok}) is displayed. The text of the warning can be set using
@code{nullbodymsg} variable (see below).
If @code{nullbody} is unset, @command{mail} will silently ignore such
messages. This can be useful in @file{crontab} files, to avoid sending
mails when nothing important happens. For example, the @file{crontab}
messages. This can be useful in @file{crontab} files, to avoid sending
mails when nothing important happens. For example, the @file{crontab}
entry below will send mail only if the utility @command{some-prog}
outputs something on its standard output or error:
......@@ -3444,7 +3652,7 @@ outputs something on its standard output or error:
@vrindex nullbodymsg
Keeps the text of the warning, displayed by @command{mail} before
sending an empty message. When available, the translation of
sending an empty message. When available, the translation of
this text, in accordance with the current locale, is displayed.
Unsetting this variable disables the warning.
......@@ -3849,23 +4057,23 @@ Enable (default) or disable TLS support
@pindex readmsg
The program, readmsg, extracts with the selection argument messages from
a mailbox. Selection can be specify by:
a mailbox. Selection can be specify by:
@enumerate
@item A lone ``*'' means select all messages in the mailbox.
@item
A list of message numbers may be specified. Values
A list of message numbers may be specified. Values
of ``0'' and ``$'' in the list both mean the last
message in the mailbox. For example:
message in the mailbox. For example:
@smallexample
readmsg 1 3 0
@end smallexample
extracts three messages from the folder: the first, the third, and the last.
@item
Finally, the selection may be some text to match. This will select a mail
message which exactly matches the specified text. For example,
Finally, the selection may be some text to match. This will select a mail
message which exactly matches the specified text. For example,
@smallexample
readmsg staff meeting
@end smallexample
......@@ -3916,7 +4124,7 @@ Default is --weedlist=''From Subject Date To CC Apparently-''
@pindex sieve
Sieve is a language for filtering e-mail messages at time of final
delivery, described in RFC 3028. @sc{gnu} Mailutils provides two
delivery, described in RFC 3028. GNU Mailutils provides two
implementations of this language: a stand-alone @dfn{sieve interpreter}
and a @dfn{sieve translator and filter}. The following sections describe these
utilities in detail.
......@@ -3930,10 +4138,10 @@ utilities in detail.
@subsection A Sieve Interpreter
Sieve interpreter @command{sieve} allows to apply Sieve scripts to an
arbitrary number of mailboxes. @sc{gnu} @command{sieve} implements a superset
arbitrary number of mailboxes. GNU @command{sieve} implements a superset
of the Sieve language as described in RFC 3028. @xref{Sieve Language},
for a description of the Sieve language. @xref{GNU Extensions}, for a
discussion of differences between the @sc{gnu} implementation of Sieve and
discussion of differences between the GNU implementation of Sieve and
its standard.
@menu
......@@ -4047,7 +4255,7 @@ for debugging the code generator.
@emph{Note}, that there should be no whitespace
between the short variant of the option (@option{-d}), and its
argument. Similarly, when using long option (@option{--debug}),
argument. Similarly, when using long option (@option{--debug}),
its argument must be preceded by equal sign.
If the argument to @option{--debug} is omitted, it defaults to
......@@ -4374,7 +4582,7 @@ Display usage summary and exit.
@item -L
@itemx --license
Display @sc{gnu} General Public License and exit.
Display GNU General Public License and exit.
@item -m @var{path}
@itemx --mail-spool @var{path}
......@@ -4558,7 +4766,7 @@ not delivered and the sender receives following notification message:
message. In this case @command{mail.local} does deliver the message.
@end enumerate
Version @value{VERSION} of @sc{gnu} mailutils is able to retrieve
Version @value{VERSION} of GNU mailutils is able to retrieve
mailbox quotas from a @sc{dbm} or @sc{sql} database.
@menu
......@@ -4950,7 +5158,7 @@ days, for retrieved messages on the server.
downloaded by @code{RETR} or @code{TOP} command, it is marked with
@samp{X-Expire-Timestamp: @var{n}} header, where @var{n} is current
value of UNIX timestamp. The exact expiration mechanism
depends on you. Mailutils allows you two options:
depends on you. Mailutils allows you two options:
@enumerate
@item
......@@ -5084,7 +5292,7 @@ Sets the name of the login timestamp database, used with
@item -t @var{number}
@itemx --timeout @var{number}
Set idle timeout to given @var{number} of seconds. Default is 600 seconds (10
minutes). The daemon breaks the connection if it receives no commands
minutes). The daemon breaks the connection if it receives no commands
from the client within that number of seconds.
@item --tls-required
......@@ -5104,7 +5312,7 @@ Remove all deletion marks from the messages after opening the mailbox.
@section IMAP4 Daemon
@pindex imap4d
@sc{gnu} @command{imap4d} is a daemon implementing @sc{imap4} rev1 protocol
GNU @command{imap4d} is a daemon implementing @sc{imap4} rev1 protocol
for accessing and handling electronic mail messages on a server. It can
be run either as a standalone program or from @file{inetd.conf} file.
......@@ -5118,7 +5326,7 @@ be run either as a standalone program or from @file{inetd.conf} file.
@cindex namespace
@cindex IMAP4 namespace
@sc{gnu} @command{imap4d} supports a notion of @dfn{namespaces} defined
GNU @command{imap4d} supports a notion of @dfn{namespaces} defined
in RFC 2342. A namespace is a set of directories upon which the user
has certain permissions. It should be understood that these permissions
apply only if the underlying filesystem allows them.
......@@ -5222,7 +5430,7 @@ namespace. @var{pathlist} is a list of directory names separated by colons.
@item -t @var{number}
@itemx --timeout @var{number}
Set idle timeout to given @var{number} of seconds. Default is 1800 seconds (30
minutes). The daemon breaks the connection if it receives no commands
minutes). The daemon breaks the connection if it receives no commands
from the client within that number of seconds.
@item -v
@itemx --version
......@@ -5664,7 +5872,7 @@ The flags and their meanings are:
The Mailutils uses @sc{pam} libraries.
@item HAVE_LIBLTDL
The @sc{gnu} wrapper library @file{libltdl} is present and is used
The GNU wrapper library @file{libltdl} is present and is used
by Mailutils. @xref{Using libltdl,,,libtool,Using libltdl}, for
more information on @file{libltdl} library.
......
......@@ -5,10 +5,10 @@
@c ======================================================================
@c This document has three levels of rendition: PUBLISH, DISTRIB or PROOF,
@c as decided by @set symbols. The PUBLISH rendition does not show
@c notes or marks asking for revision. Most users will prefer having more
@c as decided by @set symbols. The PUBLISH rendition does not show
@c notes or marks asking for revision. Most users will prefer having more
@c information, even if this information is not fully revised for adequacy,
@c so DISTRIB is the default for distributions. The PROOF rendition
@c so DISTRIB is the default for distributions. The PROOF rendition
@c show all marks to the point of ugliness, but is nevertheless useful to
@c those working on the manual itself.
@c ======================================================================
......
......@@ -4,7 +4,7 @@
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
The input language understood by the @sc{gnu} Sieve Library
The input language understood by the GNU Sieve Library
is a superset of the Sieve language as described in RFC 3028.
@menu
......@@ -52,8 +52,8 @@ Like in C, bracketed comments do not nest.
The basic lexical entities are @dfn{identifiers} and @dfn{literals}.
An @dfn{identifier} is a sequence of letters, digits and underscores, started
with a letter or underscore. For example, @code{header} and
An @dfn{identifier} is a sequence of letters, digits and underscores,
that begins with a letter or underscore. For example, @code{header} and
@code{check_822_again} are valid identifiers, whereas @code{1st} is not.
A special form of identifier is @dfn{tag}: it is an identifier prefixed
with a colon (@samp{:}), e.g.: @code{:comparator}.
......@@ -64,6 +64,7 @@ literals:
@itemize
@item Number
@cindex numbers, sieve
@dfn{Numbers} are given as ordinary unsigned decimal numbers. An
optional suffix may be used to indicate a multiple of a power of two.
......@@ -75,13 +76,14 @@ or 1,073,741,824 (2^30) times the value of the number.
The numbers have 32 bits of magnitude.
@item String
@cindex strings, sieve
A @dfn{string} is any sequence of characters enclosed in double quotes
(@samp{"}). A string cannot contain newlines and double quote
characters. This limitation will disappear in future releases.
@item Multiline Strings
@cindex multiline strings, sieve
@kwindex text:
A @dfn{multiline string} is used to represent large blocks of text
with embedded newlines and special characters. It starts with the
keyword @code{text:} followed by a newline and ends with a dot
......@@ -159,6 +161,7 @@ if header "from" "me@@example.com"
@noindent
@item String Lists
@cindex string list, sieve
A @dfn{string list} is a comma-delimited list of quoted strings, enclosed
in a pair of square brackets, e.g.:
......@@ -169,7 +172,7 @@ in a pair of square brackets, e.g.:
For convenience, in any context where a list of strings is appropriate,
a single string is allowed without being a member of a list: it is
equivalent to a list with a single member. For example, the following
equivalent to a list with a single member. For example, the following
two statements are equivalent:
@smallexample
......@@ -225,6 +228,7 @@ For example, consider the following command
@smallexample
header :mime :comparator "i;octet" ["to", "from"] "bug-mailutils@@gnu.org"
@end smallexample
@noindent
Here, given that @code{header} takes two positional arguments:
@code{header} is command name, the list @code{["to", "from"]} is first
......@@ -235,9 +239,10 @@ parameter.
@node Actions Described
@subsection Actions Described
@cindex action, sieve
An @dfn{action} is a Sieve command that performs some operation over
the message. Actions do the main job in any Sieve
a message. Actions do the main job in any Sieve
program. Syntactically, an action is a command terminated with
semicolon, e.g.:
......@@ -247,14 +252,15 @@ keep;
fileinto "mbox";
@end smallexample
@sc{gnu} Sieve provides the full set of actions described in RFC 3028.
GNU Sieve provides the full set of actions described in RFC 3028.
It also allows to extend this set using loadable
actions. @xref{Actions}, for detailed discussion of actions.
@node Control Flow
@subsection Control Flow
@kwindex if, sieve
The only control flow statement Sieve has is ``if'' statement. In its
The only control flow statement Sieve has is @code{if} statement. In its
simplest form it is:
@smallexample
......@@ -313,6 +319,7 @@ statements.
@node Tests and Conditions
@subsection Tests and Conditions
@cindex test, sieve
@dfn{Tests} are Sieve commands that return boolean value. E.g. the
test
......@@ -320,21 +327,28 @@ test
@smallexample
header :contains "from" "coyote"
@end smallexample
@noindent
returns true only if the header ``From'' of the current message contains
substring ``coyote''.
The tests shipped with the @sc{gnu} Sieve are described in @ref{Tests}.
The tests shipped with the GNU Sieve are described in @ref{Tests}.
@cindex condition, sieve
@dfn{Condition} is a Sieve expression that evaluates to @code{true} or
@code{false}. In its simplest form, condition is just a Sieve test.
@kwindex not, sieve
To reverse the sense of a condition use keyword @code{not}, e.g.:
@smallexample
not header :contains "from" "coyote"
@end smallexample
@kwindex and, sieve
@kwindex or, sieve
@kwindex allof
@kwindex anyof
The results of several conditions may be joined together by logical
@code{and} and @code{or} operations. The special form @code{allof}
takes several tests as its arguments and computes the logical @code{and}
......@@ -351,11 +365,12 @@ if anyof (not exists ["From", "Date"],
@node Preprocessor
@section Preprocessor
@cindex Sieve preprocessor statements, a @sc{gnu} extension
@cindex preprocessor, sieve
@cindex Sieve preprocessor statements
The preprocessor statements are a @sc{gnu} extension to the Sieve language.
Preprocessor statements are a GNU extension to the Sieve language.
The syntax for a preprocessor statement is similar to that used in
@code{C} programming language, i.e.: a pound character (@samp{#})
@code{C} programming language, i.e. a pound character (@samp{#})
followed by a preprocessor directive and its arguments. Any amount of
whitespace can be inserted between the @samp{#} and the directive.
Currently implemented directives are @code{include} and @code{searchpath}.
......@@ -367,7 +382,7 @@ Currently implemented directives are @code{include} and @code{searchpath}.
@node #include
@subheading Sieve #include directive
@cindex #include, sieve
@kwindex #include, sieve
The @code{#include} directive reads in the contents of the given file.
The contents is ``inserted'' into the text being parsed starting at the
......@@ -387,15 +402,16 @@ If @var{filename} starts with a directory separator character
@node #searchpath
@subheading Sieve #searchpath directive
@cindex #searchpath, sieve
@kwindex #searchpath, sieve
The @code{#searchpath} directive adds its argument to the list of
directories searched for loadable modules. It has the same effect
as @option{-L} command line switch used by @sc{gnu} sieve utility
as @option{-L} command line switch used by GNU sieve utility
(@FIXME-pxref{sieve group}).
@node Require Statement
@section Require Statement
@kwindex require, sieve
@smallexample
Syntax: require @var{string};
......@@ -419,11 +435,12 @@ Otherwise, the capability is understood as a name of an action to be
used.
The @code{require} statement, if present, must be used before any other
statement that is using the required capability. As an extension, the @sc{gnu}
statement that is using the required capability. As an extension, the GNU
sieve allows the @code{require} and any other statements to be
interspersed.
By default the following actions and comparators are always required:
By default the following actions and comparators need not be
explicitly required:
@itemize
@item stop
......@@ -443,7 +460,7 @@ require "fileinto";
require "comparator-i;ascii-numeric";
@end smallexample
When processing arguments for @code{require} statement, @sc{gnu} libsieve
When processing arguments for @code{require} statement, GNU libsieve
uses the following algorithm:
@enumerate 1
......@@ -481,6 +498,8 @@ search path (e.g. on Linux it is set by the contents of the file
@env{LD_LIBRARY_PATH}).
@end enumerate
@vindex LTDL_LIBRARY_PATH
@vindex LD_LIBRARY_PATH
The value of @env{LTDL_LIBRARY_PATH} and @env{LD_LIBRARY_PATH} must be a
colon-separated list of absolute directories, for example,
@samp{"/usr/lib/mypkg:/lib/foo"}.
......@@ -512,8 +531,9 @@ source for the required action NAME is not available
@node Comparators
@section Comparators
@cindex comparator, sieve
@sc{gnu} libsieve supports the following built-in comparators:
GNU libsieve supports the following built-in comparators:
@table @code
@item i;octet
......@@ -531,8 +551,9 @@ be explicitly required prior to use.
@node Tests
@section Tests
@cindex test, sieve
This section describes the built-in tests supported by @sc{gnu} libsieve.
This section describes the built-in tests supported by GNU libsieve.
In the discussion below the following macro-notations are used:
@table @var
......@@ -541,31 +562,41 @@ This tag specifies the matching type to be used with the test. It can
be one of the following:
@table @code
@kwindex :is, sieve
@kwindex is, sieve
@item :is
The @code{:is} match type describes an absolute match; if the contents of
the first string are absolutely the same as the contents of the
second string, they match. Only the string ``frobnitzm'' is the string
``frobnitzm''. The null key ``:is'' and only ``:is'' the null value.
second string, they match. Only the string ``frobnitzm'' is the string
``frobnitzm''. The null key ``:is'' and only ``:is'' the null value.
This is the default match-type.
@kwindex :contains, sieve
@kwindex contains, sieve
@item :contains
The @code{:contains} match type describes a substring match. If the value
The @code{:contains} match type describes a substring match. If the value
argument contains the key argument as a substring, the match is true.
For instance, the string ``frobnitzm'' contains ``frob'' and ``nit'', but
not ``fbm''. The null key ``'' is contained in all values.
not ``fbm''. The null key ``'' is contained in all values.
@kwindex :matches, sieve
@kwindex matches, sieve
@item :matches
The @code{:matches} version specifies a wildcard match using the
characters @samp{*} and @samp{?}. @samp{*} matches zero or more
characters, and @samp{?} matches a single character. @samp{?} and
@samp{*} may be escaped as @samp{\\?} and @samp{\\*} in strings to match
against themselves. The first backslash escapes the second backslash;
against themselves. The first backslash escapes the second backslash;
together, they escape the @samp{*}.
@kwindex :regex, sieve
@kwindex regex, sieve
@item :regex
The @code{:regex} version specifies a match using POSIX Extended Regular
Expressions.
@kwindex :value, sieve
@kwindex value, sieve
@item :value @var{relation}
The @code{:value} match type does a relational comparison between
strings. Valid values for @var{relation} are:
......@@ -590,6 +621,8 @@ Less Than
Less than or Equal
@end table
@kwindex :count, sieve
@kwindex count, sieve
@item :count @var{relation}
This match type first determines the number of the specified entities
(headers, addresses, etc.) in the message and does a relational
......@@ -597,6 +630,8 @@ comparison of the number of entities to the values specified in the
test expression. The test expression must be a list of one element.
@end table
@kwindex :comparator, sieve
@kwindex comparator, sieve
@item comparator
A @var{comparator} syntax item is defined as follows:
......@@ -623,12 +658,18 @@ specifies which part of an address must be used in comparisons.
Exactly one of the following tags may be used:
@table @code
@kwindex :all, sieve
@kwindex all, sieve
@item :all
Use the whole address. This is the default.
@kwindex :localpart, sieve
@kwindex localpart, sieve
@item :localpart
Use local part of the address.
@kwindex :domain, sieve
@kwindex domain, sieve
@item :domain
Use domain part of the address.
@end table
......@@ -651,6 +692,19 @@ comparator `i;ascii-numeric' is incompatible with match type `:matches'
in call to `header'
@end smallexample
GNU Sieve supports two kinds of tests. @dfn{Built-in tests} are
defined within the library and do not require any external files.
@dfn{External tests} are loadable modules that can be linked in at run
time using the @code{require} statement (@pxref{Require Statement}).
@menu
* Built-in Tests::
* External Tests::
@end menu
@node Built-in Tests
@subsection Built-in Tests
@deffn Test false
This test always evaluates to ``false''.
......@@ -661,7 +715,10 @@ This test always evaluates to ``false''.
This test always evaluates to ``true''.
@end deffn
@deffn Test address [@var{address-part}][@var{comparator}][@var{match-type}] @var{header-names} @var{key-list}
@deftypefn Test {} address [@var{address-part}] @
[@var{comparator}] @
[@var{match-type}] @
@var{header-names} @var{key-list}
@noindent
Tagged arguments:
......@@ -677,6 +734,7 @@ Specifies the comparator to be used instead of the default @code{i;ascii-casemap
@item match-type
Specifies the match type to be used instead of the default @code{:is}.
@end table
@noindent
Required arguments:
......@@ -690,7 +748,7 @@ A list of address values.
@noindent
The @code{address} test matches Internet addresses in structured headers
that contain addresses. It returns @code{true} if any header contains any
that contain addresses. It returns @code{true} if any header contains any
key in the specified part of the address, as modified by
@var{comparator} and @var{match-type} optional arguments.
......@@ -710,13 +768,11 @@ if address :is :all "from" "tim@@example.com"
discard;
@}
@end smallexample
@end deffn
@deffn Test size [:over|:under] @var{number}
@noindent
@end deftypefn
@deftypefn Test {} size [:over | :under] @var{limit}(number)
The @code{size} test deals with the size of a message. The required
argument @var{number} represents the size of the message in bytes. It
argument @var{limit} represents the size of the message in bytes. It
may be suffixed with the following quantifiers:
@table @samp
......@@ -731,20 +787,26 @@ The number is expressed in megabytes.
The number is expressed in gigabytes.
@end table
@kwindex :over
If the tagged argument is @samp{:over}, and the size of the message is greater
than @var{number}, the test is true; otherwise, it is false.
@kwindex :under
If the argument is @samp{:under}, and the size of the message is less than
the @var{number}, the test is true; otherwise, it is false.
Otherwise, the test is true only if the size of the message equals
exactly @var{number}. This is a @sc{gnu} extension.
exactly @var{number}. This is a GNU extension.
The size of a message is defined to be the number of octets from the
initial header until the last character in the message body.
@end deffn
@end deftypefn
@deffn Test envelope [@var{address-part}][@var{comparator}][@var{match-type}] @var{envelope-part} @var{key-list}
@deftypefn Test {} envelope [@var{address-part}] @
[@var{comparator}] @
[@var{match-type}] @
@var{envelope-part}(string-list) @
@var{key-list}(string-list)
@noindent
Tagged arguments:
......@@ -782,9 +844,9 @@ then matching occurs against the FROM address used in the
@emph{Notice}, that due to the limitations imposed by @sc{smtp} envelope
structure the use of any other values in @var{envelope-parts} header is
meaningless.
@end deffn
@end deftypefn
@deffn Test exists @var{header-names}
@deftypefn Test {} exists @var{header-names}(string-list)
@noindent
Required arguments:
......@@ -793,9 +855,9 @@ Required arguments:
@item header-names
List of message header names.
@end table
@sp 1
@noindent
The @code{exists} test is @code{true} if the headers listed in
@var{header-names} argument exist within the message. All of the headers
must exist or the test is false.
......@@ -809,9 +871,13 @@ if not exists ["From","Date"]
discard;
@}
@end smallexample
@end deffn
@end deftypefn
@deffn Test header [@var{comparator}] [@var{match-type}] [:mime] @var{header-names} @var{key-list}
@deftypefn Test {} header [@var{comparator}] @
[@var{match-type}] @
[:mime] @
@var{header-names}(string-list) @
@var{key-list}(string-list)
@sp 1
@noindent
Tagged arguments:
......@@ -823,6 +889,7 @@ Specifies the comparator to be used instead of the default @code{i;ascii-casemap
@item @var{match-type}
Specifies the match type to be used instead of the default @code{:is}.
@kwindex :mime
@item :mime
This tag instructs @code{header} to search through the mime headers in
multipart messages as well.
......@@ -842,15 +909,15 @@ A list of header values.
@sp 1
@noindent
The @code{header} test evaluates to true if any header name matches any
key. The type of match is specified by the optional match argument,
key. The type of match is specified by the optional match argument,
which defaults to ":is" if not explicitly given.
The test returns @code{true} if any combination of the @var{header-names}
and @var{key-list} arguments match.
If a header listed in @var{header-names} exists, it contains the null
key (@samp{""}). However, if the named header is not present, it
does not contain the null key. So if a message contained the header
key (@samp{""}). However, if the named header is not present, it
does not contain the null key. So if a message contained the header
@smallexample
X-Caffeine: C8H10N4O2
......@@ -863,31 +930,207 @@ these tests on that header evaluate as follows:
header :is ["X-Caffeine"] [""] @result{} false
header :contains ["X-Caffeine"] [""] @result{} true
@end smallexample
@end deffn
@end deftypefn
@node External Tests
@subsection External Tests
@deffn Test numaddr [:over|:under] @var{header-names} @var{number}
@deftypefn Test {} numaddr [:over | :under] @
@var{header-names}(string-list) @
@var{count}(number)
@noindent
@subsubheading Synopsis
@smallexample
require "test-numaddr";
@dots{}
if numaddr @var{args}
@{
@dots{}
@}
@end smallexample
@subsubheading Description
This test is provided as an example of loadable extension tests. You
must use @samp{require "test-numaddr"} statement before actually using
it.
The @code{numaddr} test counts Internet addresses in structured headers
that contain addresses. It returns true if the total number of
that contain addresses. It returns true if the total number of
addresses satisfies the requested relation.
@kwindex :over
If the tagged argument is @samp{:over} and the number of addresses is
greater than @var{number}, the test is true; otherwise, it is false.
greater than @var{count}, the test is true; otherwise, it is false.
@kwindex :under
If the tagged argument is @samp{:under} and the number of addresses is
less than @var{number}, the test is true; otherwise, it is false.
less than @var{count}, the test is true; otherwise, it is false.
If the tagged argument is not given, @samp{:over} is assumed.
@end deffn
@end deftypefn
@deftypefn Test {} spamd [:host @var{tcp-host}(string)] @
[:port @var{tcp-port}(number)] @
[:socket @var{unix-socket}(string)] @
[:user @var{name}(string)] @
[:over | :under @var{limit}(string)]
@subsubheading Synopsis
@smallexample
require "test-spamd";
@dots{}
if spamd @var{args}
@{
# @r{This is spam}
@dots{}
@}
@end smallexample
@subsubheading Description
This test is an interface to SpamAssassin filter. It connects to the
@command{spamd} daemon using connection parameters specified by tagged
arguments @code{:host} and @code{:port} (if the daemon is listening on
an INET socket), or @code{:socket} (if the daemon is listening on a
UNIX socket) and returns true, if SpamAssassin qualifies the message
as spam. Tagged argument @var{limit} alters the default behavior. Its
value is a string representation of a floating point number. If
the tag @code{:over} is used, then the test returns true if the spam
score returned from SpamAssassin is greater than @var{limit}.
Otherwise, if @code{:under} is used, the test returns true if the spam
score is less than @var{limit}. The comparison takes into account
three decimal digits.
Tagged argument @code{:user} allows to select a specific user profile.
If it is not given, the user name is determined using the effective
UID.
Before returning, the @code{spamd} test adds the following headers to
the message:
@table @asis
@item X-Spamd-Status
@samp{YES} or @samp{NO}, depending on whether the message is qualified
as spam or ham.
@item X-Spamd-Score
Actual spam score value.
@item X-Spamd-Threshold
Spam score threshold, as configured in SpamAssassin settings.
@item X-Spamd-Keywords
Comma-separated list of keywords, describing the spam checks that
succeeded for this message.
@end table
@subsubheading Example
@smallexample
request "test-spamd";
if spamd :host 127.0.0.1 :port 3333
@{
discard;
@}
@end smallexample
@end deftypefn
@deftypefn Test {} list [@var{comparator}] [@var{match-type}] @
[ :delim @var{delimiters}(string) ] @
@var{headers}(string-list) @var{keys}(string-list)
@subsubheading Synopsis
@smallexample
require "test-list";
if list @var{args}
@{
@dots{}
@}
@end smallexample
@subsubheading Description
The @code{list} test evaluates to true if any of @var{headers} match any
key from @var{keys}. Each header is regarded as containing a list of
keywords. By default, comma is assumed as list separator. This can be
overridden by specifying the @code{:delim} tag, whose value is a
string consisting of valid list delimiter characters.
@subsubheading Example
This test can be used in conjunction with the @code{spamd} test
described above:
@smallexample
require ["fileinto", "test-spamd", "test-list"];
if spamd :host 127.0.0.1 :port 3333
@{
if list :matches :delim " ,"
"X-Spamd-Keywords" [ "HTML_*", "FORGED_*" ]
@{
fileinto "~/mail/spam";
@}
else
@{
discard;
@}
@}
@end smallexample
@end deftypefn
@deftypefn Test {} timestamp [:before | :after] @
@var{header}(string) @var{date}(string)
@subsubheading Synopsis
@smallexample
require "test-timestamp";
if timestamp @var{arg}
@{
@dots{}
@}
@end smallexample
@subsubheading Description
The @code{timestamp} test compares the value of a structured date header
field (@var{header}) with the given date (@var{date}).
If the tagged argument is @code{:after} and the date from the header is
after the specified date the result is true, otherwise, if the header
date is before the given date, the result is false.
If the tagged argument is @code{:before} and the date from the header is
before the specified date the result is true, otherwise, if the header
date is after the given date, the result is false.
If no tagged argument is supplied, @code{:after} is assumed.
Almost any date format is understood. @xref{Date Input Formats}, for
a detailed information on date formats.
@subsubheading Example
The test below succeeds if the date in @samp{X-Expire-Timestamp}
header is more than 5 days older than the current date:
@smallexample
require "test-timestamp";
if timestamp :before "X-Expire-Timestamp" "now - 5 days"
@{
discard;
@}
@end smallexample
@end deftypefn
@node Actions
@section Actions
There are two groups of GNU Sieve actions: @dfn{built-in actions},
which are defined within the library, and @dfn{external actions}, i.e.
loadable modules that can be linked in at run time using the
@code{require} statement (@pxref{Require Statement}).
The @sc{gnu} libsieve supports the following default actions:
@menu
* Built-in Actions::
* External Actions::
@end menu
@node Built-in Actions
@subsection Built-in Actions
The GNU libsieve supports the following built-in actions:
@itemize
@item stop
......@@ -929,6 +1172,7 @@ if header :contains ["from"] ["idiot@@example.edu"]
@end smallexample
@end deffn
@anchor{fileinto}
@deffn Action fileinto [:permissions @var{mode}] @var{folder}
@noindent
......@@ -948,12 +1192,12 @@ Specifies the permissions to use, if the mailbox is created.
@end table
The @code{fileinto} action delivers the message into the specified
folder. If the folder is local, it is created using permissions
@samp{0600}, for regular files, and @samp{0700} for directories. This
default can be changed by using the @code{:permissions} tag. Its
folder. If the folder is local, it is created using permissions
@samp{0600}, for regular files, and @samp{0700} for directories. This
default can be changed by using the @code{:permissions} tag. Its
argument is a mode specification, similar to that used by
@command{chmod} shell utility. It is a list of permissions settings
separated by commas. Each setting begins with one of the following
@command{chmod} shell utility. It is a list of permissions settings
separated by commas. Each setting begins with one of the following
letters:
@table @asis
......@@ -965,7 +1209,7 @@ Set permissions for users not in the file's group.
@end table
This letter must be followed by either @samp{+} or @samp{=} and the
list of permissions to be set. This latter list is a string
list of permissions to be set. This latter list is a string
containing any one or both of the following characters:
@table @asis
......@@ -993,17 +1237,17 @@ value.
@item
Only @code{r} and @code{w} permissions can be set, since other
permissions do not seem to be useful for mailboxes. However, for
permissions do not seem to be useful for mailboxes. However, for
mailboxes that have a directory structure (such as maildir and MH),
any settings in @samp{g} and @samp{o} sets imply setting the
executable bit.
@item
Owner's permissions cannot be set. The owner always has all
Owner's permissions cannot be set. The owner always has all
permissions on the mailbox he created.
@item
The @code{:permissions} settings apply only to local mailboxes. They
The @code{:permissions} settings apply only to local mailboxes. They
are ignored for remote mailboxes.
@end enumerate
......@@ -1056,7 +1300,8 @@ coyote@@desert.example.org.
Message was refused by recipient's mail filtering program.
Reason given was as follows:
I am not taking mail from you, and I don't want your birdseed, either!
I am not taking mail from you, and I don't want your
birdseed, either!
----- =_aaaaaaaaaa0
Content-Type: message/delivery-status
......@@ -1098,26 +1343,169 @@ if header :mime :matches "Content-Type"
@end deffn
@deffn Action redirect @var{address}
@noindent
The @code{redirect} action is used to send the message to another user at
a supplied @var{address}, as a mail forwarding feature does. This action
a supplied @var{address}, as a mail forwarding feature does. This action
makes no changes to the message body or existing headers, but it may add
new headers. It also modifies the envelope recipient.
The @code{redirect} command performs an MTA-style ``forward'' --- that
is, what you get from a @file{.forward} file using @code{sendmail} under
@sc{unix}. The address on the SMTP envelope is replaced with the one on
@sc{unix}. The address on the SMTP envelope is replaced with the one on
the @code{redirect} command and the message is sent back
out. @emph{Notice}, that it differs from the MUA-style forward, which
creates a new message with a different sender and message ID, wrapping
the old message in a new one.
@end deffn
@node External Actions
@subsection External Actions
@UNREVISED
GNU Mailutils is shipped with a set of external Sieve
actions. These actions are compiled as loadable modules and must be
required prior to use (@pxref{Require Statement}).
@deftypefn Action {} moderator [:keep] [:address @var{address}(string)] @
[:source @var{sieve-file}(string)]
@subsubheading Synopsis
@smallexample
require "moderator"
moderator @var{args};
@end smallexample
@subsubheading Description
@cindex mailman
This action is a moderator robot for Mailman-driven mail archives.
A Mailman moderation request is a MIME message consisting of the
following three parts:
@multitable @columnfractions 0.2 0.4 0.4
@headitem N @tab Content-Type @tab Description
@item 1 @tab text/plain @tab Introduction for the human reader.
@item 2 @tab message/rfc822 @tab Original submission.
@item 3 @tab message/rfc822 @tab Mailman control message.
@end multitable
Replying to part 3 (keeping the subject intact) instructs Mailman to
discard the original submission.
Replying to part 3 while adding an `Approved:' header with the list
password in it approves the submission.
The @code{moderator} action spawns an inferior Sieve machine and
filters the original submission (part 2) through it. If the inferior
machine marks the message as deleted, the action replies to the
control message, thereby causing the submission to be discarded. The
@samp{From:} address of the reply can be modified using
@code{:address} tag. After discarding the message, @code{moderator}
marks it as deleted, unless it is given @code{:keep} tag.
The argument of @code{:source} tag, if given, specifies the Sieve
source file to be used on the message. If @code{:tag} is not present,
@code{moderator} will create and use a copy of the existing Sieve machine.
The action checks the message structure: it will bail out if the message
does not have exactly 3 MIME parts, or if parts 2 and 3 are not of
@samp{message/rfc822} type. It is the responsibility of the caller to
make sure the message is actually a valid Mailman moderation request
(see the example below).
@subsubheading Example
@smallexample
if allof(header :is "Sender" "mailman-bounces@@gnu.org",
header :is "X-List-Administrivia" "yes")
@{
moderator :source "~/.sieve/mailman.sv";
@}
@end smallexample
@end deftypefn
@deftypefn Action {} pipe [:envelope] @var{command}(string)
@subsubheading Synopsis
@smallexample
require "pipe";
if pipe @var{args}
@{
@dots{}
@}
@end smallexample
@subsubheading Description
The @code{pipe} action sends executes a command specified by its
argument and sends the entire message to its standard input. The
@var{command} argument supplies the command line.
The envelope of the message is included, if the @code{:envelope} tag
is given.
@subsubheading Example
The example below uses the @command{maidag} utility
(@FIXME-pxref{maidag}) to forward the message to user @samp{gray} on
the machine @samp{mail.gnu.org}.
@smallexample
require "pipe";
pipe "/usr/sbin/maidag --url smtp://gray@@mail.gnu.org"
@end smallexample
@end deftypefn
@deftypefn Action {} vacation [:days @var{ndays}(number)] @
[:subject @var{subject}(string)] @
[:aliases @var{addrlist}(string-list)] @
[:addresses @var{noreply-address}(string-list)] @
[:reply_regex @var{expr}(string)] @
[:reply_prefix @var{prefix}(string)] @
@var{reply-text}(string)
@subsubheading Syntax
@smallexample
require "vacation";
vacation @var{args};
@end smallexample
@subsubheading Description
The @code{vacation} action returns a message with @var{reply-text} to
the sender. It is intended to inform the sender that the recipient is
not currently reading his mail.
If the @code{:subject} tag is given, its argument sets the subject of
the message. Otherwise, the subject is formed by prefixing original
subject with @samp{Re:}, or @var{prefix}, given with the
@code{:reply_prefix} tag. Before prefixing, any original prefixes
matching extended regular expression @var{expr} (@code{:reply_regex}
tag) are stripped from the subject line. If @code{:reply_regex} is not
specified, the default regexp is @samp{^re: *}.
The @code{:aliases} tag instructs @code{vacation} to handle messages
for any address in @var{addrlist} in the same manner as those received
for the user's principal email.
Before processing, @code{vacation} compares the sender address with
its @dfn{address exclusion list}. Elements of this list are extended
case-insensitive regular expressions. If the sender address matches
any of these expressions, the message will not be replied. The default
exclusion list is:
@smallexample
.*-REQUEST@@.*
.*-RELAY@@.*
.*-OWNER@@.*
^OWNER-.*
^postmaster@@.*
^UUCP@@.*
^MAILER@@.*
^MAILER-DAEMON@@.*
@end smallexample
New entries can be added to this list using @code{:addresses} tag.
The @code{:days} tag sets the @dfn{reply interval}. A reply is sent to
each sender once in @var{ndays} days. GNU Sieve keeps track of
sender addresses and dates in a DBM file @file{.vacation} stored in
the user's home directory. This tag is available only if Mailutils is
compiled with DBM support.
@end deftypefn
@node GNU Extensions
@section GNU Extensions
This section summarizes the @sc{gnu} extensions to the sieve language
This section summarizes the GNU extensions to the sieve language
@enumerate 1
@item Multiline strings syntax
......@@ -1143,7 +1531,7 @@ be performed within a string.
@itemize
@item According to the RFC an error must occur if a @code{require} appears
after a command other than @code{require}. The @sc{gnu} sieve library allows
after a command other than @code{require}. The GNU sieve library allows
interspersing the @code{require} and other statements. The only
requirement is that @code{require} must occur before a statement that is
using the required capability (@pxref{Require Statement}).
......@@ -1168,10 +1556,15 @@ The only value that can be meaningfully used as the first required
argument of an @code{envelope} test is @samp{from}. This limitation
may disappear from the subsequent releases.
@item @code{fileinto} action
The @code{fileinto} action allows to specify permissons on the mailbox,
in case it is created (@pxref{fileinto}).
@item Match type optional argument.
Along with the usual @code{:is}, @code{:matches} and @code{contains}
matching type, @sc{gnu} sieve library understands @code{:regex} type. This
matching type, GNU sieve library understands @code{:regex} type. This
matching type toggles POSIX Extended Regular Expression matching.
@end enumerate
......
......@@ -11,7 +11,7 @@ properly.
@subsubheading POP3
The POP URL scheme contains a POP server, optional port number
and the authentication mechanism. The general form is
and the authentication mechanism. The general form is
@smallexample
@group
......@@ -91,7 +91,7 @@ If @emph{:port} is omitted the default value is 993.
@subsubheading File
Local folder should be handle by this URL. It is preferable to let
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.
......
......@@ -124,9 +124,9 @@ $ @kbd{ARGP_HELP_FMT=long-opt-col=16 sieve --help|grep ADDRESS}
@end deftypevr
@deftypevr {Help Output} offset doc-opt-col
Column in which @dfn{doc options} start. A doc option isn't actually
Column in which @dfn{doc options} start. A doc option isn't actually
an option, but rather an arbitrary piece of documentation that is
displayed in much the same manner as the options. For example, in
displayed in much the same manner as the options. For example, in
the output of @command{folder --help}:
@verbatim
......@@ -138,7 +138,7 @@ GNU MH folder
@end verbatim
@noindent
the string @samp{Actions are:} is a doc option. Thus, if you set
the string @samp{Actions are:} is a doc option. Thus, if you set
@kbd{ARGP_HELP_FMT=doc-opt-col=6} the above part of the help output
will look as follows:
......@@ -172,8 +172,8 @@ Notice, that the description starts on a separate line if
@end deftypevr
@deftypevr {Help Output} offset header-col
Column in which @dfn{group headers} are printed. A group header is a
descriptive text preceding an option group. For example, in the
Column in which @dfn{group headers} are printed. A group header is a
descriptive text preceding an option group. For example, in the
following text:
@verbatim
......
......@@ -80,9 +80,9 @@ main (int argc, char **argv)
/* Registration. */
mu_registrar_record (mu_imap_record);
mu_registrar_record (mu_mbox_record);
mu_registrar_record (mu_path_record);
mu_registrar_record (mu_pop_record);
mu_registrar_record (mu_mbox_record);
mu_registrar_set_default_record (mu_mbox_record);
MU_ASSERT (mu_mailbox_create_default (&mbox, mailbox_name));
......
......@@ -250,9 +250,10 @@ make_tmp (FILE *input, const char *from, char **tempfile)
void
register_handlers ()
{
mu_registrar_record (mu_path_record);
mu_registrar_record (mu_mbox_record);
mu_registrar_record (mu_sendmail_record);
mu_registrar_record (mu_smtp_record);
mu_registrar_set_default_record (mu_mbox_record);
}
int
......
......@@ -27,7 +27,7 @@ debug.h: $(top_srcdir)/scripts/debugdef.m4 debug.hm4
m4 $(top_srcdir)/scripts/debugdef.m4 debug.hm4 > debug.h
types.h: $(top_srcdir)/include/mailutils/types.hin Makefile
sed 's/MU_OFF_TYPE/$(MU_OFF_TYPE)/' $(top_srcdir)/include/mailutils/types.hin > $@
sed 's/_MU_OFF_TYPE_/$(MU_OFF_TYPE)/;s/_MU_DEFAULT_RECORD_/$(MU_DEFAULT_RECORD)/' $(top_srcdir)/include/mailutils/types.hin > $@
DISTCLEANFILES = types.h
pkginclude_DATA = types.h
......
......@@ -35,10 +35,6 @@ const char *mu_mailbox_url (void);
const char *mu_folder_directory (void);
int mu_construct_user_mailbox_url (char **pout, const char *name);
/* Default mailbox protocol */
int mu_mailbox_set_default_proto (const char *proto);
const char *mu_mailbox_get_default_proto (void);
/* Constructor/destructor and possible types. */
extern int mu_mailbox_create (mu_mailbox_t *, const char *);
extern int mu_mailbox_create_from_url (mu_mailbox_t *, mu_url_t);
......
......@@ -47,9 +47,18 @@ struct _mu_record
int (*_list_p) (mu_record_t, const char *, int);
};
/* Defaults */
extern int mu_registrar_set_default_scheme (const char *scheme);
extern const char *mu_registrar_get_default_scheme (void);
extern int mu_registrar_get_default_record (mu_record_t *prec);
extern void mu_registrar_set_default_record (mu_record_t record);
/* Registration. */
extern int mu_registrar_get_iterator (mu_iterator_t *);
extern int mu_registrar_get_list (mu_list_t *) __attribute__ ((deprecated));
extern int mu_registrar_lookup_scheme (const char *scheme,
mu_record_t *precord);
extern int mu_registrar_lookup (const char *name, int flags,
mu_record_t *precord, int *pflags);
......@@ -101,8 +110,6 @@ extern mu_record_t mu_nntp_record;
/* Local Mailbox Unix Mailbox, "mbox:" */
extern mu_record_t mu_mbox_record;
/* Local Folder/Mailbox, / */
extern mu_record_t mu_path_record;
/* Local MH, "mh:" */
extern mu_record_t mu_mh_record;
/* Maildir, "maildir:" */
......@@ -131,7 +138,6 @@ extern mu_record_t mu_sendmail_record;
extern mu_record_t mu_prog_record;
#define mu_register_all_mbox_formats() do {\
mu_registrar_record (mu_path_record);\
mu_registrar_record (mu_mbox_record);\
mu_registrar_record (mu_pop_record);\
mu_registrar_record (mu_pops_record);\
......@@ -139,13 +145,14 @@ extern mu_record_t mu_prog_record;
mu_registrar_record (mu_imaps_record);\
mu_registrar_record (mu_mh_record);\
mu_registrar_record (mu_maildir_record);\
mu_registrar_set_default_record (MU_DEFAULT_RECORD);\
} while (0)
#define mu_register_local_mbox_formats() do {\
mu_registrar_record (mu_path_record);\
mu_registrar_record (mu_mbox_record);\
mu_registrar_record (mu_mh_record);\
mu_registrar_record (mu_maildir_record);\
mu_registrar_set_default_record (MU_DEFAULT_RECORD);\
} while (0)
#define mu_register_remote_mbox_formats() do {\
......
......@@ -71,7 +71,7 @@ struct _mu_acl;
struct _mu_server;
struct _mu_tcp_server;
typedef MU_OFF_TYPE mu_off_t;
typedef _MU_OFF_TYPE_ mu_off_t;
typedef struct _mu_address *mu_address_t;
typedef struct _mu_attribute *mu_attribute_t;
......@@ -121,6 +121,8 @@ typedef struct _mu_progmailer *mu_progmailer_t;
#define mu_offsetof(s,f) ((size_t)&((s*)0)->f)
#define MU_ARRAY_SIZE(a) (sizeof(a)/sizeof((a)[0]))
#define MU_DEFAULT_RECORD _MU_DEFAULT_RECORD_
#ifdef __cplusplus
}
......
......@@ -219,5 +219,6 @@ mu_scm_init ()
mu_scm_mime_init ();
#include "mu_scm.x"
mu_registrar_record (mu_path_record);
mu_registrar_record (MU_DEFAULT_RECORD);
mu_registrar_set_default_record (MU_DEFAULT_RECORD);
}
......
......@@ -46,94 +46,73 @@
/* We export url parsing and the initialisation of
the mailbox, via the register entry/record. */
static struct _mu_record _mbox_record =
{
MU_MBOX_PRIO,
MU_MBOX_SCHEME,
mu_url_expand_path, /* URL init. */
_mailbox_mbox_init, /* Mailbox init. */
NULL, /* Mailer init. */
_folder_mbox_init, /* Folder init. */
NULL, /* No need for an back pointer. */
NULL, /* _is_scheme method. */
NULL, /* _get_url method. */
NULL, /* _get_mailbox method. */
NULL, /* _get_mailer method. */
NULL /* _get_folder method. */
};
mu_record_t mu_mbox_record = &_mbox_record;
static int
_path_is_scheme (mu_record_t record, mu_url_t url, int flags)
_mbox_is_scheme (mu_record_t record, mu_url_t url, int flags)
{
int rc = 0;
if (url && record->scheme)
if (mu_url_is_scheme (url, record->scheme))
return MU_FOLDER_ATTRIBUTE_FILE & flags;
if (mu_scheme_autodetect_p (url))
{
if (mu_scheme_autodetect_p (url))
{
struct stat st;
const char *path;
struct stat st;
const char *path;
mu_url_sget_path (url, &path);
if (stat (path, &st) < 0)
mu_url_sget_path (url, &path);
if (stat (path, &st) < 0)
return 0;
if (S_ISREG (st.st_mode) || S_ISCHR (st.st_mode))
{
if (st.st_size == 0)
{
if (errno == ENOENT)
rc |= MU_FOLDER_ATTRIBUTE_FILE;
return rc;
rc |= MU_FOLDER_ATTRIBUTE_FILE;
}
if (S_ISREG (st.st_mode) || S_ISCHR (st.st_mode))
else if (flags & MU_FOLDER_ATTRIBUTE_FILE)
{
if (st.st_size == 0)
#if 0
/* This effectively sieves out all non-mailbox files,
but it makes mu_folder_enumerate crawl, which is
intolerable for imap4d LIST command. */
int fd = open (path, O_RDONLY);
if (fd != -1)
{
rc |= MU_FOLDER_ATTRIBUTE_FILE;
char buf[5];
if (read (fd, buf, 5) == 5)
if (memcmp (buf, "From ", 5) == 0)
rc |= MU_FOLDER_ATTRIBUTE_FILE;
close (fd);
}
else if (flags & MU_FOLDER_ATTRIBUTE_FILE)
{
#if 0
/* This effectively sieves out all non-mailbox files,
but it makes mu_folder_enumerate crawl, which is
intolerable for imap4d LIST command. */
int fd = open (path, O_RDONLY);
if (fd != -1)
{
char buf[5];
if (read (fd, buf, 5) == 5)
if (memcmp (buf, "From ", 5) == 0)
rc |= MU_FOLDER_ATTRIBUTE_FILE;
close (fd);
}
#else
rc |= MU_FOLDER_ATTRIBUTE_FILE;
rc |= MU_FOLDER_ATTRIBUTE_FILE;
#endif
}
}
if ((flags & MU_FOLDER_ATTRIBUTE_DIRECTORY)
&& S_ISDIR (st.st_mode))
rc |= MU_FOLDER_ATTRIBUTE_DIRECTORY;
}
if ((flags & MU_FOLDER_ATTRIBUTE_DIRECTORY)
&& S_ISDIR (st.st_mode))
rc |= MU_FOLDER_ATTRIBUTE_DIRECTORY;
}
return rc;
}
static struct _mu_record _path_record =
static struct _mu_record _mbox_record =
{
MU_PATH_PRIO,
MU_PATH_SCHEME,
NULL, /* URL init. */
MU_MBOX_PRIO,
MU_MBOX_SCHEME,
mu_url_expand_path, /* URL init. */
_mailbox_mbox_init, /* Mailbox init. */
NULL, /* Mailer init. */
_folder_mbox_init, /* Folder init. */
NULL, /* No need for an owner. */
_path_is_scheme, /* is_scheme method. */
NULL, /* get_url method. */
NULL, /* get_mailbox method. */
NULL, /* get_mailer method. */
NULL /* get_folder method. */
NULL, /* Mailer init. */
_folder_mbox_init, /* Folder init. */
NULL, /* No need for an back pointer. */
_mbox_is_scheme, /* _is_scheme method. */
NULL, /* _get_url method. */
NULL, /* _get_mailbox method. */
NULL, /* _get_mailer method. */
NULL /* _get_folder method. */
};
mu_record_t mu_path_record = &_path_record;
mu_record_t mu_mbox_record = &_mbox_record;
/* lsub/subscribe/unsubscribe are not needed. */
static void folder_mbox_destroy (mu_folder_t);
......
......@@ -533,7 +533,7 @@ perms_tag_checker (const char *name, mu_list_t tags, mu_list_t args)
mu_iterator_next (itr))
{
int flag;
char *p;
const char *p;
mu_sieve_runtime_tag_t *t;
mu_iterator_current (itr, (void **)&t);
if (strcmp (t->tag, "permissions") == 0)
......
......@@ -16,8 +16,12 @@
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301 USA */
/* Syntax: pipe [:envelope] <program call: string>
/* Syntax: pipe [:envelope] <program: string>
The pipe action executes a shell command specified by its
argument and pipes the entire message to its standard input.
The envelope of the message is included, if the :envelope tag is given.
Notes/FIXME: 1. it would be nice to implement meta-variables in
<program call> which would expand to various
items from the message being handled.
......
......@@ -232,7 +232,7 @@ sigpipe_handler (int sig MU_ARG_UNUSED)
/* The test proper */
/* Syntax: spamd [":host" <tcp-host: string]
/* Syntax: spamd [":host" <tcp-host: string>]
[":port" <tcp-port: number> /
":socket" <unix-socket: string>]
[":user" <name: string>]
......
......@@ -23,7 +23,7 @@
[:reply_regex <expr: string>]
[:reply_prefix <prefix: string>]
<reply text: string>
*/
*/
#ifdef HAVE_CONFIG_H
# include <config.h>
......
......@@ -32,6 +32,7 @@
#include <mailutils/nls.h>
#include <mailutils/debug.h>
#include <mailutils/syslog.h>
#include <mailutils/registrar.h>
#include <syslog.h>
int mu_load_user_rcfile = 1;
......@@ -73,7 +74,7 @@ mu_gocs_mailbox_init (void *data)
}
if (p->mailbox_type)
{
if (mu_mailbox_set_default_proto (p->mailbox_type))
if (mu_registrar_set_default_scheme (p->mailbox_type))
mu_error (_("Invalid mailbox type: %s"), p->mailbox_type);
free (p->mailbox_type);
p->mailbox_type = NULL;
......
......@@ -77,44 +77,6 @@ mailbox_folder_create (mu_mailbox_t mbox, const char *name,
return rc;
}
static char *default_proto;
int
mu_mailbox_set_default_proto (const char *proto)
{
char *p;
size_t len = strlen (proto);
if (proto [len - 1] == ':')
{
p = strdup (proto);
if (!p)
return ENOMEM;
}
else
{
p = malloc (len + 2);
if (!p)
return ENOMEM;
strcpy (p, proto);
p[len] = ':';
p[len+1] = 0;
}
if (mu_registrar_lookup (p, MU_FOLDER_ATTRIBUTE_FILE, NULL, NULL))
return MU_ERR_NO_HANDLER;
if (default_proto)
free (default_proto);
default_proto = p;
return 0;
}
const char *
mu_mailbox_get_default_proto ()
{
return default_proto ? default_proto : "/";
}
static int
_create_mailbox0 (mu_mailbox_t *pmbox, mu_url_t url, const char *name)
{
......@@ -235,22 +197,10 @@ _create_mailbox (mu_mailbox_t *pmbox, const char *name)
int
mu_mailbox_create (mu_mailbox_t *pmbox, const char *name)
{
int rc;
if (pmbox == NULL)
return MU_ERR_OUT_PTR_NULL;
if (!mu_is_proto (name) && default_proto)
{
char *tmp_name = malloc (strlen (default_proto) + strlen (name) + 1);
strcpy (tmp_name, default_proto);
strcat (tmp_name, name);
rc = _create_mailbox (pmbox, tmp_name);
free (tmp_name);
}
else
rc = _create_mailbox (pmbox, name);
return rc;
return _create_mailbox (pmbox, name);
}
int
......
......@@ -35,7 +35,7 @@
#include <mailutils/nls.h>
#include <mailutils/error.h>
#include <mailutils/url.h>
#include <mailutils/mutil.h>
#include <registrar0.h>
/* NOTE: We will leak here since the monitor and the registrar will never
......@@ -43,6 +43,44 @@
static mu_list_t registrar_list;
struct mu_monitor registrar_monitor = MU_MONITOR_INITIALIZER;
static mu_record_t mu_default_record;
void
mu_registrar_set_default_record (mu_record_t record)
{
mu_default_record = record;
}
int
mu_registrar_get_default_record (mu_record_t *prec)
{
if (mu_default_record)
{
if (prec)
*prec = mu_default_record;
return 0;
}
return MU_ERR_NOENT;
}
int
mu_registrar_set_default_scheme (const char *scheme)
{
int status;
mu_record_t rec;
status = mu_registrar_lookup_scheme (scheme, &rec);
if (status == 0)
mu_default_record = rec;
return status;
}
const char *
mu_registrar_get_default_scheme ()
{
return mu_default_record ? mu_default_record->scheme : NULL;
}
static int
_registrar_get_list (mu_list_t *plist)
{
......@@ -91,6 +129,34 @@ mu_registrar_get_iterator (mu_iterator_t *pitr)
}
int
mu_registrar_lookup_scheme (const char *scheme, mu_record_t *precord)
{
size_t len;
mu_iterator_t iterator;
int status = mu_registrar_get_iterator (&iterator);
if (status != 0)
return status;
status = MU_ERR_NOENT;
len = strcspn (scheme, ":");
for (mu_iterator_first (iterator); !mu_iterator_is_done (iterator);
mu_iterator_next (iterator))
{
mu_record_t record;
mu_iterator_current (iterator, (void **)&record);
if (strlen (record->scheme) == len
&& memcmp (record->scheme, scheme, len) == 0)
{
if (precord)
*precord = record;
status = 0;
break;
}
}
mu_iterator_destroy (&iterator);
return status;
}
int
mu_registrar_lookup_url (mu_url_t url, int flags,
mu_record_t *precord, int *pflags)
{
......@@ -116,6 +182,17 @@ mu_registrar_lookup_url (mu_url_t url, int flags,
}
}
mu_iterator_destroy (&iterator);
if (status &&
/*s FIXME: This check is not enough. */
!mu_is_proto (mu_url_to_string (url))
&& mu_registrar_get_default_record (precord) == 0)
{
status = 0;
if (pflags)
*pflags = flags & MU_FOLDER_ATTRIBUTE_FILE; /* FIXME? */
}
return status;
}
......
......@@ -47,6 +47,7 @@ static struct mu_conf_option mu_conf_option[] = {
{ "VERSION=" VERSION, N_("Version of this package") },
{ "SYSCONFDIR=" SYSCONFDIR, N_("System configuration directory") },
{ "MAILSPOOLDIR=" MU_PATH_MAILDIR, N_("Default mail spool directory") },
{ "SCHEME=" MU_DEFAULT_SCHEME, N_("Default mailbox type") },
{ "LOG_FACILITY=" LOG_FACILITY_STRING, N_("Default syslog facility") },
#ifdef USE_LIBPAM
{ "USE_LIBPAM", N_("PAM support") },
......