summaryrefslogtreecommitdiffabout
path: root/doc/mailfromd.texi
Side-by-side diff
Diffstat (limited to 'doc/mailfromd.texi') (more/less context) (ignore whitespace changes)
-rw-r--r--doc/mailfromd.texi98
1 files changed, 96 insertions, 2 deletions
diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi
index 731c4ae..95c6741 100644
--- a/doc/mailfromd.texi
+++ b/doc/mailfromd.texi
@@ -221,6 +221,7 @@ Built-in and Library Functions
* Database functions::
* I/O functions::
* System functions::
+* Sieve Interface::
* Interfaces to Third-Party Programs::
* Special test functions::
* Mail Sending Functions::
@@ -985,7 +986,6 @@ the corresponding section below.
@node 410-420
@section Upgrading from 4.1 to 4.2
@cindex Upgrading from 4.1 to 4.2
-@UNREVISED{}
Upgrading to this version does not require any special efforts. You
can use your configuration files and filter scripts without any
changes. The only difference worth noticing is that starting from this
@@ -5258,6 +5258,7 @@ in version @value{VERSION}.
* Database functions::
* I/O functions::
* System functions::
+* Sieve Interface::
* Interfaces to Third-Party Programs::
* Special test functions::
* Mail Sending Functions::
@@ -6477,8 +6478,101 @@ strftime('%Y-%m-%d %H:%M:%S %Z', 1164477564, 1)
by calling @command{/bin/sh -c string}, and returns -1 on error or
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
@subsubsection Interfaces to Third-Party Programs

Return to:

Send suggestions and report system problems to the System administrator.