Format of filter files

Apart from leading white space, the first text in a filter file must be

# Exim filter

This is what distinguishes it from a conventional `.forward' file. If the file does not have this initial line it is treated as a conventional `.forward' file, both when delivering mail and when using the -bf testing mechanism. The white space in the line is optional, and any capitalization may be used. Further text on the same line is treated as a comment. For example, you could have

#   Exim filter   <<== do not edit or remove this line!

The remainder of the file is a sequence of filtering commands, which consist of keywords and data values, separated by white space or line breaks, except in the case of conditions for the `if' command, where round brackets (parentheses) also act as separators. For example, in the command

deliver gulliver@lilliput.fict.example

the keyword is `deliver' and the data value is `gulliver@lilliput.fict.example'. The commands are in free format, and there are no special terminators. If the character # follows a separator, then everything from # up to the next newline is ignored. This provides a way of including comments in a filter file.

There are two ways in which a data value can be input:

• If the text contains no white space then it can be typed verbatim. However, if it is part of a condition, it must also be free of round brackets (parentheses), as these are used for grouping in conditions.
• Otherwise it must be enclosed in double quotation marks. In this case, the character \ (backslash) is treated as an `escape character' within the string, causing the following character or characters to be treated specially:

  \n       is replaced by a newline
  \r       is replaced by a carriage return
  \t       is replaced by a tab
  

  Backslash followed by up to three octal digits is replaced by the character specified by those digits, and \x followed by up to two hexacimal digits is treated similarly. Backslash followed by any other character is replaced by the second character, so that in particular, \" becomes " and \\ becomes \. A data item enclosed in double quotes can be continued onto the next line by ending the first line with a backslash. Any leading white space at the start of the continuation line is ignored.

In addition to the escape character processing that occurs when strings are enclosed in quotes, most data values are also subject to string expansion (as described in the next section), in which case the characters $ and \ are also significant. This means that if a single backslash is actually required in such a string, and the string is also quoted, \\\\ has to be entered.

Go to the first, previous, next, last section, table of contents.