<!DOCTYPE html PUBLIC "XSLT-compat">
<html lang="en-GB">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" type="text/css" href="../../../../common.css">
<meta name="author" content="The Exim Project. <http://www.exim.org/>">
<meta name="copyright" content="Copyright ©2010 The Exim Project. All rights reserved">
<meta name="description" content="Exim is a message transfer agent (MTA) developed at the University of Cambridge for use on Unix systems connected to the Internet.">
<meta name="keywords" content="exim,smtp,mta,email">
<meta name="robots" content="noodp,noydir,index,follow">
<meta name="viewport" content="width=device-width">
<title>12. Embedded Perl</title>
<link rel="stylesheet" type="text/css" href="../../../../doc/chapter.css">
<link rel="canonical" href="http://www.exim.org/exim-html-current/doc/html/spec_html/ch12.html">
</head>
<body>
<h1 id="header"><a href="../../../..">Exim Internet Mailer</a></h1>
<div id="outer">
<ul id="nav_flow" class="nav">
<li><a href="../../../../index.html">Home</a></li>
<li><a href="../../../../mirrors.html">Download</a></li>
<li><a href="../../../../docs.html">Documentation</a></li>
<li><a href="../../../../maillist.html">Mailing Lists</a></li>
<li><a href="http://wiki.exim.org/">Wiki</a></li>
<li><a href="http://www.exim.org/bugzilla/">Bugs</a></li>
<li><a href="../../../../credits.html">Credits</a></li>
<li class="search"><form action="http://www.google.com/search" method="get">
<span class="search_field_container"><input type="search" name="q" placeholder="Search Docs" class="search_field"></span><input type="hidden" name="hl" value="en"><input type="hidden" name="ie" value="UTF-8"><input type="hidden" name="as_qdr" value="all"><input type="hidden" name="q" value="site:www.exim.org"><input type="hidden" name="q" value="inurl:exim-html-current">
</form></li>
</ul>
<div id="inner"><div id="content">
<a class="previous_page" href="ch11.html"><-previous</a><a class="next_page" href="ch13.html">next-></a><div id="chapter" class="chapter">
<h2 id="CHAPperl" class="">Chapter 12 - Embedded Perl</h2>
<p>
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>
<div class="docbook_literallayout"><pre>
EXIM_PERL = perl.o
</pre></div>
<p>
in your <span class="docbook_filename">Local/Makefile</span> and then build Exim in the normal way.
</p>
<div class="section">
<h3 id="SECID85" class="">1. Setting up so Perl can be used</h3>
<p>
Access to Perl subroutines is via a global configuration option called
<span class="docbook_option">perl_startup</span> and an expansion string operator <span class="docbook_option">${perl ...}</span>. If there is
no <span class="docbook_option">perl_startup</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 class="docbook_option">perl_startup</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 class="docbook_option">perl_startup</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>
<div class="docbook_literallayout"><pre>
perl_startup = do '/etc/exim.pl'
</pre></div>
<p>
where <span class="docbook_filename">/etc/exim.pl</span> 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>
<ul>
<li>
<p>
Setting <span class="docbook_option">perl_at_start</span> (a boolean option) in the configuration requests
a startup when Exim is entered.
</p>
</li>
<li>
<p>
The command line option <span class="docbook_option">-ps</span> also requests a startup when Exim is entered,
overriding the setting of <span class="docbook_option">perl_at_start</span>.
</p>
</li>
</ul>
<p>
There is also a command line option <span class="docbook_option">-pd</span> (for delay) which suppresses the
initial startup, even if <span class="docbook_option">perl_at_start</span> is set.
</p>
</div>
<div class="section">
<h3 id="SECID86" class="">2. Calling Perl subroutines</h3>
<p>
When the configuration file includes a <span class="docbook_option">perl_startup</span> option you can make use
of the string expansion item to call the Perl subroutines that are defined
by the <span class="docbook_option">perl_startup</span> code. The operator is used in any of the following
forms:
</p>
<div class="docbook_literallayout"><pre>
${perl{foo}}
${perl{foo}{argument}}
${perl{foo}{argument1}{argument2} ... }
</pre></div>
<p>
which calls the subroutine <span class="docbook_option">foo</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>
<div class="docbook_literallayout"><pre>
Too many arguments passed to Perl subroutine "foo" (max is 8)
</pre></div>
<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="docbook_emphasis">undef</span>, the expansion is forced to fail in the same way as
an explicit “fail” on an <span class="docbook_option">if</span> or <span class="docbook_option">lookup</span> item. If the subroutine aborts
by obeying Perl’s <span class="docbook_option">die</span> function, the expansion fails with the error message
that was passed to <span class="docbook_option">die</span>.
</p>
</div>
<div class="section">
<h3 id="SECID87" class="">3. Calling Exim functions from Perl</h3>
<p>
Within any Perl code called from Exim, the function <span class="docbook_emphasis">Exim::expand_string()</span>
is available to call back into Exim’s string expansion function. For example,
the Perl code
</p>
<div class="docbook_literallayout"><pre>
my $lp = Exim::expand_string('$local_part');
</pre></div>
<p>
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.
</p>
<p>
If the string expansion is forced to fail by a “fail” item, the result of
<span class="docbook_emphasis">Exim::expand_string()</span> is <span class="docbook_option">undef</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 class="docbook_option">die</span> were used.
</p>
<p>
Two other Exim functions are available for use from within Perl code.
<span class="docbook_emphasis">Exim::debug_write()</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="docbook_emphasis">Exim::log_write()</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">
<h3 id="SECID88" class="">4. Use of standard output and error by Perl</h3>
<p>
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 <span class="docbook_filename">/dev/null</span> in the daemon. The chaos is
avoided, but the output is lost.
</p>
<p>
The Perl <span class="docbook_option">warn</span> statement writes to the standard error stream by default.
Calls to <span class="docbook_option">warn</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 class="docbook_option">warn</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 class="docbook_option">warn</span> output completely, you need this:
</p>
<div class="docbook_literallayout"><pre>
$SIG{__WARN__} = sub { };
</pre></div>
<p>
Whenever a <span class="docbook_option">warn</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 class="docbook_option">warn</span> message is passed
as the first subroutine argument.
</p>
</div>
</div>
<a class="previous_page" href="ch11.html"><-previous</a><a class="next_page" href="ch13.html">next-></a>
</div></div>
<iframe id="branding" name="branding" src="../../../../branding/branding.html" height="0" frameborder="no" scrolling="no"></iframe><div id="footer">Website design by <a href="https://secure.grepular.com/">Mike Cardwell</a>, of <a href="http://cardwellit.com/">Cardwell IT Ltd.</a>
</div>
<div class="left_bar"></div>
<div class="right_bar"></div>
<div id="toc">
<ul class="hidden"></ul>
<img src="../../../../doc/contents.png" width="16" height="155">
</div>
</div>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script><script type="text/javascript" src="../../../../common.js"></script><script type="text/javascript" src="../../../../doc/chapter.js"></script>
</body>
</html>
