diff options
Diffstat (limited to 'doc/mailfromd.texi')
-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 | |||
@@ -221,6 +221,7 @@ Built-in and Library Functions | |||
221 | * Database functions:: | 221 | * Database functions:: |
222 | * I/O functions:: | 222 | * I/O functions:: |
223 | * System functions:: | 223 | * System functions:: |
224 | * Sieve Interface:: | ||
224 | * Interfaces to Third-Party Programs:: | 225 | * Interfaces to Third-Party Programs:: |
225 | * Special test functions:: | 226 | * Special test functions:: |
226 | * Mail Sending Functions:: | 227 | * Mail Sending Functions:: |
@@ -985,7 +986,6 @@ the corresponding section below. | |||
985 | @node 410-420 | 986 | @node 410-420 |
986 | @section Upgrading from 4.1 to 4.2 | 987 | @section Upgrading from 4.1 to 4.2 |
987 | @cindex Upgrading from 4.1 to 4.2 | 988 | @cindex Upgrading from 4.1 to 4.2 |
988 | @UNREVISED{} | ||
989 | Upgrading to this version does not require any special efforts. You | 989 | Upgrading to this version does not require any special efforts. You |
990 | can use your configuration files and filter scripts without any | 990 | can use your configuration files and filter scripts without any |
991 | changes. The only difference worth noticing is that starting from this | 991 | changes. The only difference worth noticing is that starting from this |
@@ -5258,6 +5258,7 @@ in version @value{VERSION}. | |||
5258 | * Database functions:: | 5258 | * Database functions:: |
5259 | * I/O functions:: | 5259 | * I/O functions:: |
5260 | * System functions:: | 5260 | * System functions:: |
5261 | * Sieve Interface:: | ||
5261 | * Interfaces to Third-Party Programs:: | 5262 | * Interfaces to Third-Party Programs:: |
5262 | * Special test functions:: | 5263 | * Special test functions:: |
5263 | * Mail Sending Functions:: | 5264 | * Mail Sending Functions:: |
@@ -6477,8 +6478,101 @@ strftime('%Y-%m-%d %H:%M:%S %Z', 1164477564, 1) | |||
6477 | by calling @command{/bin/sh -c string}, and returns -1 on error or | 6478 | by calling @command{/bin/sh -c string}, and returns -1 on error or |
6478 | the return status of the command otherwise. | 6479 | the return status of the command otherwise. |
6479 | @end deftypefn | 6480 | @end deftypefn |
6480 | |||
6481 | 6481 | ||
6482 | @node Sieve Interface | ||
6483 | @subsubsection Sieve Interface | ||
6484 | @cindex Sieve | ||
6485 | @UNREVISED{} | ||
6486 | @samp{Sieve} is a powerful mail filtering language, defined in | ||
6487 | @acronym{RFC} 3028. @command{Mailfromd} supports an extended form | ||
6488 | of this language. For description of the language and available | ||
6489 | extensions, @xref{Sieve Language, Sieve Language, Sieve Language, | ||
6490 | mailutils, GNU Mailutils Manual}. | ||
6491 | |||
6492 | @deftypefn {Built-in Function} boolean sieve (string @var{script} @ | ||
6493 | [, number @var{flags}]) | ||
6494 | Compile the Sieve source file @var{script} and execute it over the | ||
6495 | collected message. This function can be used only in @code{eom} | ||
6496 | handler. | ||
6497 | |||
6498 | @findex sieve.mfh | ||
6499 | Optional @var{flags} define additional debugging and verbosity | ||
6500 | settings. It is a bit-mask field, consisting of a bitwise @code{or} | ||
6501 | of one or more of the following flags, defined in @file{sieve.mfh}: | ||
6502 | |||
6503 | @table @code | ||
6504 | @item MF_SIEVE_LOG | ||
6505 | Log every executed @samp{Sieve} action. | ||
6506 | |||
6507 | @item MF_SIEVE_DEBUG_TRACE | ||
6508 | Trace execution of @samp{Sieve} tests. | ||
6509 | |||
6510 | @item MF_SIEVE_DEBUG_INSTR | ||
6511 | Log every instruction, executed in the compiled @samp{Sieve} code. | ||
6512 | This produces huge amounts of output and is rarely useful, unless you | ||
6513 | suspect some bug in @samp{Sieve} implementation and wish to trace it. | ||
6514 | |||
6515 | @item MF_SIEVE_DEBUG_MAILUTILS | ||
6516 | Log debugging information about the underlying Mailutils calls. | ||
6517 | |||
6518 | @item MF_SIEVE_DEBUG_PROT | ||
6519 | Trace networking protocols. | ||
6520 | @end table | ||
6521 | |||
6522 | For example, @code{MF_SIEVE_LOG|MF_SIEVE_DEBUG_TRACE} enables logging | ||
6523 | @samp{Sieve} actions and tests. | ||
6524 | |||
6525 | The @code{sieve} function returns @code{true} if the message was | ||
6526 | accepted by the @var{script} program, and @code{false} otherwise. | ||
6527 | Here, the word @dfn{accepted} means that some form of @samp{KEEP} | ||
6528 | action (@pxref{Actions, keep, Actions, mailutils, GNU Mailutils | ||
6529 | Manual}) was executed over the message. | ||
6530 | @end deftypefn | ||
6531 | |||
6532 | The following example discards each message not accepted by the | ||
6533 | @samp{Sieve} program @file{/etc/mail/filter.siv}: | ||
6534 | |||
6535 | @smallexample | ||
6536 | #include_once <sieve.mfh> | ||
6537 | group eom | ||
6538 | do | ||
6539 | if not sieve("/etc/mail/filter.siv", MF_SIEVE_LOG) | ||
6540 | discard | ||
6541 | fi | ||
6542 | done | ||
6543 | @end smallexample | ||
6544 | |||
6545 | The example below illustrates how one can adjust logging flags | ||
6546 | depending on the current debugging level: | ||
6547 | |||
6548 | @smallexample | ||
6549 | #include_once <sieve.mfh> | ||
6550 | prog eom | ||
6551 | do | ||
6552 | number flags 0 | ||
6553 | number level debug_level("bi_sieve") | ||
6554 | if %level >= 1 | ||
6555 | set flags %flags | MF_SIEVE_LOG | ||
6556 | fi | ||
6557 | if %level >= 2 | ||
6558 | set flags %flags | MF_SIEVE_DEBUG_TRACE | ||
6559 | fi | ||
6560 | if %level > 9 | ||
6561 | set flags %flags | MF_SIEVE_DEBUG_INSTR | ||
6562 | fi | ||
6563 | if %level > 19 | ||
6564 | set flags %flags | MF_SIEVE_DEBUG_MAILUTILS | ||
6565 | fi | ||
6566 | if %level > 20 | ||
6567 | set flags %flags | MF_SIEVE_DEBUG_PROT | ||
6568 | fi | ||
6569 | |||
6570 | if not sieve("/etc/mail/filter.siv", %flags) | ||
6571 | discard | ||
6572 | fi | ||
6573 | done | ||
6574 | @end smallexample | ||
6575 | |||
6482 | @node Interfaces to Third-Party Programs | 6576 | @node Interfaces to Third-Party Programs |
6483 | @subsubsection Interfaces to Third-Party Programs | 6577 | @subsubsection Interfaces to Third-Party Programs |
6484 | 6578 | ||