<!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: 42. Adding a local scan function to Exim</title>
<meta name="description" content="Specification of the Exim Mail Transfer Agent: 42. Adding a local scan function to Exim">
<meta name="keywords" content="Specification of the Exim Mail Transfer Agent: 42. Adding a local scan function to Exim">
<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="Local-scan-function"></a>
<a name="SEC365"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="spec_41.html#SEC364" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC366" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec_41.html#SEC358" 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_43.html#SEC374" 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"> 42. Adding a local scan function to Exim </h1>
<p>In these days of email worms, viruses, and ever-increasing spam, some sites
want to apply a lot of checking to messages before accepting them.
</p>
<p>The content scanning extension (chapter <a href="spec_41.html#SEC358">Content scanning at ACL time</a>) has facilities for
passing messages to external virus and spam scanning software. You can also do
a certain amount in Exim itself through string expansions and the <code>condition</code>
condition in the ACL that runs after the SMTP DATA command or the ACL for
non-SMTP messages (see chapter <a href="spec_40.html#SEC308">Access control lists</a>), but this has its limitations.
</p>
<p>To allow for further customization to a site's own requirements, there is the
possibility of linking Exim with a private message scanning function, written
in C. If you want to run code that is written in something other than C, you
can of course use a little C stub to call it.
</p>
<p>The local scan function is run once for every incoming message, at the point
when Exim is just about to accept the message.
It can therefore be used to control non-SMTP messages from local processes as
well as messages arriving via SMTP.
</p>
<p>Exim applies a timeout to calls of the local scan function, and there is an
option called <code>local_scan_timeout</code> for setting it. The default is 5 minutes.
Zero means "no timeout".
Exim also sets up signal handlers for SIGSEGV, SIGILL, SIGFPE, and SIGBUS
before calling the local scan function, so that the most common types of crash
are caught. If the timeout is exceeded or one of those signals is caught, the
incoming message is rejected with a temporary error if it is an SMTP message.
For a non-SMTP message, the message is dropped and Exim ends with a non-zero
code. The incident is logged on the main and reject logs.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#SEC366">42.1 Building Exim to use a local scan function</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC367">42.2 API for local_scan()</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC368">42.3 Configuration options for local_scan()</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC369">42.4 Available Exim variables</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC370">42.5 Structure of header lines</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC371">42.6 Structure of recipient items</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC372">42.7 Available Exim functions</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC373">42.8 More about Exim's memory handling</a></td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr size="6">
<a name="Building-Exim-to-use-a-local-scan-function"></a>
<a name="SEC366"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC365" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC367" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC365" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC365" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_43.html#SEC374" 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"> 42.1 Building Exim to use a local scan function </h2>
<p>To make use of the local scan function feature, you must tell Exim where your
function is before building Exim, by setting LOCAL_SCAN_SOURCE in your
‘<tt>Local/Makefile</tt>’. A recommended place to put it is in the ‘<tt>Local</tt>’
directory, so you might set
</p>
<table><tr><td> </td><td><pre class="example">LOCAL_SCAN_SOURCE=Local/local_scan.c
</pre></td></tr></table>
<p>for example. The function must be called <code>local_scan()</code>. It is called by
Exim after it has received a message, when the success return code is about to
be sent. This is after all the ACLs have been run. The return code from your
function controls whether the message is actually accepted or not. There is a
commented template function (that just accepts the message) in the file
_src/local_scan.c_.
</p>
<p>If you want to make use of Exim's run time configuration file to set options
for your <code>local_scan()</code> function, you must also set
</p>
<table><tr><td> </td><td><pre class="example">LOCAL_SCAN_HAS_OPTIONS=yes
</pre></td></tr></table>
<p>in ‘<tt>Local/Makefile</tt>’ (see section <a href="#SEC368">Configuration options for local_scan()</a> below).
</p>
<hr size="6">
<a name="API-for-local_005fscan_005b_005d"></a>
<a name="SEC367"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC366" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC368" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC365" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC365" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_43.html#SEC374" 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"> 42.2 API for local_scan() </h2>
<p>You must include this line near the start of your code:
</p>
<table><tr><td> </td><td><pre class="example">#include "local_scan.h"
</pre></td></tr></table>
<p>This header file defines a number of variables and other values, and the
prototype for the function itself. Exim is coded to use unsigned char values
almost exclusively, and one of the things this header defines is a shorthand
for ‘<samp>unsigned char</samp>’ called ‘<samp>uschar</samp>’.
It also contains the following macro definitions, to simplify casting character
strings and pointers to character strings:
</p>
<table><tr><td> </td><td><pre class="example">#define CS (char *)
#define CCS (const char *)
#define CSS (char **)
#define US (unsigned char *)
#define CUS (const unsigned char *)
#define USS (unsigned char **)
</pre></td></tr></table>
<p>The function prototype for <code>local_scan()</code> is:
</p>
<table><tr><td> </td><td><pre class="example">extern int local_scan(int fd, uschar **return_text);
</pre></td></tr></table>
<p>The arguments are as follows:
</p>
<ul class="toc">
<li>
<code>fd</code> is a file descriptor for the file that contains the body of the message
(the -D file). The file is open for reading and writing, but updating it is not
recommended. <strong>Warning</strong>: You must <em>not</em> close this file descriptor.
<p>The descriptor is positioned at character 19 of the file, which is the first
character of the body itself, because the first 19 characters are the message
id followed by ‘<samp>-D</samp>’ and a newline. If you rewind the file, you should use the
macro SPOOL_DATA_START_OFFSET to reset to the start of the data, just in
case this changes in some future version.
</p>
</li><li>
<code>return_text</code> is an address which you can use to return a pointer to a text
string at the end of the function. The value it points to on entry is NULL.
</li></ul>
<p>The function must return an <code>int</code> value which is one of the following macros:
</p>
<dl compact="compact">
<dt> ‘<samp>LOCAL_SCAN_ACCEPT</samp>’</dt>
<dd><a name="IDX2675"></a>
<p>The message is accepted. If you pass back a string of text, it is saved with
the message, and made available in the variable <code>$local_scan_data</code>. No
newlines are permitted (if there are any, they are turned into spaces) and the
maximum length of text is 1000 characters.
</p>
</dd>
<dt> ‘<samp>LOCAL_SCAN_ACCEPT_FREEZE</samp>’</dt>
<dd><p>This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is
queued without immediate delivery, and is frozen.
</p>
</dd>
<dt> ‘<samp>LOCAL_SCAN_ACCEPT_QUEUE</samp>’</dt>
<dd><p>This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is
queued without immediate delivery.
</p>
</dd>
<dt> ‘<samp>LOCAL_SCAN_REJECT</samp>’</dt>
<dd><p>The message is rejected; the returned text is used as an error message which is
passed back to the sender and which is also logged. Newlines are permitted -
they cause a multiline response for SMTP rejections, but are converted to
‘<samp>\n</samp>’ in log lines. If no message is given, "Administrative prohibition" is
used.
</p>
</dd>
<dt> ‘<samp>LOCAL_SCAN_TEMPREJECT</samp>’</dt>
<dd><p>The message is temporarily rejected; the returned text is used as an error
message as for LOCAL_SCAN_REJECT. If no message is given, "Temporary local
problem" is used.
</p>
</dd>
<dt> ‘<samp>LOCAL_SCAN_REJECT_NOLOGHDR</samp>’</dt>
<dd><p>This behaves as LOCAL_SCAN_REJECT, except that the header of the rejected
message is not written to the reject log. It has the effect of unsetting the
<code>rejected_header</code> log selector for just this rejection. If
<code>rejected_header</code> is already unset (see the discussion of the
<code>log_selection</code> option in section <a href="spec_49.html#SEC450">Reducing or increasing what is logged</a>), this code is the
same as LOCAL_SCAN_REJECT.
</p>
</dd>
<dt> ‘<samp>LOCAL_SCAN_TEMPREJECT_NOLOGHDR</samp>’</dt>
<dd><p>This code is a variation of LOCAL_SCAN_TEMPREJECT in the same way that
LOCAL_SCAN_REJECT_NOLOGHDR is a variation of LOCAL_SCAN_REJECT.
</p></dd>
</dl>
<p>If the message is not being received by interactive SMTP, rejections are
reported by writing to <code>stderr</code> or by sending an email, as configured by the
<code>-oe</code> command line options.
</p>
<hr size="6">
<a name="Configuration-options-for-local_005fscan_005b_005d"></a>
<a name="SEC368"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC367" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC369" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC365" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC365" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_43.html#SEC374" 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"> 42.3 Configuration options for local_scan() </h2>
<p>It is possible to have option settings in the main configuration file
that set values in static variables in the <code>local_scan()</code> module. If you
want to do this, you must have the line
</p>
<table><tr><td> </td><td><pre class="example">LOCAL_SCAN_HAS_OPTIONS=yes
</pre></td></tr></table>
<p>in your ‘<tt>Local/Makefile</tt>’ when you build Exim. (This line is in
‘<tt>OS/Makefile-Default</tt>’, commented out). Then, in the <code>local_scan()</code> source
file, you must define static variables to hold the option values, and a table
to define them.
</p>
<p>The table must be a vector called <code>local_scan_options</code>, of type
‘<samp>optionlist</samp>’. Each entry is a triplet, consisting of a name, an option type,
and a pointer to the variable that holds the value. The entries must appear in
alphabetical order. Following <code>local_scan_options</code> you must also define a
variable called <code>local_scan_options_count</code> that contains the number of
entries in the table. Here is a short example, showing two kinds of option:
</p>
<table><tr><td> </td><td><pre class="example">static int my_integer_option = 42;
static uschar *my_string_option = US"a default string";
optionlist local_scan_options[] = {
{ "my_integer", opt_int, &my_integer_option },
{ "my_string", opt_stringptr, &my_string_option }
};
int local_scan_options_count =
sizeof(local_scan_options)/sizeof(optionlist);
</pre></td></tr></table>
<p>The values of the variables can now be changed from Exim's runtime
configuration file by including a local scan section as in this example:
</p>
<table><tr><td> </td><td><pre class="example">begin local_scan
my_integer = 99
my_string = some string of text...
</pre></td></tr></table>
<p>The available types of option data are as follows:
</p>
<dl compact="compact">
<dt> <strong>opt_bool</strong></dt>
<dd><p>This specifies a boolean (true/false) option. The address should point to a
variable of type ‘<samp>BOOL</samp>’, which will be set to TRUE or FALSE, which are macros
that are defined as "1" and "0", respectively. If you want to detect
whether such a variable has been set at all, you can initialize it to
TRUE_UNSET. (BOOL variables are integers underneath, so can hold more than two
values.)
</p>
</dd>
<dt> <strong>opt_fixed</strong></dt>
<dd><p>This specifies a fixed point number, such as is used for load averages.
The address should point to a variable of type ‘<samp>int</samp>’. The value is stored
multiplied by 1000, so, for example, 1.4142 is truncated and stored as 1414.
</p>
</dd>
<dt> <strong>opt_int</strong></dt>
<dd><p>This specifies an integer; the address should point to a variable of type
‘<samp>int</samp>’. The value may be specified in any of the integer formats accepted by
Exim.
</p>
</dd>
<dt> <strong>opt_mkint</strong></dt>
<dd><p>This is the same as <code>opt_int</code>, except that when such a value is output in a
<code>-bP</code> listing, if it is an exact number of kilobytes or megabytes, it is
printed with the suffix K or M.
</p>
</dd>
<dt> <strong>opt_octint</strong></dt>
<dd><p>This also specifies an integer, but the value is always interpreted as an
octal integer, whether or not it starts with the digit zero, and it is
always output in octal.
</p>
</dd>
<dt> <strong>opt_stringptr</strong></dt>
<dd><p>This specifies a string value; the address must be a pointer to a
variable that points to a string (for example, of type ‘<samp>uschar *</samp>’).
</p>
</dd>
<dt> <strong>opt_time</strong></dt>
<dd><p>This specifies a time interval value. The address must point to a variable of
type ‘<samp>int</samp>’. The value that is placed there is a number of seconds.
</p></dd>
</dl>
<p>If the <code>-bP</code> command line option is followed by ‘<samp>local_scan</samp>’, Exim prints
out the values of all the <code>local_scan()</code> options.
</p>
<hr size="6">
<a name="Available-Exim-variables"></a>
<a name="SEC369"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC368" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC370" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC365" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC365" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_43.html#SEC374" 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"> 42.4 Available Exim variables </h2>
<p>The header ‘<tt>local_scan.h</tt>’ gives you access to a number of C variables. These
are the only ones that are guaranteed to be maintained from release to release.
Note, however, that you can obtain the value of any Exim expansion variable,
including <code>$recipients</code>, by calling <em>expand_string()</em>. The exported
C variables are as follows:
</p>
<dl compact="compact">
<dt> <strong>intbody_linecount</strong></dt>
<dd><p>This variable contains the number of lines in the message's body.
</p>
</dd>
<dt> <strong>intbody_zerocount</strong></dt>
<dd><p>This variable contains the number of binary zero bytes in the message's body.
</p>
</dd>
<dt> <strong>unsignedintdebug_selector</strong></dt>
<dd><p>This variable is set to zero when no debugging is taking place. Otherwise, it
is a bitmap of debugging selectors. Two bits are identified for use in
<code>local_scan()</code>; they are defined as macros:
</p>
<ul class="toc">
<li>
The ‘<samp>D_v</samp>’ bit is set when <code>-v</code> was present on the command line. This is a
testing option that is not privileged - any caller may set it. All the
other selector bits can be set only by admin users.
</li><li>
The ‘<samp>D_local_scan</samp>’ bit is provided for use by <code>local_scan()</code>; it is set
by the ‘<samp>+local_scan</samp>’ debug selector. It is not included in the default set
of debugging bits.
</li></ul>
<p>Thus, to write to the debugging output only when ‘<samp>+local_scan</samp>’ has been
selected, you should use code like this:
</p>
<table><tr><td> </td><td><pre class="example">if ((debug_selector & D_local_scan) != 0)
debug_printf("xxx", ...);
</pre></td></tr></table>
</dd>
<dt> <strong>uschar*expand_string_message</strong></dt>
<dd><p>After a failing call to <em>expand_string()</em> (returned value NULL), the
variable <code>expand_string_message</code> contains the error message, zero-terminated.
</p>
</dd>
<dt> <strong>header_line*header_list</strong></dt>
<dd><p>A pointer to a chain of header lines. The <code>header_line</code> structure is
discussed below.
</p>
</dd>
<dt> <strong>header_line*header_last</strong></dt>
<dd><p>A pointer to the last of the header lines.
</p>
</dd>
<dt> <strong>uschar*headers_charset</strong></dt>
<dd><p>The value of the <code>headers_charset</code> configuration option.
</p>
</dd>
<dt> <strong>BOOLhost_checking</strong></dt>
<dd><p>This variable is TRUE during a host checking session that is initiated by the
<code>-bh</code> command line option.
</p>
</dd>
<dt> <strong>uschar*interface_address</strong></dt>
<dd><p>The IP address of the interface that received the message, as a string. This
is NULL for locally submitted messages.
</p>
</dd>
<dt> <strong>intinterface_port</strong></dt>
<dd><p>The port on which this message was received. When testing with the <code>-bh</code>
command line option, the value of this variable is -1 unless a port has been
specified via the <code>-oMi</code> option.
</p>
</dd>
<dt> <strong>uschar*message_id</strong></dt>
<dd><p>This variable contains Exim's message id for the incoming message (the value of
<code>$message_exim_id</code>) as a zero-terminated string.
</p>
</dd>
<dt> <strong>uschar*received_protocol</strong></dt>
<dd><p>The name of the protocol by which the message was received.
</p>
</dd>
<dt> <strong>intrecipients_count</strong></dt>
<dd><p>The number of accepted recipients.
</p>
</dd>
<dt> <strong>recipient_item*recipients_list</strong></dt>
<dd><a name="IDX2676"></a>
<a name="IDX2677"></a>
<p>The list of accepted recipients, held in a vector of length
<code>recipients_count</code>. The <code>recipient_item</code> structure is discussed below. You
can add additional recipients by calling <em>receive_add_recipient()</em> (see
below). You can delete recipients by removing them from the vector and
adjusting the value in <code>recipients_count</code>. In particular, by setting
<code>recipients_count</code> to zero you remove all recipients. If you then return the
value ‘<samp>LOCAL_SCAN_ACCEPT</samp>’, the message is accepted, but immediately
blackholed. To replace the recipients, you can set <code>recipients_count</code> to zero
and then call <em>receive_add_recipient()</em> as often as needed.
</p>
</dd>
<dt> <strong>uschar*sender_address</strong></dt>
<dd><p>The envelope sender address. For bounce messages this is the empty string.
</p>
</dd>
<dt> <strong>uschar*sender_host_address</strong></dt>
<dd><p>The IP address of the sending host, as a string. This is NULL for
locally-submitted messages.
</p>
</dd>
<dt> <strong>uschar*sender_host_authenticated</strong></dt>
<dd><p>The name of the authentication mechanism that was used, or NULL if the message
was not received over an authenticated SMTP connection.
</p>
</dd>
<dt> <strong>uschar*sender_host_name</strong></dt>
<dd><p>The name of the sending host, if known.
</p>
</dd>
<dt> <strong>intsender_host_port</strong></dt>
<dd><p>The port on the sending host.
</p>
</dd>
<dt> <strong>BOOLsmtp_input</strong></dt>
<dd><p>This variable is TRUE for all SMTP input, including BSMTP.
</p>
</dd>
<dt> <strong>BOOLsmtp_batched_input</strong></dt>
<dd><p>This variable is TRUE for BSMTP input.
</p>
</dd>
<dt> <strong>intstore_pool</strong></dt>
<dd><p>The contents of this variable control which pool of memory is used for new
requests. See section <a href="#SEC373">More about Exim's memory handling</a> for details.
</p></dd>
</dl>
<hr size="6">
<a name="Structure-of-header-lines"></a>
<a name="SEC370"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC369" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC371" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC365" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC365" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_43.html#SEC374" 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"> 42.5 Structure of header lines </h2>
<p>The <code>header_line</code> structure contains the members listed below.
You can add additional header lines by calling the <em>header_add()</em> function
(see below). You can cause header lines to be ignored (deleted) by setting
their type to *.
</p>
<dl compact="compact">
<dt> <strong>structheader_line*next</strong></dt>
<dd><p>A pointer to the next header line, or NULL for the last line.
</p>
</dd>
<dt> <strong>inttype</strong></dt>
<dd><p>A code identifying certain headers that Exim recognizes. The codes are printing
characters, and are documented in chapter <a href="spec_53.html#SEC490">Format of spool files</a> of this manual.
Notice in particular that any header line whose type is * is not transmitted
with the message. This flagging is used for header lines that have been
rewritten, or are to be removed (for example, <em>Envelope-sender:</em> header
lines.) Effectively, * means "deleted".
</p>
</dd>
<dt> <strong>intslen</strong></dt>
<dd><p>The number of characters in the header line, including the terminating and any
internal newlines.
</p>
</dd>
<dt> <strong>uschar*text</strong></dt>
<dd><p>A pointer to the text of the header. It always ends with a newline, followed by
a zero byte. Internal newlines are preserved.
</p></dd>
</dl>
<hr size="6">
<a name="Structure-of-recipient-items"></a>
<a name="SEC371"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC370" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC372" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC365" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC365" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_43.html#SEC374" 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"> 42.6 Structure of recipient items </h2>
<p>The <code>recipient_item</code> structure contains these members:
</p>
<dl compact="compact">
<dt> <strong>uschar*address</strong></dt>
<dd><p>This is a pointer to the recipient address as it was received.
</p>
</dd>
<dt> <strong>intpno</strong></dt>
<dd><p>This is used in later Exim processing when top level addresses are created by
the <code>one_time</code> option. It is not relevant at the time <code>local_scan()</code> is run
and must always contain -1 at this stage.
</p>
</dd>
<dt> <strong>uschar*errors_to</strong></dt>
<dd><p>If this value is not NULL, bounce messages caused by failing to deliver to the
recipient are sent to the address it contains. In other words, it overrides the
envelope sender for this one recipient. (Compare the <code>errors_to</code> generic
router option.) If a <code>local_scan()</code> function sets an <code>errors_to</code> field to
an unqualified address, Exim qualifies it using the domain from
<code>qualify_recipient</code>. When <code>local_scan()</code> is called, the <code>errors_to</code> field
is NULL for all recipients.
</p></dd>
</dl>
<hr size="6">
<a name="Available-Exim-functions"></a>
<a name="SEC372"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC371" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC373" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC365" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC365" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_43.html#SEC374" 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"> 42.7 Available Exim functions </h2>
<p>The header ‘<tt>local_scan.h</tt>’ gives you access to a number of Exim functions.
These are the only ones that are guaranteed to be maintained from release to
release:
</p>
<dl compact="compact">
<dt> <strong>pid_tchild_open(uschar**argv,uschar**envp,intnewumask,int*infdptr,int*outfdptr, BOOLmake_leader)</strong></dt>
<dd><p>This function creates a child process that runs the command specified by
<code>argv</code>. The environment for the process is specified by <code>envp</code>, which can
be NULL if no environment variables are to be passed. A new umask is supplied
for the process in <code>newumask</code>.
</p>
<p>Pipes to the standard input and output of the new process are set up
and returned to the caller via the <code>infdptr</code> and <code>outfdptr</code> arguments. The
standard error is cloned to the standard output. If there are any file
descriptors "in the way" in the new process, they are closed. If the final
argument is TRUE, the new process is made into a process group leader.
</p>
<p>The function returns the pid of the new process, or -1 if things go wrong.
</p>
</dd>
<dt> <strong>intchild_close(pid_tpid,inttimeout)</strong></dt>
<dd><p>This function waits for a child process to terminate, or for a timeout (in
seconds) to expire. A timeout value of zero means wait as long as it takes. The
return value is as follows:
</p>
<ul class="toc">
<li>
>= 0
<p>The process terminated by a normal exit and the value is the process
ending status.
</p>
</li><li>
< 0 and > -256
<p>The process was terminated by a signal and the value is the negation of the
signal number.
</p>
</li><li>
-256
<p>The process timed out.
</p>
</li><li>
-257
<p>The was some other error in wait(); <code>errno</code> is still set.
</p></li></ul>
</dd>
<dt> <strong>pid_tchild_open_exim(int*fd)</strong></dt>
<dd><p>This function provide you with a means of submitting a new message to
Exim. (Of course, you can also call ‘<tt>/usr/sbin/sendmail</tt>’ yourself if you
want, but this packages it all up for you.) The function creates a pipe,
forks a subprocess that is running
</p>
<table><tr><td> </td><td><pre class="example">exim -t -oem -oi -f <>
</pre></td></tr></table>
<p>and returns to you (via the ‘<samp>int *</samp>’ argument) a file descriptor for the pipe
that is connected to the standard input. The yield of the function is the PID
of the subprocess. You can then write a message to the file descriptor, with
recipients in <em>To:</em>, <em>Cc:</em>, and/or <em>Bcc:</em> header lines.
</p>
<p>When you have finished, call <em>child_close()</em> to wait for the process to
finish and to collect its ending status. A timeout value of zero is usually
fine in this circumstance. Unless you have made a mistake with the recipient
addresses, you should get a return code of zero.
</p>
</dd>
<dt> <strong>pid_tchild_open_exim2(int*fd,uschar*sender,uschar*sender_authentication)</strong></dt>
<dd><p>This function is a more sophisticated version of <em>child_open()</em>. The command
that it runs is:
</p>
<table><tr><td> </td><td><pre class="display">exim -t -oem -oi -f sender -oMas sender_authentication
</pre></td></tr></table>
<p>The third argument may be NULL, in which case the <code>-oMas</code> option is omitted.
</p>
</dd>
<dt> <strong>voiddebug_printf(char*,...)</strong></dt>
<dd><p>This is Exim's debugging function, with arguments as for <em>(printf()</em>. The
output is written to the standard error stream. If no debugging is selected,
calls to <em>debug_printf()</em> have no effect. Normally, you should make calls
conditional on the ‘<samp>local_scan</samp>’ debug selector by coding like this:
</p>
<table><tr><td> </td><td><pre class="example">if ((debug_selector & D_local_scan) != 0)
debug_printf("xxx", ...);
</pre></td></tr></table>
</dd>
<dt> <strong>uschar*expand_string(uschar*string)</strong></dt>
<dd><p>This is an interface to Exim's string expansion code. The return value is the
expanded string, or NULL if there was an expansion failure.
The C variable <code>expand_string_message</code> contains an error message after an
expansion failure. If expansion does not change the string, the return value is
the pointer to the input string. Otherwise, the return value points to a new
block of memory that was obtained by a call to <em>store_get()</em>. See section
<a href="#SEC373">More about Exim's memory handling</a> below for a discussion of memory handling.
</p>
</dd>
<dt> <strong>voidheader_add(inttype,char*format,...)</strong></dt>
<dd><p>This function allows you to an add additional header line at the end of the
existing ones. The first argument is the type, and should normally be a space
character. The second argument is a format string and any number of
substitution arguments as for <code>sprintf()</code>. You may include internal newlines
if you want, and you must ensure that the string ends with a newline.
</p>
</dd>
<dt> <strong>voidheader_add_at_position(BOOLafter,uschar*name,BOOLtopnot,inttype,char*format, ...)</strong></dt>
<dd><p>This function adds a new header line at a specified point in the header
chain. The header itself is specified as for <em>header_add()</em>.
</p>
<p>If <code>name</code> is NULL, the new header is added at the end of the chain if
<code>after</code> is true, or at the start if <code>after</code> is false. If <code>name</code> is not
NULL, the header lines are searched for the first non-deleted header that
matches the name. If one is found, the new header is added before it if
<code>after</code> is false. If <code>after</code> is true, the new header is added after the
found header and any adjacent subsequent ones with the same name (even if
marked "deleted"). If no matching non-deleted header is found, the <code>topnot</code>
option controls where the header is added. If it is true, addition is at the
top; otherwise at the bottom. Thus, to add a header after all the <em>Received:</em>
headers, or at the top if there are no <em>Received:</em> headers, you could use
</p>
<table><tr><td> </td><td><pre class="example">header_add_at_position(TRUE, US"Received", TRUE,
' ', "X-xxx: ...");
</pre></td></tr></table>
<p>Normally, there is always at least one non-deleted <em>Received:</em> header, but
there may not be if <code>received_header_text</code> expands to an empty string.
</p>
</dd>
<dt> <strong>voidheader_remove(intoccurrence,uschar*name)</strong></dt>
<dd><p>This function removes header lines. If <code>occurrence</code> is zero or negative, all
occurrences of the header are removed. If occurrence is greater than zero, that
particular instance of the header is removed. If no header(s) can be found that
match the specification, the function does nothing.
</p>
</dd>
<dt> <strong>BOOLheader_testname(header_line*hdr,uschar*name,intlength,BOOLnotdel)</strong></dt>
<dd><p>This function tests whether the given header has the given name. It is not just
a string comparison, because white space is permitted between the name and the
colon. If the <code>notdel</code> argument is true, a false return is forced for all
"deleted" headers; otherwise they are not treated specially. For example:
</p>
<table><tr><td> </td><td><pre class="example">if (header_testname(h, US"X-Spam", 6, TRUE)) ...
</pre></td></tr></table>
</dd>
<dt> <strong>uschar*lss_b64encode(uschar*cleartext,intlength)</strong></dt>
<dd><a name="IDX2678"></a>
<p>This function base64-encodes a string, which is passed by address and length.
The text may contain bytes of any value, including zero. The result is passed
back in dynamic memory that is obtained by calling <em>store_get()</em>. It is
zero-terminated.
</p>
</dd>
<dt> <strong>intlss_b64decode(uschar*codetext,uschar**cleartext)</strong></dt>
<dd><p>This function decodes a base64-encoded string. Its arguments are a
zero-terminated base64-encoded string and the address of a variable that is set
to point to the result, which is in dynamic memory. The length of the decoded
string is the yield of the function. If the input is invalid base64 data, the
yield is -1. A zero byte is added to the end of the output string to make it
easy to interpret as a C string (assuming it contains no zeros of its own). The
added zero byte is not included in the returned count.
</p>
</dd>
<dt> <strong>intlss_match_domain(uschar*domain,uschar*list)</strong></dt>
<dd><p>This function checks for a match in a domain list. Domains are always
matched caselessly. The return value is one of the following:
</p>
<table><tr><td> </td><td><pre class="display">OK match succeeded
FAIL match failed
DEFER match deferred
</pre></td></tr></table>
<p>DEFER is usually caused by some kind of lookup defer, such as the
inability to contact a database.
</p>
</dd>
<dt> <strong>intlss_match_local_part(uschar*localpart,uschar*list,BOOLcaseless)</strong></dt>
<dd><p>This function checks for a match in a local part list. The third argument
controls case-sensitivity. The return values are as for
<em>lss_match_domain()</em>.
</p>
</dd>
<dt> <strong>intlss_match_address(uschar*address,uschar*list,BOOLcaseless)</strong></dt>
<dd><p>This function checks for a match in an address list. The third argument
controls the case-sensitivity of the local part match. The domain is always
matched caselessly. The return values are as for <em>lss_match_domain()</em>.
</p>
</dd>
<dt> <strong>intlss_match_host(uschar*host_name,uschar*host_address,uschar*list)</strong></dt>
<dd><p>This function checks for a match in a host list. The most common usage is
expected to be
</p>
<table><tr><td> </td><td><pre class="example">lss_match_host(sender_host_name, sender_host_address, ...)
</pre></td></tr></table>
<a name="IDX2679"></a>
<p>An empty address field matches an empty item in the host list. If the host name
is NULL, the name corresponding to <code>$sender_host_address</code> is automatically
looked up if a host name is required to match an item in the list. The return
values are as for <em>lss_match_domain()</em>, but in addition, <em>lss_match_host()</em>
returns ERROR in the case when it had to look up a host name, but the lookup
failed.
</p>
</dd>
<dt> <strong>voidlog_write(unsignedintselector,intwhich,char*format,...)</strong></dt>
<dd><p>This function writes to Exim's log files. The first argument should be zero (it
is concerned with <code>log_selector</code>). The second argument can be ‘<samp>LOG_MAIN</samp>’ or
‘<samp>LOG_REJECT</samp>’ or ‘<samp>LOG_PANIC</samp>’ or the inclusive "or" of any combination of
them. It specifies to which log or logs the message is written. The remaining
arguments are a format and relevant insertion arguments. The string should not
contain any newlines, not even at the end.
</p>
</dd>
<dt> <strong>voidreceive_add_recipient(uschar*address,intpno)</strong></dt>
<dd><p>This function adds an additional recipient to the message. The first argument
is the recipient address. If it is unqualified (has no domain), it is qualified
with the <code>qualify_recipient</code> domain. The second argument must always be -1.
</p>
<p>This function does not allow you to specify a private <code>errors_to</code> address (as
described with the structure of <code>recipient_item</code> above), because it pre-dates
the addition of that field to the structure. However, it is easy to add such a
value afterwards. For example:
</p>
<table><tr><td> </td><td><pre class="example"> receive_add_recipient(US"monitor@mydom.example", -1);
recipients_list[recipients_count-1].errors_to =
US"postmaster@mydom.example";
</pre></td></tr></table>
</dd>
<dt> <strong>BOOLreceive_remove_recipient(uschar*recipient)</strong></dt>
<dd><p>This is a convenience function to remove a named recipient from the list of
recipients. It returns true if a recipient was removed, and false if no
matching recipient could be found. The argument must be a complete email
address.
</p></dd>
</dl>
<a name="IDX2680"></a>
<dl compact="compact">
<dt> <strong>uscharrfc2047_decode(uschar*string,BOOLlencheck,uschar*target,intzeroval,int*lenptr, uschar**error)</strong></dt>
<dd><p>This function decodes strings that are encoded according to RFC 2047. Typically
these are the contents of header lines. First, each "encoded word" is decoded
from the Q or B encoding into a byte-string. Then, if provided with the name of
a charset encoding, and if the <code>iconv()</code> function is available, an attempt is
made to translate the result to the named character set. If this fails, the
binary string is returned with an error message.
</p>
<p>The first argument is the string to be decoded. If <code>lencheck</code> is TRUE, the
maximum MIME word length is enforced. The third argument is the target
encoding, or NULL if no translation is wanted.
</p>
<a name="IDX2681"></a>
<a name="IDX2682"></a>
<p>If a binary zero is encountered in the decoded string, it is replaced by the
contents of the <code>zeroval</code> argument. For use with Exim headers, the value must
not be 0 because header lines are handled as zero-terminated strings.
</p>
<p>The function returns the result of processing the string, zero-terminated; if
<code>lenptr</code> is not NULL, the length of the result is set in the variable to
which it points. When <code>zeroval</code> is 0, <code>lenptr</code> should not be NULL.
</p>
<p>If an error is encountered, the function returns NULL and uses the <code>error</code>
argument to return an error message. The variable pointed to by <code>error</code> is
set to NULL if there is no error; it may be set non-NULL even when the function
returns a non-NULL value if decoding was successful, but there was a problem
with translation.
</p>
</dd>
<dt> <strong>intsmtp_fflush(void)</strong></dt>
<dd><p>This function is used in conjunction with <em>smtp_printf()</em>, as described
below.
</p>
</dd>
<dt> <strong>voidsmtp_printf(char*,...)</strong></dt>
<dd><p>The arguments of this function are like <code>printf()</code>; it writes to the SMTP
output stream. You should use this function only when there is an SMTP output
stream, that is, when the incoming message is being received via interactive
SMTP. This is the case when <code>smtp_input</code> is TRUE and <code>smtp_batched_input</code>
is FALSE. If you want to test for an incoming message from another host (as
opposed to a local process that used the <code>-bs</code> command line option), you can
test the value of <code>sender_host_address</code>, which is non-NULL when a remote host
is involved.
</p>
<p>If an SMTP TLS connection is established, <em>smtp_printf()</em> uses the TLS
output function, so it can be used for all forms of SMTP connection.
</p>
<p>Strings that are written by <em>smtp_printf()</em> from within <code>local_scan()</code>
must start with an appropriate response code: 550 if you are going to return
LOCAL_SCAN_REJECT, 451 if you are going to return
LOCAL_SCAN_TEMPREJECT, and 250 otherwise. Because you are writing the
initial lines of a multi-line response, the code must be followed by a hyphen
to indicate that the line is not the final response line. You must also ensure
that the lines you write terminate with CRLF. For example:
</p>
<table><tr><td> </td><td><pre class="example">smtp_printf("550-this is some extra info\r\n");
return LOCAL_SCAN_REJECT;
</pre></td></tr></table>
<p>Note that you can also create multi-line responses by including newlines in
the data returned via the <code>return_text</code> argument. The added value of using
<em>smtp_printf()</em> is that, for instance, you could introduce delays between
multiple output lines.
</p>
<p>The <em>smtp_printf()</em> function does not return any error indication, because it
does not automatically flush pending output, and therefore does not test
the state of the stream. (In the main code of Exim, flushing and error
detection is done when Exim is ready for the next SMTP input command.) If
you want to flush the output and check for an error (for example, the
dropping of a TCP/IP connection), you can call <em>smtp_fflush()</em>, which has no
arguments. It flushes the output stream, and returns a non-zero value if there
is an error.
</p>
</dd>
<dt> <strong>void*store_get(int)</strong></dt>
<dd><p>This function accesses Exim's internal store (memory) manager. It gets a new
chunk of memory whose size is given by the argument. Exim bombs out if it ever
runs out of memory. See the next section for a discussion of memory handling.
</p>
</dd>
<dt> <strong>void*store_get_perm(int)</strong></dt>
<dd><p>This function is like <em>store_get()</em>, but it always gets memory from the
permanent pool. See the next section for a discussion of memory handling.
</p>
</dd>
<dt> <strong>uschar*string_copy(uschar*string)</strong></dt>
<dd><p>See below.
</p>
</dd>
<dt> <strong>uschar*string_copyn(uschar*string,intlength)</strong></dt>
<dd><p>See below.
</p>
</dd>
<dt> <strong>uschar*string_sprintf(char*format,...)</strong></dt>
<dd><p>These three functions create strings using Exim's dynamic memory facilities.
The first makes a copy of an entire string. The second copies up to a maximum
number of characters, indicated by the second argument. The third uses a format
and insertion arguments to create a new string. In each case, the result is a
pointer to a new string in the current memory pool. See the next section for
more discussion.
</p></dd>
</dl>
<hr size="6">
<a name="More-about-Exim_0027s-memory-handling"></a>
<a name="SEC373"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC372" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="spec_43.html#SEC374" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC365" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC365" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_43.html#SEC374" 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"> 42.8 More about Exim's memory handling </h2>
<p>No function is provided for freeing memory, because that is never needed.
The dynamic memory that Exim uses when receiving a message is automatically
recycled if another message is received by the same process (this applies only
to incoming SMTP connections - other input methods can supply only one
message at a time). After receiving the last message, a reception process
terminates.
</p>
<p>Because it is recycled, the normal dynamic memory cannot be used for holding
data that must be preserved over a number of incoming messages on the same SMTP
connection. However, Exim in fact uses two pools of dynamic memory; the second
one is not recycled, and can be used for this purpose.
</p>
<p>If you want to allocate memory that remains available for subsequent messages
in the same SMTP connection, you should set
</p>
<table><tr><td> </td><td><pre class="example">store_pool = POOL_PERM
</pre></td></tr></table>
<p>before calling the function that does the allocation. There is no need to
restore the value if you do not need to; however, if you do want to revert to
the normal pool, you can either restore the previous value of <code>store_pool</code> or
set it explicitly to POOL_MAIN.
</p>
<p>The pool setting applies to all functions that get dynamic memory, including
<em>expand_string()</em>, <em>store_get()</em>, and the <em>string_xxx()</em> functions.
There is also a convenience function called <em>store_get_perm()</em> that gets a
block of memory from the permanent pool while preserving the value of
<code>store_pool</code>.
<a name="IDX2683"></a>
</p>
<hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC365" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="spec_43.html#SEC374" 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
>
146
