Embedded Perl

Exim can be built to include an embedded Perl interpreter. When this is done, Perl subroutines can be called as part of the string expansion process. To make use of the Perl support, you need version 5.004 or later of Perl installed on your system. To include the embedded interpreter in the Exim binary, include the line

EXIM_PERL = perl.o

in your `Local/Makefile' and then build Exim in the normal way.

Access to Perl subroutines is via a global configuration option called `perl_startup' and an expansion string operator `${perl ...}'. If there is no `perl_startup' option in the Exim configuration file then no Perl interpreter is started and there is almost no overhead for Exim (since none of the Perl library will be paged in unless used). If there is a `perl_startup' option then the associated value is taken to be Perl code which is executed in a newly created Perl interpreter.

The value of `perl_startup' is not expanded in the Exim sense, so you do not need backslashes before any characters to escape special meanings. The option should usually be something like

perl_startup = do '/etc/exim.pl'

where `/etc/exim.pl' is Perl code which defines any subroutines you want to use from Exim. Exim can be configured either to start up a Perl interpreter as soon as it is entered, or to wait until the first time it is needed. Starting the interpreter at the beginning ensures that it is done while Exim still has its setuid privilege, but can impose an unnecessary overhead if Perl is not in fact used in a particular run. By default, the interpreter is started only when it is needed, but this can be changed in two ways:

• Setting `perl_at_start' (a boolean option) in the configuration requests a startup when Exim is entered.
• The command line option `-ps' also requests a startup when Exim is entered, overriding the setting of `perl_at_start'.

There is also a command line option `-pd' (for delay) which suppresses the initial startup, even if `perl_at_start' is set.

When the configuration file includes a `perl_startup' option you can make use of the string expansion item to call the Perl subroutines that are defined by the `perl_startup' code. The operator is used in any of the following forms:

${perl{foo}}
${perl{foo}{argument}}
${perl{foo}{argument1}{argument2} ... }

which calls the subroutine `foo' with the given arguments. A maximum of eight arguments may be passed. Passing more than this results in an expansion failure with an error message of the form

Too many arguments passed to Perl subroutine "foo" (max is 8)

The return value of the subroutine is inserted into the expanded string, unless the return value is "undef". In that case, the expansion fails in the same way as an explicit `fail' on an `${if ...}' or `${lookup...}' item. If the subroutine aborts by obeying Perl's `die' function, then the expansion fails with the error message that was passed to `die'.

Within any Perl code called from Exim, the function `Exim::expand_string' is available to call back into Exim's string expansion function. For example, the Perl code

my $lp = Exim::expand_string('$local_part');

makes the current Exim `$local_part' available in the Perl variable `$lp'. Note those are single quotes and not double quotes to protect against `$local_part' being interpolated as a Perl variable.