1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52
from spec on 25 November 2000 -->
<TITLE>Exim Specification - 10. Embedded Perl</TITLE>
</HEAD>
<body bgcolor="#FFFFFF" text="#00005A" link="#FF6600" alink="#FF9933" vlink="#990000">
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_9.html">previous</A>, <A HREF="spec_11.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
<P><HR><P>
<H1><A NAME="SEC182" HREF="spec_toc.html#TOC182">10. Embedded Perl</A></H1>
<P>
<A NAME="IDX599"></A>
<A NAME="IDX600"></A>
</P>
<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
<PRE>
EXIM_PERL = perl.o
</PRE>
<P>
in your <TT>`Local/Makefile'</TT> and then build Exim in the normal way.
</P>
<P>
Access to Perl subroutines is via a global configuration option called
<A NAME="IDX601"></A>
<EM>perl_startup</EM> and an expansion string operator <EM>${perl ...}</EM>. If there is
no <EM>perl_startup</EM> 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 <EM>perl_startup</EM>
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 <EM>perl_startup</EM> 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
<PRE>
perl_startup = do '/etc/exim.pl'
</PRE>
<P>
where <EM>/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.
<font color=green>
Also, note that this does not mean that Exim is necessarily running as root
when Perl is called at a later time.
</font>
By default, the interpreter is started only when it is needed, but this can be
changed in two ways:
</P>
<UL>
<LI>
<A NAME="IDX602"></A>
Setting <EM>perl_at_start</EM> (a boolean option) in the configuration requests
a startup when Exim is entered.
<LI>
The command line option -<EM>ps</EM> also requests a startup when Exim is entered,
overriding the setting of <EM>perl_at_start</EM>.
</UL>
<P>
There is also a command line option -<EM>pd</EM> (for delay) which suppresses the
initial startup, even if <EM>perl_at_start</EM> is set.
</P>
<P>
When the configuration file includes a <EM>perl_startup</EM> option you can make use
of the string expansion item to call the Perl subroutines that are defined
by the <EM>perl_startup</EM> code. The operator is used in any of the following
forms:
<PRE>
${perl{foo}}
${perl{foo}{argument}}
${perl{foo}{argument1}{argument2} ... }
</PRE>
<P>
which calls the subroutine <EM>foo</EM> 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
<PRE>
Too many arguments passed to Perl subroutine "foo" (max is 8)
</PRE>
<P>
The return value of the subroutine is inserted into the expanded string, unless
the return value is <EM>undef</EM>. In that case, the expansion fails in the same
way as an explicit `fail' on an <EM>${if ...}</EM> or <EM>${lookup...}</EM> item. If
the subroutine aborts by obeying Perl's <EM>die</EM> function, the expansion
fails with the error message that was passed to <EM>die</EM>.
</P>
<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
<PRE>
my $lp = Exim::expand_string('$local_part');
</PRE>
<P>
makes the current Exim $<EM>local_part</EM> available in the Perl variable $<EM>lp</EM>.
Note those are single quotes and not double quotes to protect against
$<EM>local_part</EM> 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 <EM>undef</EM>. 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 <EM>die</EM> were used.
</P>
<P><HR><P>
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_9.html">previous</A>, <A HREF="spec_11.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
</BODY>
</HTML>
|
