Exim Filter Specification section 5

Previous Next Contents (Exim Filter Specification)

## 5. 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. For example, in the command

      deliver gulliver@lilliput.fict.example

the keyword is `deliver` and the data value is `gulliver@lilliput.fict.example`. White space or line breaks separate the components of a command, except in the case of conditions for the `if` command, where round brackets (parentheses) also act as separators. Complete commands are separated from each other by white space or line breaks; there are no special terminators. Thus, several commands may appear on one line, or one command may be spread over a number of lines.

If the character # follows a separator anywhere in a command, 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 hexadecimal 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.

Previous Next Contents (Exim Filter Specification)