aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2007-06-06 20:17:32 +0000
committerSergey Poznyakoff <gray@gnu.org.ua>2007-06-06 20:17:32 +0000
commit2579949551251da5cbf37f049e04635c818a1396 (patch)
treedf21c2c5768a1f51304ce2eff0249a454be1c807 /doc
parent2dbbad64c6cd896c81d9bc479ee4228f01727e7a (diff)
downloadmailfromd-2579949551251da5cbf37f049e04635c818a1396.tar.gz
mailfromd-2579949551251da5cbf37f049e04635c818a1396.tar.bz2
Update
git-svn-id: file:///svnroot/mailfromd/trunk@1487 7a8a7f39-df28-0410-adc6-e0d955640f24
Diffstat (limited to 'doc')
-rw-r--r--doc/mailfromd.texi60
1 files changed, 47 insertions, 13 deletions
diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi
index 2426269b..cab2db33 100644
--- a/doc/mailfromd.texi
+++ b/doc/mailfromd.texi
@@ -3275,6 +3275,35 @@ 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.
+ Another place to execute special caution are format strings used
+with @code{sprintf} (@pxref{String formatting}) and @code{strftime}
+(@anchor{strftime}) functions. They use @samp{%} as a character
+introducing conversion specifiers, while the same character is used to
+expand a @acronym{MFL} variable within a string. To prevent this
+misinterpretation, enclose format specification in @emph{single
+quotes} (@pxref{singe-vs-double}). To illustrate this, let's consider
+the following example:
+
+@smallexample
+echo sprintf ("Mail from %s", $f)
+@end smallexample
+
+ If a variable @code{s} is not declared, this line will produce the
+@samp{Variable s is not defined} error message, which will allow you
+to identify and fix the bug. The situation is considerably worse if
+@code{s} is declared. In that case you will see no warning message,
+as the statement is perfectly valid, but at the run-time the variable
+@code{s} will be interpreted within the format string, and its value
+will replace @code{%s}. To prevent this from happening, single quotes
+must be used:
+
+@smallexample
+echo sprintf ('Mail from %s', $f)
+@end smallexample
+
+This does not limit the functionality, since there is no need to fall
+back to variable interpretation in format strings.
+
@node MFL, Using MFL Mode, Tutorial, Top
@chapter Mail Filtering Language
@cindex MFL
@@ -5358,17 +5387,21 @@ character @samp{%}, and ends with a conversion specifier. In
between there may be (in this order) zero or more @dfn{flags},
an optional @dfn{minimum field width}, and an optional @dfn{precision}.
+Notice, that in practice that means that you should use single quotes
+with the @var{format} arguments, to protect conversion specifications from
+being recognized as variable references (@pxref{singe-vs-double}).
+
No type conversion is done on arguments, so it is important that the
-supplied arguments must correspond properly with the corresponding
-conversion specifiers. By default, the arguments are used in the
-order given, where each @samp{*} and each conversion specifier asks
-for the next argument. If insufficiently many arguments are given,
-@code{sprintf} raises @samp{range} exception. One can also specify
-explicitly which argument is taken, at each place where an argument is
-required, by writing @samp{%@var{m}$}, instead of @samp{%} and
-@samp{*@var{m}$} instead of @samp{*}, where the decimal integer
-@var{m} denotes the position in the argument list of the desired
-argument, indexed starting from 1. Thus,
+supplied arguments match their corresponding conversion specifiers.
+By default, the arguments are used in the order given, where each
+@samp{*} and each conversion specifier asks for the next argument. If
+insufficiently many arguments are given, @code{sprintf} raises
+@samp{range} exception. One can also specify explicitly which
+argument is taken, at each place where an argument is required, by
+writing @samp{%@var{m}$}, instead of @samp{%} and @samp{*@var{m}$}
+instead of @samp{*}, where the decimal integer @var{m} denotes the
+position in the argument list of the desired argument, indexed
+starting from 1. Thus,
@smallexample
sprintf('%*d', %width, %num);
@@ -6314,6 +6347,7 @@ The function @code{revip} is defined in @ref{revip}.
measured in seconds.
@end deftypefn
+@anchor{strftime}
@deftypefn {Built-in Function} string strftime (string @var{fmt}, @
number @var{timestamp})
@deftypefnx {Built-in Function} string strftime (string @var{fmt}, @
@@ -9286,11 +9320,11 @@ compilation error.
@UNREVISED{}
Before compiling the script file, @command{mailfromd} preprocesses
it. The built-in preprocessor handles only file inclusion
-(@pxref{include}), the rest of traditional facililities, such as
+(@pxref{include}), while the rest of traditional facililities, such as
macro expansion, are supported via @command{m4}, which is used as an
external preprocessor.
- The detailed description of @command{m4} facilities is far beyond
+ The detailed description of @command{m4} facilities lies far beyond
the scope of this document. You will find a complete user manual in
@ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}.
@@ -9357,7 +9391,7 @@ string to the current log output (@pxref{Logging and Debugging}).
Example usage:
@smallexample
-printf("Function `%s' returned %d", %funcname, %retcode)
+printf('Function `%s' returned %d', %funcname, %retcode)
@end smallexample
@end deffn

Return to:

Send suggestions and report system problems to the System administrator.