<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- Created on September, 10 2009 by texi2html 1.78 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Many creative people.
Send bugs and suggestions to <texi2html-bug@nongnu.org>
-->
<head>
<title>Specification of the Exim Mail Transfer Agent: 12. Embedded Perl</title>
<meta name="description" content="Specification of the Exim Mail Transfer Agent: 12. Embedded Perl">
<meta name="keywords" content="Specification of the Exim Mail Transfer Agent: 12. Embedded Perl">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.78">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.roman {font-family:serif; font-weight:normal;}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Embedded-Perl"></a>
<a name="SEC147"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="spec_11.html#SEC146" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC148" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec_11.html#SEC137" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_13.html#SEC152" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h1 class="chapter"> 12. Embedded Perl </h1>
<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>
<table><tr><td> </td><td><pre class="example">EXIM_PERL = perl.o
</pre></td></tr></table>
<p>in your ‘<tt>Local/Makefile</tt>’ and then build Exim in the normal way.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#SEC148">12.1 Setting up so Perl can be used</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC149">12.2 Calling Perl subroutines</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC150">12.3 Calling Exim functions from Perl</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC151">12.4 Use of standard output and error by Perl</a></td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr size="6">
<a name="Setting-up-so-Perl-can-be-used"></a>
<a name="SEC148"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC147" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC149" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC147" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC147" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_13.html#SEC152" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 12.1 Setting up so Perl can be used </h2>
<p>Access to Perl subroutines is via a global configuration option called
<code>perl_startup</code> and an expansion string operator <code>${perl ...}</code>. If there is
no <code>perl_startup</code> 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 <code>perl_startup</code>
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 <code>perl_startup</code> 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>
<table><tr><td> </td><td><pre class="example">perl_startup = do '/etc/exim.pl'
</pre></td></tr></table>
<p>where ‘<tt>/etc/exim.pl</tt>’ 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 class="toc">
<li>
<a name="IDX1056"></a>
Setting <code>perl_at_start</code> (a boolean option) in the configuration requests
a startup when Exim is entered.
</li><li>
The command line option <code>-ps</code> also requests a startup when Exim is entered,
overriding the setting of <code>perl_at_start</code>.
</li></ul>
<p>There is also a command line option <code>-pd</code> (for delay) which suppresses the
initial startup, even if <code>perl_at_start</code> is set.
</p>
<hr size="6">
<a name="Calling-Perl-subroutines"></a>
<a name="SEC149"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC148" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC150" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC147" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC147" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_13.html#SEC152" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 12.2 Calling Perl subroutines </h2>
<p>When the configuration file includes a <code>perl_startup</code> option you can make use
of the string expansion item to call the Perl subroutines that are defined
by the <code>perl_startup</code> code. The operator is used in any of the following
forms:
</p>
<table><tr><td> </td><td><pre class="example">${perl{foo}}
${perl{foo}{argument}}
${perl{foo}{argument1}{argument2} ... }
</pre></td></tr></table>
<p>which calls the subroutine <code>foo</code> 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>
<table><tr><td> </td><td><pre class="example">Too many arguments passed to Perl subroutine "foo" (max is 8)
</pre></td></tr></table>
<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 <em>undef</em>, the expansion is forced to fail in the same way as
an explicit "fail" on an <code>if</code> or <code>lookup</code> item. If the subroutine aborts
by obeying Perl's <code>die</code> function, the expansion fails with the error message
that was passed to <code>die</code>.
</p>
<hr size="6">
<a name="Calling-Exim-functions-from-Perl"></a>
<a name="SEC150"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC149" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC151" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC147" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC147" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_13.html#SEC152" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 12.3 Calling Exim functions from Perl </h2>
<p>Within any Perl code called from Exim, the function <em>Exim::expand_string()</em>
is available to call back into Exim's string expansion function. For example,
the Perl code
</p>
<table><tr><td> </td><td><pre class="example">my $lp = Exim::expand_string('$local_part');
</pre></td></tr></table>
<p>makes the current Exim <code>$local_part</code> available in the Perl variable <code>$lp</code>.
Note those are single quotes and not double quotes to protect against
<code>$local_part</code> being interpolated as a Perl variable.
</p>
<p>If the string expansion is forced to fail by a "fail" item, the result of
<em>Exim::expand_string()</em> is <code>undef</code>. 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 <code>die</code> were used.
</p>
<a name="IDX1057"></a>
<a name="IDX1058"></a>
<p>Two other Exim functions are available for use from within Perl code.
<em>Exim::debug_write()</em> 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.
<em>Exim::log_write()</em> writes a string to Exim's main log, adding a leading
timestamp. In this case, you should not supply a terminating newline.
</p>
<hr size="6">
<a name="Use-of-standard-output-and-error-by-Perl"></a>
<a name="SEC151"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC150" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="spec_13.html#SEC152" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC147" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC147" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_13.html#SEC152" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 12.4 Use of standard output and error by Perl </h2>
<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 ‘<tt>/dev/null</tt>’ in the daemon. The chaos is
avoided, but the output is lost.
</p>
<a name="IDX1059"></a>
<p>The Perl <code>warn</code> statement writes to the standard error stream by default.
Calls to <code>warn</code> 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 <code>warn</code> 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 <code>warn</code> output completely, you need this:
</p>
<table><tr><td> </td><td><pre class="example">$SIG{__WARN__} = sub { };
</pre></td></tr></table>
<p>Whenever a <code>warn</code> 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 <code>warn</code> message is passed
as the first subroutine argument.
<a name="IDX1060"></a>
</p>
<hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC147" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="spec_13.html#SEC152" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p>
<font size="-1">
This document was generated on <i>September, 10 2009</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.78</i></a>.
</font>
<br>
</p>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
a4080654d049ad31b216b761b9173c1f
>
files
>
113
