3.4 Sieve Library

Libsieve is gnu implementation of the mail filtering language Sieve. The library is built around a Sieve Machine — an abstract computer constructed specially to handle mail filtering tasks. This computer has two registers: program counter and numeric accumulator; a runtime stack of unlimited depth and the code segment. A set of functions is provided for creating and destroying instances of Sieve Machine, manipulating its internal data, compiling and executing a sieve program.

The following is a typical scenario of using libsieve:

1. Application program creates the instance of sieve machine.
2. Then mu_sieve_compile function is called to translate the Sieve source into an equivalent program executable by the Machine
3. A mailbox is opened and associated with the Machine
4. The Machine executes the program over the mailbox
5. When the execution of the program is finished, all messages upon which an action was executed other than keep are marked with the delete flag. Thus, running mailbox_expunge upon the mailbox finishes the job, leaving in the mailbox only those messages that were preserved by the filter.
6. Finally, the instance of Sieve Machine is destroyed and the resources allocated for it are reclaimed.

The following sections describe in detail the functions from the Sieve Library.

• Sieve Data Types
• Manipulating the Sieve Machine
• Logging and Diagnostic Functions
• Symbol Space Functions
• Memory Allocation
• Compiling and Executing the Script
• Writing Loadable Commands