diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2007-04-30 11:06:00 +0000 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2007-04-30 11:06:00 +0000 |
commit | aa1fefb873bdfaf9591e2991df446e7f4d9646b1 (patch) | |
tree | 6e223f9ff64604151d1d28eabcbc6ddb60e22528 /doc | |
parent | f5f4f4f7135e354f4a5c68d1b68db67562e42250 (diff) | |
download | mailfromd-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.texi | 106 |
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 |