diff options
Diffstat (limited to 'doc/mailfromd.texi')
-rw-r--r-- | doc/mailfromd.texi | 86 |
1 files changed, 76 insertions, 10 deletions
diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi index 3d2e43c5..090222eb 100644 --- a/doc/mailfromd.texi +++ b/doc/mailfromd.texi @@ -1352,22 +1352,27 @@ message for delivery, without any further interaction with The word @code{accept} in the above example is an @dfn{action}. @dfn{Action} is a special language statement that causes the execution of the program to stop and to return a response code to the @command{Sendmail}. There are five actions, one for each response code: @code{continue}, @code{accept}, @code{reject}, @code{discard}, and @code{tempfail}. Among these, @code{reject} and @code{discard} -can optionally take one to three arguments. The first -argument is a three-digit @acronym{RFC} 2821 reply code. It must begin with -@samp{5} for @code{reject} and with @samp{4} for @code{tempfail}. If -two arguments are supplied, the second argument must be either an -@dfn{extended reply code} (@acronym{RFC} 1893/2034) or a textual string to be +can optionally take one to three arguments. There are two ways of +supplying the arguments. + +In the first form, called @dfn{literal} or @dfn{traditional} notation, +the arguments are supplied as additional words after the action name, +separated by whitespace. The first argument is a three-digit +@acronym{RFC} 2821 reply code. It must begin with @samp{5} for +@code{reject} and with @samp{4} for @code{tempfail}. If two arguments +are supplied, the second argument must be either an @dfn{extended +reply code} (@acronym{RFC} 1893/2034) or a textual string to be returned along with the @acronym{SMTP} reply. Finally, if all three arguments are supplied, then the second one must be an extended reply code and the third one must supply the textual string. The following examples illustrate all possible ways of using the @code{reject} -statement: +statement in literal notation: @smallexample @group reject reject 503 reject 503 5.0.0 @@ -1376,12 +1381,31 @@ reject 503 5.0.0 "Need HELO command" @end group @end smallexample @noindent Please note the quotes around the textual string. +Another form for these action is called @dfn{functional} notation, +because it resembles the function syntax. When used in this form, the +action word is followed by a parenthesized group of exactly three +arguments, separated by commas. The meaning and ordering of the +argument is the same as in literal form. Any of three arguments may +be absent, in which case it will be replaced by the default value. To +illustrate this, here are the statements from the previous example, +written in functional notation: + +@smallexample +@group +reject(,,) +reject(503,,) +reject(503, 5.0.0) +reject(503,, "Need HELO command") +reject(503, 5.0.0, "Need HELO command") +@end group +@end smallexample + @node Conditional Execution @section Conditional Execution Programs consisting of a single action are rarely useful. In most cases you will want to do some checking and decide whether to process the message depending on its result. For example, if you do not want @@ -10250,30 +10274,33 @@ program. @cindex actions An @dfn{action} statement instructs @command{mailfromd} to perform a certain action over the message being processed. There are two kinds of actions: return actions and header manipulation actions. - Return actions tell @command{Sendmail} to return given response code +@subsubheading Reply Actions +Reply actions tell @command{Sendmail} to return given response code to the remote party. There are five such actions: @table @code @item accept @cindex accept action, defined @kwindex accept Return an @code{accept} reply. The remote party will continue transmitting its message. -@item reject [@var{code}] [@var{excode}] [@var{message}] +@item reject @var{code} @var{excode} @var{message-expr} +@itemx reject (@var{code-expr}, @var{excode-expr}, @var{message-expr}) @cindex reject action, defined @kwindex reject Return a @code{reject} reply. The remote party will have to cancel transmitting its message. The three arguments are optional, their usage is described below. -@item tempfail [@var{code}] [@var{excode}] [@var{message}] +@item tempfail @var{code} @var{excode} @var{message} +@itemx tempfail (@var{code-expr}, @var{excode-expr}, @var{message-expr}) @cindex tempfail action, defined @kwindex tempfail Return a @samp{temporary failure} reply. The remote party can retry to send its message later. The three arguments are optional, their usage is described below. @@ -10289,13 +10316,18 @@ it without delivering it to any recipient. Stops the current handler and instructs @command{Sendmail} to continue processing of the message. @end table @anchor{reject} Two actions, @code{reject} and @code{tempfail} can take up to three -optional parameters. The first argument is a three-digit +optional parameters. There are two forms of supplying these +parameters. + +In the first form, called @dfn{literal} or @dfn{traditional} notation, +the arguments are supplied as additional words after the action name, +and are separated by whitespace. The first argument is a three-digit @acronym{RFC} 2821 reply code. It must begin with @samp{5} for @code{reject} and with @samp{4} for @code{tempfail}. If two arguments are supplied, the second argument must be either an @dfn{extended reply code} (@acronym{RFC} 1893/2034) or a textual string to be returned along with the @acronym{SMTP} reply. Finally, if all three arguments are supplied, then the second one must be an extended reply @@ -10310,12 +10342,46 @@ reject 503 reject 503 5.0.0 reject 503 "Need HELO command" reject 503 5.0.0 "Need HELO command" @end group @end smallexample +The notion @dfn{textual string}, used above means either a literal +string or an @acronym{MFL} expression that evaluates to string. +However, both code and extended code must always be literal. + +The second form of supplying arguments is called @dfn{functional} +notation, because it resembles the function syntax. When used in this +form, the action word is followed by a parenthesized group of exactly +three arguments, separated by commas. Each argument is a +@acronym{MFL} expression. The meaning and ordering of the arguments is +the same as in literal form. Any or all of these three arguments may +be absent, in which case it will be replaced by the default value. To +illustrate this, here are the statements from the previous example, +written in functional notation: + +@smallexample +@group +reject(,,) +reject(503,,) +reject(503, 5.0.0) +reject(503, "Need HELO command",) +reject(503, 5.0.0, "Need HELO command") +@end group +@end smallexample + + Notice that there is an important difference between the two +notations. The functional notation allows to compute both reply codes +at run time, e.g.: + +@smallexample + reject(500 + %dig2*10 + %dig3, "5." %edig2 "." %edig2) +@end smallexample + +@subsubheading Header Actions + @anchor{header manipulation} @cindex header manipulation actions @cindex actions, header manipulation Header manipulation actions provide basic means to add, delete or modify the message @acronym{RFC} 2822 headers. |