4.5 Pragmatic comments

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.

4.5.1 Pragma prereq

The #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 or prior.

4.5.2 Pragma stacksize

The 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.

pragma: stacksize size [incr [max]]

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:

Suffix	Meaning
k	Kiloword, i.e. 1024 words
m	Megawords, i.e. 1048576 words
g	Gigawords,
t	Terawords (ouch!)

Table 4.1: Unit Size Suffix

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 this:

warning: stack segment expanded, new size=8192

You can use these messages to adjust your stack size configuration settings.

4.5.3 Pragma regex

The ‘#pragma regex’, controls compilation of regular expressions. You can use any number of such pragma directives in your mailfromd.mfl. The scope of ‘#pragma regex’ extends to the next occurrence of this directive or to the end of the script file, whichever occurs first.

pragma: regex [push|pop] flags

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:

‘extended’

Use POSIX Extended Regular Expression syntax when interpreting regex. If not set, POSIX Basic Regular Expression syntax is used.

‘icase’

Do not differentiate case. Subsequent regex searches will be case insensitive.

‘newline’

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.mfl 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.

The statement

#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

4.5.4 Pragma dbprop

pragma: dbprop pattern prop …

This pragma configures properties for a DBM database. See Database functions, for its detailed description.

4.5.5 Pragma greylist

pragma: greylist type

Selects the greylisting implementation to use. Allowed values for type are:

traditional

gray

Use the traditional greylisting implementation. This is the default.

con-tassios

ct

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.

4.5.6 Pragma miltermacros

pragma: miltermacros handler macro …

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).

The 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 via getmacro and 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.

4.5.7 Pragma provide-callout

The #pragma provide-callout statement is used in the callout module to inform mailfromd that the module has been loaded.

Do not use this pragma.