aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2007-04-27 20:45:53 +0000
committerSergey Poznyakoff <gray@gnu.org.ua>2007-04-27 20:45:53 +0000
commitf1133249d78b4de8a1897f256dba5fabb09646f3 (patch)
tree0765ea6be492498188be4af0432b0fa8fa54f0b2 /doc
parent4d3f1f3b87ccb7b42c98b804d86d26504b2fc383 (diff)
downloadmailfromd-f1133249d78b4de8a1897f256dba5fabb09646f3.tar.gz
mailfromd-f1133249d78b4de8a1897f256dba5fabb09646f3.tar.bz2
Implement begin/end statements. Allow to disable/enable caching
git-svn-id: file:///svnroot/mailfromd/trunk@1387 7a8a7f39-df28-0410-adc6-e0d955640f24
Diffstat (limited to 'doc')
-rw-r--r--doc/mailfromd.texi145
1 files changed, 138 insertions, 7 deletions
diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi
index 6ba94777..f65d4615 100644
--- a/doc/mailfromd.texi
+++ b/doc/mailfromd.texi
@@ -157,7 +157,8 @@ Mail Filtering Language
* Constants::
* Variables::
* Back references::
-* Handlers::
+* Handlers::
+* begin/end::
* Functions:: Functions.
* Expressions:: Expressions.
* Statements::
@@ -1082,14 +1083,27 @@ be supplied its own handling procedure. A missing procedure implies
@cindex milter state handler, described
@cindex handler, described
+@cindex connect, handler
+@cindex helo, handler
+@cindex envfrom, handler
+@cindex envrcpt, handler
+@cindex header, handler
+@cindex eoh, handler
+@cindex body, handler
+@cindex eom, handler
+@cindex begin, special handler
+@cindex end, special handler
@anchor{handler names}
A filter script can define up to eight @dfn{milter state handlers},
called after the names of milter states: @samp{connect}, @samp{helo},
@samp{envfrom}, @samp{envrcpt}, @samp{header}, @samp{eoh},
-@samp{body}, and @samp{eom}. The diagram below shows the control flow
-when processing an @acronym{SMTP} transaction. Lines marked with
-@code{C:} show @acronym{SMTP} commands issued by the remote machine
-(the @dfn{client}), those marked with @samp{@result{}} show called handlers
+@samp{body}, and @samp{eom}. Two special handlers are available for
+initialization and cleran-up purposes: @samp{begin} is called before
+the processing starts, and @samp{end} is called after it is finished.
+The diagram below shows the control flow when processing an
+@acronym{SMTP} transaction. Lines marked with @code{C:} show
+@acronym{SMTP} commands issued by the remote machine (the
+@dfn{client}), those marked with @samp{@result{}} show called handlers
with their arguments. An @r{[R]} appearing at the right end of a line
indicates that this part of the transaction can be repeated any number
of times:
@@ -1098,6 +1112,7 @@ of times:
@caption{Mailfromd Control Flow}
@smallexample
@group
+@result{} begin
@result{} connect(@var{hostname}, @var{family}, @var{port}, @samp{IP address})
C: HELO @var{domain}
helo(@var{domain})
@@ -1124,7 +1139,8 @@ do
C: .
@result{} eom
- done
+ done
+@result{} end
@end group
@end smallexample
@end float
@@ -2938,7 +2954,8 @@ amount of white-space characters (i.e. spaces, tabulations or newlines).
* Constants::
* Variables::
* Back references::
-* Handlers::
+* Handlers::
+* begin/end::
* Functions:: Functions.
* Expressions:: Expressions.
* Statements::
@@ -4526,6 +4543,119 @@ For your reference, the following table shows each handler with its arguments:
@end multitable
@end float
+@node begin/end
+@section The @samp{begin} and @samp{end} special handlers
+@cindex begin, special handler
+@cindex end, special handler
+@cindex startup handler
+@cindex handler, startup
+@cindex handler, initialization
+@cindex cleanup handler
+@cindex handler, cleanup
+ Apart from milter handlers defined previously, @acronym{MFL}
+defines two special handlers, called @samp{begin} and @samp{end},
+which supply startup and cleanup instruction for the filter program.
+
+ The @samp{begin} special handler is executed once for each
+@acronym{SMTP} session, after the connection has been established but
+before the first milter handler has been called. Similarly, an
+@samp{end} handler is executed exactly once, after the connection has
+been closed. Neither of handlers takes any arguments.
+
+ The two handlers are defined using the following syntax:
+
+@smallexample
+# @r{Begin handler}
+begin
+do
+ @dots{}
+done
+
+# @r{End handler}
+end
+do
+ @dots{}
+done
+@end smallexample
+
+@noindent
+where @samp{@dots{}} represent any @acronym{MFL} statements.
+
+ An @acronym{MFL} program may have multiple @samp{begin} and
+@samp{end} definitions. They can be intermixed with other
+definitions. The compiler combines all @samp{begin}
+statements into a single one, in the order they appear in the
+sources. Similarly, all @samp{end} blocks are concatenated together.
+The resulting @samp{begin} is called once, at the beginning of each
+@acronym{SMTP} session, and @samp{end} is called once at its
+termination.
+
+ Multiple @samp{begin} and @samp{end} handlers are a useful feature
+for writing modules (@pxref{Modules}), because each module can thus
+have its own initialization and cleanup blocks. Notice, however, that
+in this case the order in which subsequent @samp{begin} and @samp{end}
+blocks are executed is not defined. It is only warranted, that all
+@samp{begin} blocks are executed at startup and all @samp{end} blocks
+are executed at shutdown. It is also warranted that all @samp{begin}
+and @samp{end} blocks defined within a compilation unit (i.e. a single
+abstract source file, whith all @code{#include} and
+@code{#include_once} statements expanded in place) are executed in
+order of their appearance in the unit.
+
+@cindex @samp{begin}, handler restrictions
+@cindex @samp{end}, handler restrictions
+ Due to their special nature, the startup and cleanup blocks impose
+certain restrictions on the statements that can be used within them:
+
+@enumerate 1
+@cindex @code{return} in @samp{begin}
+@cindex @samp{begin} and @code{return}
+@cindex @code{return} in @samp{end}
+@cindex @samp{end} and @code{return}
+@item @code{return} cannot be used in @samp{begin} and @samp{end}
+handlers. @FIXME{But could it be a useful feature?}
+
+@cindex @code{accept} in @samp{begin}
+@cindex @samp{begin} and @code{accept}
+@cindex @code{accept} in @samp{end}
+@cindex @samp{end} and @code{accept}
+@cindex @code{continue} in @samp{begin}
+@cindex @samp{begin} and @code{continue}
+@cindex @code{continue} in @samp{end}
+@cindex @samp{end} and @code{continue}
+@cindex @code{discard} in @samp{begin}
+@cindex @samp{begin} and @code{discard}
+@cindex @code{discard} in @samp{end}
+@cindex @samp{end} and @code{discard}
+@cindex @code{reject} in @samp{begin}
+@cindex @samp{begin} and @code{reject}
+@cindex @code{reject} in @samp{end}
+@cindex @samp{end} and @code{reject}
+@cindex @code{tempfail} in @samp{begin}
+@cindex @samp{begin} and @code{tempfail}
+@cindex @code{tempfail} in @samp{end}
+@cindex @samp{end} and @code{tempfail}
+@item The following Sendmail actions cannot be used in them:
+@code{accept}, @code{continue}, @code{discard}, @code{reject},
+@code{tempfail}.
+
+@cindex @code{add} in @samp{begin}
+@cindex @samp{begin} and @code{add}
+@cindex @code{add} in @samp{end}
+@cindex @samp{end} and @code{add}
+@cindex @code{replace} in @samp{begin}
+@cindex @samp{begin} and @code{replace}
+@cindex @code{replace} in @samp{end}
+@cindex @samp{end} and @code{replace}
+@cindex @code{delete} in @samp{begin}
+@cindex @samp{begin} and @code{delete}
+@cindex @code{delete} in @samp{end}
+@cindex @samp{end} and @code{delete}
+@item Header manipulation actions (@pxref{header manipulation}) can be
+used only in @samp{begin} header.
+@end enumerate
+
+@FIXME{Examples of @samp{begin}/@samp{end}}
@node Functions
@section Functions
@@ -7391,6 +7521,7 @@ reject 503 5.0.0 "Need HELO command"
@end group
@end smallexample
+@anchor{header manipulation}
@cindex Header manipulation actions
Header manipulation actions allow you to add, delete or modify
message @acronym{RFC} 2822 headers.

Return to:

Send suggestions and report system problems to the System administrator.