3.8.1 A Sieve Interpreter

Sieve interpreter sieve allows to apply Sieve scripts to an arbitrary number of mailboxes. GNU sieve implements a superset of the Sieve language as described in RFC 3028. See section 5. Sieve Language, for a description of the Sieve language. See section 5.8 GNU Extensions, for a discussion of differences between the GNU implementation of Sieve and its standard.

Invoking sieve
Logging and debugging
Extending sieve

Invoking sieve

The sieve invocation syntax is:

sieve [options] script

where script denotes the filename of the sieve program to parse, and options is one or more of the following:

`-c'

`--compile-only'

Compile script and exit.

`-d[flags]'

`--debug[=flags]'

Specify debug flags. The flags argument is a sequence of one or more of the following letters:

`g'	Enable main parser traces
`T'	Enable mailutil traces
`P'	Trace network protocols
`t'	Enable sieve trace
`i'	Trace the program instructions

`-D'

`--dump'

Compile the script, dump disassembled code on standard output and exit.

`-e address'

`--email address'

Override the user email address. This is useful for reject and redirect actions. By default, the user email address is deduced from the user name and the full name of the machine where sieve is executed.

`-f'

`--mbox-url=mbox'

Mailbox to sieve (defaults to user's system mailbox)

`-k'

`--keep-going'

Keep on going if execution fails on a message

`-n'

`--no-actions'

Dry run: do not execute any actions, just print what would be done.

`-t ticket'

`--ticket=ticket'

Ticket file for mailbox authentication

`-v'

`--verbose'

Log all actions executed.

Apart from these, sieve understands the options from the following groups: sieve, mailbox, mailer, logging.

Logging and debugging

The default behavior of sieve is to remain silent about anything except errors. However, it is sometimes necessary to see which actions are executed and on which messages. This is particularly useful when debugging the sieve scripts. The `--verbose' (`-v') option outputs log of every action executed.

Option `--debug' allows to produce even more detailed debugging information. This option takes an argument specifying the debugging level to be enabled. The argument can consist of the following letters:

``t''

This flag enables sieve tracing. It means that every test will be logged when executed.

``T''

This flag enables debugging of underlying mailutils library.

``P''

Trace network protocols: produces log of network transactions executed while running the script.

``g''

Enable main parser traces. This is useful for debugging the sieve grammar.

``i''

Trace the program instructions. It is the most extensive debugging level. It produces the full execution log of a sieve program, showing each instruction and states of the sieve machine. It is only useful for debugging the code generator.

Note, that there should be no whitespace between the short variant of the option (`-d'), and its argument. Similarly, when using long option (`--debug'), its argument must be preceded by equal sign.

If the argument to `--debug' is omitted, it defaults to `TPt'.

Option `--dump' produces the disassembled dump of the compiled sieve program.

By default sieve output all diagnostics on standard error and verbose logs on standard output. This behaviour is changed when `--log-facility' is given in the command line (see section 3.1.8 Logging). This option causes sieve to output its diagnostics to the given syslog facility.

Extending sieve

The basic set of sieve actions, tests and comparators may be extended using loadable extensions. Usual require mechanism is used for that.

When processing arguments for require statement, sieve uses the following algorithm:

1. Look up the name in a symbol table. If the name begins with `comparator-' it is looked up in the comparator table. If it begins with `test-', the test table is used instead. Otherwise the name is looked up in the action table.

2. If the name is found, the search is terminated.

3. Otherwise, transform the name. First, any `comparator-' or `test-' prefix is stripped. Then, any character other than alphanumeric characters, `.' and `,' is replaced with dash (`-'). The name thus obtained is used as a file name of an external loadable module.

4. Try to load the module. The module is searched in the following search paths (in the order given):
   1. Mailutils module directory. By default it is `$prefix/lib/mailutils'.

   2. The value of the environment variable LTDL_LIBRARY_PATH.

   3. Additional search directories specified with the #searchpath directive.

   4. System library search path: The system dependent library search path (e.g. on Linux it is set by the contents of the file `/etc/ld.so.conf' and the value of the environment variable LD_LIBRARY_PATH).

   The value of LTDL_LIBRARY_PATH and LD_LIBRARY_PATH must be a colon-separated list of absolute directories, for example, `"/usr/lib/mypkg:/lib/foo"'.

   In any of these directories, sieve first attempts to find and load the given filename. If this fails, it tries to append the following suffixes to the file name:

   1. the libtool archive extension `.la'

   2. the extension used for native dynamic libraries on the host platform, e.g., `.so', `.sl', etc.

5. If the module is found, sieve executes its initialization function (see below) and again looks up the name in the symbol table. If found, search terminates successfully.

6. If either the module is not found, or the symbol wasn't found after execution of the module initialization function, search is terminated with an error status. sieve then displays the following diagnostic message:

   source for the required action NAME is not available