General-Purpose Mail Filter
If ‘#’ is immediately followed by word ‘pragma’ (with optional whitespace between them), such a construct introduces a pragmatic comment, i.e. an instruction that controls some configuration setting.
The available pragma types are described in the following subsections.
#pragma prereq statement ensures that the correct
mailfromd version is used to compile the source file it
appears in. It takes version number as its arguments and produces
a compilation error if the actual
mailfromd version number
is earlier than that. For example, the following statement:
#pragma prereq 7.0.94
results in error if compiled with
mailfromd version 7.0.93
stacksize pragma sets the initial size of the run-time
stack and may also define the policy of its growing, in case it
becomes full. The default stack size is 4096 words. You may
need to increase this number if your configuration program uses
recursive functions or does an excessive amount of string manipulations.
Sets stack size to size units. Optional incr and max define stack growth policy (see below). The default units are words. The following example sets the stack size to 7168 words:
#pragma stacksize 7168
The size may end with a unit size suffix:
|k||Kiloword, i.e. 1024 words|
|m||Megawords, i.e. 1048576 words|
File suffixes are case-insensitive, so the following two pragmas are
equivalent and set the stack size to
7*1048576 = 7340032 words:
#pragma stacksize 7m #pragma stacksize 7M
When the MFL engine notices that there is no more stack space available, it attempts to expand the stack. If this attempt succeeds, the operation continues. Otherwise, a runtime error is reported and the execution of the filter stops.
The optional incr argument to
#pragma stacksize defines growth
policy for the stack. Two growth policies are implemented:
fixed increment policy, which expands stack in a fixed
number of expansion chunks, and exponential growth policy, which
duplicates the stack size until it is able to accommodate the needed
number of words. The fixed increment policy is the default. The default
chunk size is 4096 words.
If incr is the word ‘twice’, the duplicate policy is selected. Otherwise incr must be a positive number optionally suffixed with a size suffix (see above). This indicates the expansion chunk size for the fixed increment policy.
The following example sets initial stack size to 10240, and expansion chunk size to 2048 words:
#pragma stacksize 10M 2K
The pragma below enables exponential stack growth policy:
#pragma stacksize 10240 twice
In this case, when the run-time evaluator hits the stack size limit, it expands the stack to twice the size it had before. So, in the example above, the stack will be sequentially expanded to the following sizes: 20480, 40960, 81920, 163840, etc.
The optional max argument defines the maximum size of the stack. If stack grows beyond this limit, the execution of the script will be aborted.
If you are concerned about the execution time of your script, you
may wish to avoid stack reallocations. To help you find out the
optimal stack size, each time the stack is expanded,
mailfromd issues a warning in its log file, which looks like
warning: stack segment expanded, new size=8192
You can use these messages to adjust your stack size configuration settings.
The ‘#pragma regex’, controls compilation of expressions. You can use any number of such pragma directives in your mailfromd.mf. The scope of ‘#pragma regex’ extends to the next occurrence of this directive or to the end of the script file, whichever occurs first.
The optional push|pop parameter is one of the words ‘push’ or ‘pop’ and is discussed in detail below. The flags parameter is a whitespace-separated list of regex flags. Each regex-flag is a word specifying some regex feature. It can be preceded by ‘+’ to enable this feature (this is the default), by ‘-’ to disable it or by ‘=’ to reset regex flags to its value. Valid regex-flags are:
Use POSIX Extended Regular Expression syntax when interpreting regex. If not set, POSIX Basic Regular Expression syntax is used.
Do not differentiate case. Subsequent regex searches will be case insensitive.
Match-any-character operators don’t match a newline.
A non-matching list (‘[^...]’) not containing a newline does not match a newline.
Match-beginning-of-line operator (‘^’) matches the empty string immediately after a newline.
Match-end-of-line operator (‘$’) matches the empty string immediately before a newline.
For example, the following pragma enables POSIX extended, case insensitive matching (a good thing to start your mailfromd.mf with):
#pragma regex +extended +icase
Optional modifiers ‘push’ and ‘pop’ can be used to maintain a stack of regex flags. The statement
#pragma regex push [flags]
saves current regex flags on stack and then optionally modifies them as requested by flags.
#pragma regex pop [flags]
does the opposite: restores the current regex flags from the top of stack and applies flags to it.
This statement is useful in module and include files to avoid disturbing user regex settings. E.g.:
#pragma regex push +extended +icase . . . #pragma regex pop
This pragma configures properties for a DBM database. See Database functions, for its detailed description.
Selects the greylisting implementation to use. Allowed values for type are:
Use the traditional greylisting implementation. This is the default.
Use Con Tassios greylisting implementation.
See greylisting types, for a detailed description of these greylisting implementations.
Notice, that this pragma can be used only once. A second use of this pragma would constitute an error, because you cannot use both greylisting implementations in the same program.
Declare that the Milter stage handler uses MTA macro listed as the rest of arguments. The handler must be a valid handler name (see Handlers).
mailfromd parser collects the names of the macros
referred to by a ‘$name’ construct within a handler
(see Sendmail Macros) and declares them automatically for
corresponding handlers. It is, however, unable to track macros
used in functions called from handler as well as those referred to
macro_defined functions. Such
macros should be declared using ‘#pragma miltermacros’.
During initial negotiation with the MTA,
mailfromd will ask it to export the macro names declared
automatically or by using the ‘#pragma miltermacros’. The
MTA is free to honor or to ignore this request. In
particular, Sendmail versions prior to 8.14.0 and Postfix versions
prior to 2.5 do not support this feature. If you use one of these,
you will need to export the needed macros explicitly in the
MTA configuration. For more details, refer to the section
in MTA Configuration corresponding to your MTA type.
#pragma provide-callout statement is used in the
callout module to inform
mailfromd that the
module has been loaded.
Do not use this pragma.
This document was generated on January 3, 2019 using makeinfo.Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.