<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><style xmlns="" type="text/css">
div.added { background-color: #ffff99; }
div.deleted { text-decoration: line-through;
background-color: #FF7F7F; }
div.changed { background-color: #99ff99; }
div.off { }
span.added { background-color: #ffff99; }
span.deleted { text-decoration: line-through;
background-color: #FF7F7F; }
span.changed { background-color: #99ff99; }
span.off { }
pre.literallayout {
background-color: #E8E8D0;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div[class=changed] pre.literallayout {
background-color: #99ff99;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div.literallayout {
background-color: #E8E8D0;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div[class=changed] div.literallayout {
background-color: #99ff99;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
</style><title>12. Embedded Perl</title><meta name="generator" content="DocBook XSL Stylesheets V1.72.0" /><link rel="start" href="index.html" title="Specification of the Exim Mail Transfer Agent" /><link rel="up" href="index.html" title="Specification of the Exim Mail Transfer Agent" /><link rel="prev" href="ch11.html" title="11. String expansions" /><link rel="next" href="ch13.html" title="13. Starting the daemon and the use of network interfaces" /></head><body><div class="navheader">
<table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch11.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch13.html">Next</a></td></tr></table></div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a href="index.html#toc0147" id="CHAPperl">12. Embedded Perl</a></h2></div>
</div>
</div>
<p>
<a id="IIDperl" class="indexterm"></a>
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
</p>
<pre class="literallayout">EXIM_PERL = perl.o
</pre><p>
in your <em class="filename">Local/Makefile</em> and then build Exim in the normal way.
</p>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0148" id="SECID85">12.1 Setting up so Perl can be used</a></h3></div>
</div>
</div>
<p>
<a id="id523516" class="indexterm"></a>
Access to Perl subroutines is via a global configuration option called
<span><strong class="option">perl_startup</strong></span> and an expansion string operator <span><strong class="option">${perl ...}</strong></span>. If there is
no <span><strong class="option">perl_startup</strong></span> 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 <span><strong class="option">perl_startup</strong></span>
option then the associated value is taken to be Perl code which is executed in
a newly created Perl interpreter.
</p>
<p>
The value of <span><strong class="option">perl_startup</strong></span> 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
</p>
<pre class="literallayout">perl_startup = do '/etc/exim.pl'
</pre><p>
where <em class="filename">/etc/exim.pl</em> 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. Also, note that this does not mean that Exim is
necessarily running as root when Perl is called at a later time. By default,
the interpreter is started only when it is needed, but this can be changed in
two ways:
</p>
<div class="itemizedlist">
<ul type="disc"><li><p>
<a id="id523584" class="indexterm"></a>
Setting <span><strong class="option">perl_at_start</strong></span> (a boolean option) in the configuration requests
a startup when Exim is entered.
</p>
</li><li><p>
The command line option <span><strong class="option">-ps</strong></span> also requests a startup when Exim is entered,
overriding the setting of <span><strong class="option">perl_at_start</strong></span>.
</p>
</li></ul></div>
<p>
There is also a command line option <span><strong class="option">-pd</strong></span> (for delay) which suppresses the
initial startup, even if <span><strong class="option">perl_at_start</strong></span> is set.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0149" id="SECID86">12.2 Calling Perl subroutines</a></h3></div>
</div>
</div>
<p>
When the configuration file includes a <span><strong class="option">perl_startup</strong></span> option you can make use
of the string expansion item to call the Perl subroutines that are defined
by the <span><strong class="option">perl_startup</strong></span> code. The operator is used in any of the following
forms:
</p>
<pre class="literallayout">${perl{foo}}
${perl{foo}{argument}}
${perl{foo}{argument1}{argument2} ... }
</pre><p>
which calls the subroutine <span><strong class="option">foo</strong></span> 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
</p>
<pre class="literallayout">Too many arguments passed to Perl subroutine "foo" (max is 8)
</pre><p>
The return value of the Perl subroutine is evaluated in a scalar context before
it is passed back to Exim to be inserted into the expanded string. If the
return value is <span class="emphasis"><em>undef</em></span>, the expansion is forced to fail in the same way as
an explicit “<span class="quote">fail</span>” on an <span><strong class="option">if</strong></span> or <span><strong class="option">lookup</strong></span> item. If the subroutine aborts
by obeying Perl’s <span><strong class="option">die</strong></span> function, the expansion fails with the error message
that was passed to <span><strong class="option">die</strong></span>.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0150" id="SECID87">12.3 Calling Exim functions from Perl</a></h3></div>
</div>
</div>
<p>
Within any Perl code called from Exim, the function <span class="emphasis"><em>Exim::expand_string()</em></span>
is available to call back into Exim’s string expansion function. For example,
the Perl code
</p>
<pre class="literallayout">my $lp = Exim::expand_string('$local_part');
</pre><p>
makes the current Exim <em class="varname">$local_part</em> available in the Perl variable <em class="varname">$lp</em>.
Note those are single quotes and not double quotes to protect against
<em class="varname">$local_part</em> being interpolated as a Perl variable.
</p>
<p>
If the string expansion is forced to fail by a “<span class="quote">fail</span>” item, the result of
<span class="emphasis"><em>Exim::expand_string()</em></span> is <span><strong class="option">undef</strong></span>. If there is a syntax error in the
expansion string, the Perl call from the original expansion string fails with
an appropriate error message, in the same way as if <span><strong class="option">die</strong></span> were used.
</p>
<p>
<a id="id523786" class="indexterm"></a>
<a id="id523801" class="indexterm"></a>
Two other Exim functions are available for use from within Perl code.
<span class="emphasis"><em>Exim::debug_write()</em></span> writes a string to the standard error stream if Exim’s
debugging is enabled. If you want a newline at the end, you must supply it.
<span class="emphasis"><em>Exim::log_write()</em></span> writes a string to Exim’s main log, adding a leading
timestamp. In this case, you should not supply a terminating newline.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0151" id="SECID88">12.4 Use of standard output and error by Perl</a></h3></div>
</div>
</div>
<p>
<a id="id523850" class="indexterm"></a>
You should not write to the standard error or output streams from within your
Perl code, as it is not defined how these are set up. In versions of Exim
before 4.50, it is possible for the standard output or error to refer to the
SMTP connection during message reception via the daemon. Writing to this stream
is certain to cause chaos. From Exim 4.50 onwards, the standard output and
error streams are connected to <em class="filename">/dev/null</em> in the daemon. The chaos is
avoided, but the output is lost.
</p>
<p>
<a id="id523881" class="indexterm"></a>
The Perl <span><strong class="option">warn</strong></span> statement writes to the standard error stream by default.
Calls to <span><strong class="option">warn</strong></span> may be embedded in Perl modules that you use, but over which
you have no control. When Exim starts up the Perl interpreter, it arranges for
output from the <span><strong class="option">warn</strong></span> statement to be written to the Exim main log. You can
change this by including appropriate Perl magic somewhere in your Perl code.
For example, to discard <span><strong class="option">warn</strong></span> output completely, you need this:
</p>
<pre class="literallayout">$SIG{__WARN__} = sub { };
</pre><p>
Whenever a <span><strong class="option">warn</strong></span> is obeyed, the anonymous subroutine is called. In this
example, the code for the subroutine is empty, so it does nothing, but you can
include any Perl code that you like. The text of the <span><strong class="option">warn</strong></span> message is passed
as the first subroutine argument.
<a id="id523942" class="indexterm"></a>
</p>
</div>
</div>
<div class="navfooter">
<table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch11.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch13.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div>
</body></html>
