diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/mailfromd.texi | 98 |
1 files changed, 96 insertions, 2 deletions
diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi index 731c4ae1..95c6741f 100644 --- a/doc/mailfromd.texi +++ b/doc/mailfromd.texi @@ -223,2 +223,3 @@ Built-in and Library Functions * System functions:: +* Sieve Interface:: * Interfaces to Third-Party Programs:: @@ -987,3 +988,2 @@ the corresponding section below. @cindex Upgrading from 4.1 to 4.2 -@UNREVISED{} Upgrading to this version does not require any special efforts. You @@ -5260,2 +5260,3 @@ in version @value{VERSION}. * System functions:: +* Sieve Interface:: * Interfaces to Third-Party Programs:: @@ -6479,4 +6480,97 @@ the return status of the command otherwise. @end deftypefn - +@node Sieve Interface +@subsubsection Sieve Interface +@cindex Sieve +@UNREVISED{} + @samp{Sieve} is a powerful mail filtering language, defined in +@acronym{RFC} 3028. @command{Mailfromd} supports an extended form +of this language. For description of the language and available +extensions, @xref{Sieve Language, Sieve Language, Sieve Language, +mailutils, GNU Mailutils Manual}. + +@deftypefn {Built-in Function} boolean sieve (string @var{script} @ + [, number @var{flags}]) +Compile the Sieve source file @var{script} and execute it over the +collected message. This function can be used only in @code{eom} +handler. + +@findex sieve.mfh +Optional @var{flags} define additional debugging and verbosity +settings. It is a bit-mask field, consisting of a bitwise @code{or} +of one or more of the following flags, defined in @file{sieve.mfh}: + +@table @code +@item MF_SIEVE_LOG +Log every executed @samp{Sieve} action. + +@item MF_SIEVE_DEBUG_TRACE +Trace execution of @samp{Sieve} tests. + +@item MF_SIEVE_DEBUG_INSTR +Log every instruction, executed in the compiled @samp{Sieve} code. +This produces huge amounts of output and is rarely useful, unless you +suspect some bug in @samp{Sieve} implementation and wish to trace it. + +@item MF_SIEVE_DEBUG_MAILUTILS +Log debugging information about the underlying Mailutils calls. + +@item MF_SIEVE_DEBUG_PROT +Trace networking protocols. +@end table + +For example, @code{MF_SIEVE_LOG|MF_SIEVE_DEBUG_TRACE} enables logging +@samp{Sieve} actions and tests. + +The @code{sieve} function returns @code{true} if the message was +accepted by the @var{script} program, and @code{false} otherwise. +Here, the word @dfn{accepted} means that some form of @samp{KEEP} +action (@pxref{Actions, keep, Actions, mailutils, GNU Mailutils +Manual}) was executed over the message. +@end deftypefn + +The following example discards each message not accepted by the +@samp{Sieve} program @file{/etc/mail/filter.siv}: + +@smallexample +#include_once <sieve.mfh> +group eom +do + if not sieve("/etc/mail/filter.siv", MF_SIEVE_LOG) + discard + fi +done +@end smallexample + +The example below illustrates how one can adjust logging flags +depending on the current debugging level: + +@smallexample +#include_once <sieve.mfh> +prog eom +do + number flags 0 + number level debug_level("bi_sieve") + if %level >= 1 + set flags %flags | MF_SIEVE_LOG + fi + if %level >= 2 + set flags %flags | MF_SIEVE_DEBUG_TRACE + fi + if %level > 9 + set flags %flags | MF_SIEVE_DEBUG_INSTR + fi + if %level > 19 + set flags %flags | MF_SIEVE_DEBUG_MAILUTILS + fi + if %level > 20 + set flags %flags | MF_SIEVE_DEBUG_PROT + fi + + if not sieve("/etc/mail/filter.siv", %flags) + discard + fi +done +@end smallexample + @node Interfaces to Third-Party Programs |