aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2007-04-30 11:06:00 +0000
committerSergey Poznyakoff <gray@gnu.org.ua>2007-04-30 11:06:00 +0000
commitaa1fefb873bdfaf9591e2991df446e7f4d9646b1 (patch)
tree6e223f9ff64604151d1d28eabcbc6ddb60e22528 /doc
parentf5f4f4f7135e354f4a5c68d1b68db67562e42250 (diff)
downloadmailfromd-aa1fefb873bdfaf9591e2991df446e7f4d9646b1.tar.gz
mailfromd-aa1fefb873bdfaf9591e2991df446e7f4d9646b1.tar.bz2
Update
git-svn-id: file:///svnroot/mailfromd/trunk@1395 7a8a7f39-df28-0410-adc6-e0d955640f24
Diffstat (limited to 'doc')
-rw-r--r--doc/mailfromd.texi106
1 files changed, 104 insertions, 2 deletions
diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi
index 9d72db8d..3e619e6c 100644
--- a/doc/mailfromd.texi
+++ b/doc/mailfromd.texi
@@ -139,6 +139,7 @@ Tutorial
* Testing Filter Scripts::
* Logging and Debugging::
* Runtime errors::
+* Cautions::
Databases
@@ -1021,6 +1022,7 @@ interaction with the Mail Transport Agent.
* Testing Filter Scripts::
* Logging and Debugging::
* Runtime errors::
+* Cautions::
@end menu
@node Start Up
@@ -1317,6 +1319,7 @@ names of the formal parameters and the result type, if the function is
to return a meaningful value (function definitions in @acronym{MFL}
are discussed in detail in @pxref{User-defined, User-Defined Functions}).
+@anchor{funcall}
@cindex function calls
A function is invoked using a special construct, @dfn{function
call}:
@@ -1348,7 +1351,7 @@ hostname $client_addr
@noindent
However, such syntax creates several ambiguities, so use it sparingly
if at all. We recommend to always use parentheses when calling a
-function. @FIXME{explain why.}
+function; @xref{Cautions}, for the detailed analysis of of this syntax.
When a function does not deliver a result, it should only be called
as a statement.
@@ -2929,6 +2932,104 @@ the error and fix it.
calling the @code{stack_trace} function. This can be useful for
debugging, or in your @code{catch} statements.
+@node Cautions
+@section Warnings about some slippery places in @acronym{MFL}
+
+@quotation
+It seemed like a good idea at the time.
+
+--- Brian Kernighan
+@end quotation
+
+ There are some features of @acronym{MFL} which, when used improperly,
+may lead to subtle, hard identifiable errors. These are: concatenation
+operation (@pxref{Concatenation}) and passing arguments to
+one-argument functions without parentheses (@pxref{funcall, Function
+call syntax}).
+
+ Since there is no explicit operator for concatenation, it is often
+necessary to ensure that it happens at the right time by using
+parentheses to enclose the items to concatenate. Consider the
+following example:
+
+@smallexample
+echo toupper "some" "thing"
+@end smallexample
+
+ Should it print @samp{SOMETHING} or just @samp{SOMEthing}? The
+correct answer is the former, but it is difficult to deduce unless you
+are well acquainted the @acronym{MFL} precedence rules
+(@pxref{Precedence}). Therefore, the rule of thumb is: whenever in
+doubt, parenthesize:
+
+@smallexample
+echo toupper("some" "thing") @result{} "SOMETHING"
+echo toupper("some") "thing" @result{} "SOMEthing"
+@end smallexample
+
+ Quoteless literals (@pxref{Literals}) are yet another dangerous
+feature. Just as the features mentioned above, it stems from the
+good old days when @acronym{MFL} was small and sweet and using
+literals without quotes indeed ``seemed a good idea at the time.'' It
+ceased to seem so after the introduction of user-defined functions,
+though. Consider the following @emph{entire} program text:
+
+@smallexample
+@group
+prog envfrom
+do
+ if hostname($client_addr) = $client_addr
+ reject
+ fi
+done
+@end group
+@end smallexample
+
+ The intent was obviously to reject any mail if it comes from an
+address without a proper @code{PTR} record (@pxref{hostname
+function}). There is a serious error, however: @code{hostname} is not
+a built-in function as it used to be in previous releases@footnote{Up to
+the version 1.3.91.}, and therefore it needs to be defined or required
+prior to using. Otherwise it is no more than a literal, and the whole
+construct @samp{hostname($client_addr)} is regarded by @acronym{MFL}
+compiler as a concatenation of the string @samp{hostname} and the
+value of @samp{client_addr} Sendmail variable. It is easy to see
+using @option{--dump-tree} option:
+
+@smallexample
+$ @kbd{mailfromd --dump-tree test.mf}
+State handlers:
+---------------
+envfrom:
+COND:
+EQ
+ CONCAT:
+ STRING: "hostname"
+ SYMBOL: @{client_addr@}
+ SYMBOL: @{client_addr@}
+IFTRUE
+ reject
+IFFALSE
+@end smallexample
+
+ In effect, the comparison is always false and @code{reject} is never
+called.
+
+ That is why starting from version 3.0 @command{mailfromd} warns
+about any occurrence of an unquoted identifier. In fact, running
+@option{--lint} on the above program, gives:
+
+@smallexample
+$ @kbd{mailfromd --lint test.mf}
+mailfromd: test.mf:3: warning: unquoted identifier `hostname'
+@end smallexample
+
+ Whenever you see such a message, be sure to inspect the source and
+to place quotes around the suspicious string, if it is intended to be
+used as a literal, or to require the corresponding module
+(@pxref{Modules}) (or include the source file directly,
+@pxref{include}), if it is indeed a function name.
+
@node MFL, Mailfromd Configuration, Tutorial, Top
@chapter Mail Filtering Language
@cindex MFL
@@ -5326,6 +5427,7 @@ raises the exception @code{not_found}.
@code{temp_failure}, depending on the character of the failure.
@end deftypefn
+@anchor{hostname function}
@deftypefn {Library Function} string hostname (string @var{ip})
The @var{ip} argument should be a string representing an @acronym{IP} address in
@dfn{dotted-quad} notation. The function returns the canonical name of
@@ -8269,7 +8371,7 @@ throw @var{excode} @var{descr}
@code{catch} statement: @var{excode} gives the numeric code of the
exception, @var{descr} gives its textual description. This statement
can be used in complex scripts to create non-local exits from deeply
-nested statements. @FIXME{(Elaborate on that).}
+nested statements. @FIXME{Elaborate on that.}
Notice several limitations of @code{throw}: first, the @var{excode}
argument must be an immediate value, you cannot use an expression in

Return to:

Send suggestions and report system problems to the System administrator.