Next: Interfaces to Third-Party Programs, Previous: Passwd functions, Up: Library [Contents][Index]
‘Sieve’ is a powerful mail filtering language, defined in
RFC 3028. Mailfromd
supports an extended form
of this language. For a description of the language and available
extensions, see Sieve Language in GNU Mailutils Manual.
Compile the Sieve program script and execute it over the message identified by the descriptor nmsg.
Optional flags modify the behavior of the function. It is a
bit-mask field, consisting of a bitwise or
of one or more of
the following flags, defined in sieve.mfl:
MF_SIEVE_FILE
The script argument specifies the name of a Sieve program file. This is the default.
MF_SIEVE_TEXT
The script argument is a string containing entire Sieve program. Optional arguments file and line can be used to fix source locations in Sieve diagnostic messages (see below).
MF_SIEVE_LOG
Log every executed ‘Sieve’ action.
MF_SIEVE_DEBUG_TRACE
Trace execution of ‘Sieve’ tests.
MF_SIEVE_DEBUG_INSTR
Log every instruction, executed in the compiled ‘Sieve’ code. This produces huge amounts of output and is rarely useful, unless you suspect some bug in ‘Sieve’ implementation and wish to trace it.
For example, MF_SIEVE_LOG|MF_SIEVE_DEBUG_TRACE
enables logging
‘Sieve’ actions and tests.
The sieve
function returns true
if the message was
accepted by the script program, and false
otherwise.
Here, the word accepted means that some form of ‘KEEP’
action (see Actions in GNU Mailutils
Manual) was executed over the message.
While executing the Sieve script, Sieve environment (RFC 5183) is initialized as follows:
The domain name of the server Sieve is running on.
Host name of the server Sieve is running on.
The string ‘MTA’.
The string ‘GNU Mailutils’.
The string ‘pre’.
Defined to the value of ‘client_ptr’ macro, if it was required.
Defined to the value of ‘client_addr’ macro, if it was required.
The version of GNU Mailutils.
The following example discards each message not accepted by the ‘Sieve’ program /etc/mail/filter.siv:
require 'sieve' group eom do if not sieve(current_message(), "/etc/mail/filter.siv", MF_SIEVE_LOG) discard fi done
The Sieve program can be embedded in the MFL filter, as shown in the example below:
require 'sieve' prog eom do if not sieve(current_message(), "require \"fileinto\";\n" "fileinto \"/tmp/sieved.mbox\";", MF_SIEVE_TEXT | MF_SIEVE_LOG) discard fi done
In such cases, any Sieve diagnostics (error messages, traces, etc.)
will be marked with the locations relative to the line where the call
to sieve
appears. For example, the above program produces the
following in the log:
prog.mfl:7: FILEINTO; delivering into /tmp/sieved.mbox
Notice, that the line number correctly refers to the line where the
fileinto
action appears in the source. However, there are
cases where the reported line number is incorrect. This happens,
for instance, if script is a string variable defined elsewhere.
To handle such cases, sieve
accepts two optional parameters
which are used to compute the location in the Sieve program. The
file parameter specifies the file name where the definition of
the program appears, and the line parameter gives the number of
line in that file where the program begins. For example:
require 'sieve' const sieve_prog_line __line__ + 2 string sieve_prog <<EOT require "fileinto"; fileinto "/tmp/sieved.mbox"; EOT prog eom do if not sieve(current_message(), sieve_prog, MF_SIEVE_TEXT | MF_SIEVE_LOG, __file__, sieve_prog_line) discard fi done
The actual Sieve program begins two lines below the
sieve_prog_line
constant definition, which is reflected in its
initialization.
Next: Interfaces to Third-Party Programs, Previous: Passwd functions, Up: Library [Contents][Index]