diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2007-05-24 14:51:36 +0000 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2007-05-24 14:51:36 +0000 |
commit | 15a613d5247b1e2f739f100ed73c7c95753d9848 (patch) | |
tree | 15428f32eeed4df4f9d1c74b677bc37907cecf3c | |
parent | feaa5acf2f418c8eb4d836ce897f86e44ac2b19d (diff) | |
download | mailfromd-15a613d5247b1e2f739f100ed73c7c95753d9848.tar.gz mailfromd-15a613d5247b1e2f739f100ed73c7c95753d9848.tar.bz2 |
Improve docs
git-svn-id: file:///svnroot/mailfromd/trunk@1471 7a8a7f39-df28-0410-adc6-e0d955640f24
-rw-r--r-- | NEWS | 31 | ||||
-rw-r--r-- | doc/Makefile.am | 3 | ||||
-rw-r--r-- | doc/mailfromd.texi | 444 | ||||
-rw-r--r-- | src/main.c | 11 |
4 files changed, 444 insertions, 45 deletions
@@ -1,4 +1,4 @@ -Mailfromd NEWS -- history of user-visible changes. 2007-05-22 +Mailfromd NEWS -- history of user-visible changes. 2007-05-24 Copyright (C) 2005, 2006, 2007 Sergey Poznyakoff See the end of file for copying conditions. @@ -7,8 +7,17 @@ Please send mailfromd bug reports to <bug-mailfromd@gnu.org.ua> Version 4.0.90 -* Added National Language Support. Polish and Ukrainian translations - available. +* National Language Support. + +The program include National Language Support. Polish and Ukrainian +translations are available. + +* NLS Functions + +NLS functions allow to localize your filter scripts for a particular +language. The following functions are implemented: bindtextdomain, +dgettext, dngettext, textdomain, gettext, ngettext. In addition, +macros _() and N_() are also provided. * Input files are preprocessed before compilation. Default preprocessor is M4, but this can be changed (or disabled) at configuration time (see @@ -40,13 +49,21 @@ do /* `n' is passed */ ... -* The support for `&code' form to specify an exception code is discontinued. +* sprintf + +The built-in function `sprintf' is available with the same semantics +as its C counterpart. + +* Discontinued support for deprecated feature: + +** `&code' form to specify an exception code is discontinued. +** pragma options retry, io-retry, and connect-retry * Bugfixes: ** Built-in listen ignored optional second argument. -** Debug specification incorrectly gave preverence to global level over the - source level. This is fixed, so that `--debug=40,dns=10' means - level 10 for calls from `dns.c', and level 40 for all the rest. +** Debug specification incorrectly gave preverence to the global level + over the source level. This is fixed, so that `--debug=40,dns=10' + means level 10 for calls from `dns.c', and level 40 for all the rest. Version 4.0, 2007-05-12 diff --git a/doc/Makefile.am b/doc/Makefile.am index cd62e11a..994f3404 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -60,7 +60,8 @@ check-options: check-builtins: @check-docs.sh builtins \ - '/MF_DEFUN/s/[ \t]*MF_DEFUN *(\([^,][^,]*\),.*/\1/p' \ + '/MF_DEFUN/{s/[ \t]*MF_DEFUN *(\([^,][^,]*\),.*/\1/p;\ + s/[ \t]*MF_DEFUN_VARARGS *(\([^,][^,]*\),.*/\1/p}' \ 's/@deftypefn {Built-in Function} *[^ ][^ ]* *\([^ ]*\).*/\1/p' \ $(top_srcdir)/src/bi_*.m4 -- \ $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi index 0aef9c5b..22cc5d98 100644 --- a/doc/mailfromd.texi +++ b/doc/mailfromd.texi @@ -184,7 +184,7 @@ Mail Filtering Language * Exceptions:: Exceptional Conditions and their Handling. * Polling:: Sender Verification Tests. * Modules:: Modules are Collections of Useful Functions. -* Preprocessor:: Input Text Can Be Preprocessed. +* Preprocessor:: Input Text Is Preprocessed. * Filter Script Example:: A Working Filter Script Explained. * Reserved Words:: A Reference List of Reserved Words. @@ -210,7 +210,8 @@ Functions Built-in and Library Functions -* String manipulation:: +* String manipulation:: +* String formatting:: * Mail header functions:: * Polling functions:: * Internet address manipulation functions:: @@ -221,6 +222,7 @@ Built-in and Library Functions * Interfaces to Third-Party Programs:: * Special test functions:: * Mail Sending Functions:: +* NLS Functions:: * Debugging Functions:: * Blacklisting Functions:: * SPF Functions:: @@ -977,6 +979,32 @@ the corresponding section below. @cindex Upgrading from 4.0 to 4.1 @UNREVISED{} + Upgrading to this version does not require any special efforts. You +can use your configuration files and filter scripts without any changes. +Notice only the following major differences between 4.1 and 4.0: + +@itemize @bullet +@item Input files are preprocessed before compilation. +@xref{Preprocessor}, for the description. + +@item There is a way to discern between a not-supplied optional +parameter, and a supplied one, having null value (@pxref{defined}). + +@item The version 4.1 implements @code{sprintf} function +(@pxref{String formatting}) and @code{printf} macro +(@pxref{Preprocessor, printf}). + +@item Support for some obsolete features is withdrawn. These include: + +@enumerate 1 +@item +Using @samp{&@var{code}} to specify exception codes +@item +Pragma options: @code{retry}, @code{io-retry}, and +@code{connect-retry}. +@end enumerate +@end itemize + @node 31x-400 @section Upgrading from 3.1.x to 4.0 @cindex upgrading from 3.1.x to 4.0 @@ -3281,7 +3309,7 @@ amount of white-space characters (i.e. spaces, tabulations or newlines). * Exceptions:: Exceptional Conditions and their Handling. * Polling:: Sender Verification Tests. * Modules:: Modules are Collections of Useful Functions. -* Preprocessor:: Input Text Can Be Preprocessed. +* Preprocessor:: Input Text Is Preprocessed. * Filter Script Example:: A Working Filter Script Explained. * Reserved Words:: A Reference List of Reserved Words. @end menu @@ -3407,6 +3435,22 @@ statement is similar to @code{#include_once}. You will find more information regarding @acronym{MFL} modules in @xref{Modules}. +@anchor{line} +@cindex line, @code{#line} statement +@kwindex #line + + A line in the form + +@smallexample +#line @var{number} "@var{identifier}" +@end smallexample + +@noindent +causes the @acronym{MFL} compiler to believe, for purposes of error +diagnostics, that the line number of the next source line is given by +@var{number} and the current input file is named by @var{identifier}. +If the identifier is absent, the remembered file name does not change. + @anchor{Pragmatic comments} @cindex pragmatic comments @cindex #pragma statement @@ -3559,25 +3603,7 @@ considered deprecated. @ignore ------------------------------------------------------------------------ - -- This is to pacify make check-docs. These options are no longer - -- used but retained for backward compatibility. -@deffn {pragma option} io-retry @var{number} -@deffnx {pragma option} retry @var{number} -@xprindex{io-retry} -@xprindex{retry} - Sets number of retries for each I/O operation. Default is 3. -@xref{pragma io-timeout}, for the description of its effect. - - The form @code{retry} is retained for backward compatibility and is -considered deprecated. -@end deffn - -@deffn {pragma option} connect-retry @var{number} -@xprindex{connect-retry} - Sets number of attempts to establish initial connection. Default is -1 attempt. -@end deffn - + -- This is to pacify make check-docs. -- These options are reserved for future use @opindex load @@ -4304,6 +4330,18 @@ For alpha versions and maintenance releases expands to the version patch level. For stable versions, expands to @samp{0}. @end deftypevr +@deftypevr {Built-in constant} string __preproc__ + Expands to the external preprocessor command line, if the +preprocessor is used, or to an empty string if it cannot, e.g.: + +@smallexample +__preproc__ @result{} "/usr/bin/m4 -s" +@end smallexample + + @xref{Preprocessor}, for the information on preprocessor and its +features. +@end deftypevr + The following example uses @code{__major__} constant to determine if some version-dependent feature can be used: @@ -4315,7 +4353,7 @@ fi @end group @end smallexample - Built-in macros can be used as variables, this allows to expand them + Built-in constants can be used as variables, this allows to expand them within strings or here-documents. The following example illustrates the common practice used for debugging configuration scripts: @@ -5088,7 +5126,8 @@ functions}. in version @value{VERSION}. @menu -* String manipulation:: +* String manipulation:: +* String formatting:: * Mail header functions:: * Polling functions:: * Internet address manipulation functions:: @@ -5099,6 +5138,7 @@ in version @value{VERSION}. * Interfaces to Third-Party Programs:: * Special test functions:: * Mail Sending Functions:: +* NLS Functions:: * Debugging Functions:: * Blacklisting Functions:: * SPF Functions:: @@ -5294,6 +5334,153 @@ Example: @code{revip("127.0.0.1") @result{} "1.0.0.127"} @end deftypefn +@node String formatting +@subsubsection String formatting + +@deftypefn {Built-in Function} string sprintf (string @var{format}, @dots{}) +The function @code{sprintf} formats its argument according to +@var{format} (see below) and returns the resulting string. It takes +varying number of parameters, the only mandatory one being +@var{format}. +@end deftypefn + +@subsubheading Format of the format string +The format string is a simplified version of the format argument to +@acronym{C} @code{printf}-family functions. + +The format string is composed of zero or more @dfn{directives}: ordinary +characters (not @samp{%}), which are copied unchanged to the +output stream; and @dfn{conversion specifications}, each of +which results in fetching zero or more subsequent arguments. +Each conversion specification is introduced by the +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}. + +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, + +@smallexample + sprintf('%*d', %width, %num); +@end smallexample +@noindent +and +@smallexample + sprintf('%2$*1$d', width, num); +@end smallexample +@noindent +are equivalent. The second style allows repeated references to the +same argument. + +@subsubheading The flag characters +The character @samp{%} is followed by zero or more of the following +@dfn{flags}: + +@table @samp +@item # +The value should be converted to an @dfn{alternate form}. For +@samp{o} conversions, the first character of the output string is made +zero (by prefixing a @samp{0} if it was not zero already). For +@samp{x} and @samp{X} conversions, a non-zero result has the string +@samp{0x} (or @samp{0X} for @samp{X} conversions) prepended to it. +Other conversions are not affected by this flag. + +@item 0 +The value should be zero padded. For @samp{d}, @samp{i}, @samp{o}, @samp{u}, +@samp{x}, and @samp{X} conversions, the converted value is padded on +the left with zeros rather than blanks. If the @samp{0} and @samp{-} +flags both appear, the @samp{0} flag is ignored. If a precision is given, +the @samp{0} flag is ignored. +Other conversions are not affected by this flag. + +@item - +The converted value is to be left adjusted on the field boundary. +(The default is right justification.) The converted value is padded +on the right with blanks, rather than on the left with blanks or +zeros. A @samp{-} overrides a @samp{0} if both are given. + +@item ' ' (a space) +A blank should be left before a positive number (or empty string) +produced by a signed conversion. + +@item + +A sign (@samp{+} or @samp{-}) always be placed before a number +produced by a signed conversion. By default a sign is used only for +negative numbers. A @samp{+} overrides a space if both are used. +@end table + +@subsubheading The field width +An optional decimal digit string (with nonzero first digit) specifying +a minimum field width. If the converted value has fewer characters +than the field width, it will be padded with spaces on the left (or +right, if the left-adjustment flag has been given). Instead of a +decimal digit string one may write @samp{*} or @samp{*@var{m}$} (for +some decimal integer @var{m}) to specify that the field width is given +in the next argument, or in the @var{m}-th argument, respectively, +which must be of numeric type. A negative field width is taken as a +@samp{-} flag followed by a positive field width. In no case does a +non-existent or small field width cause truncation of a field; if the +result of a conversion is wider than the field width, the field is +expanded to contain the conversion result. + +@subsubheading The precision +An optional precision, in the form of a period (@samp{.}) followed by +an optional decimal digit string. Instead of a decimal digit string +one may write @samp{*} or @samp{*@var{m}$} (for some decimal integer +@var{m}) to specify that the precision is given in the next argument, +or in the @var{m}-th argument, respectively, which must be of numeric +type. If the precision is given as just @samp{.}, or the precision is +negative, the precision is taken to be zero. This gives the minimum number +of digits to appear for @samp{d}, @samp{i}, @samp{o}, @samp{u}, +@samp{x}, and @samp{X} conversions, or the maximum number of +characters to be printed from a string for the @samp{s} conversion. + +@subsubheading The conversion specifier +A character that specifies the type of conversion to be applied. The +conversion specifiers and their meanings are: + +@table @asis +@item d +@itemx i +The numeric argument is converted to signed decimal notation. The +precision, if any, gives the minimum number of digits that must +appear; if the converted value requires fewer digits, it is padded on +the left with zeros. The default precision is @samp{1}. When @samp{0} is printed with an explicit precision @samp{0}, the output is empty. + +@item o +@itemx u +@itemx x +@itemx X +The numeric argument is converted to unsigned octal (@samp{o}), +unsigned decimal (@samp{u}), or unsigned hexadecimal (@samp{x} and +@samp{X}) notation. The letters @samp{abcdef} are used for @samp{x} +conversions; the letters @samp{ABCDEF} are used for @samp{X} +conversions. The precision, if any, gives the minimum number of +digits that must appear; if the converted value requires fewer +digits, it is padded on the left with zeros. The default precision is +@samp{1}. When @samp{0} is printed with an explicit precision 0, the +output is empty. + +@item s +The string argument is written to the output. If a precision is +specified, no more than the number specified of characters are +written. + +@item % +A @samp{%} is written. No argument is converted. The complete +conversion specification is @samp{%%}. +@end table + + @node Mail header functions @subsubsection Mail Header Functions @@ -7056,7 +7243,11 @@ of the @acronym{SPF} functions. By default is is Set by @code{check_host} function to @samp{1} if the function made the decision based on the cached data, or to @samp{0} otherwise. @end deftypevar - + +@node NLS Functions +@subsubsection National Language Support Functions +@UNREVISED{} + @node Debugging Functions @subsubsection Debugging Functions @@ -7221,6 +7412,67 @@ using the syntax for variable references: @code{%@var{name}}. The value of a parameter can be altered using @code{set} statement, the same way as for variables. +@cindex optional arguments to a function +@cindex arguments, optional + A function can be declared to take a certain number of @dfn{optional +arguments}. In function declaration, optional abstract arguments +must be placed after the mandatory ones, and must be separated from +them with a semicolon. The following example is a definition of +function @code{foo}, which takes two mandatory and two optional +arguments: + +@smallexample +func foo(string msg, string email; number x, string pfx) +@end smallexample + +@noindent +@cindex $#, special construct +@cindex function arguments, getting the number of +@cindex function arguments, counting +@cindex number of actual arguments +@cindex @@@var{var}, special construct +@cindex argument number in the list of arguments +Mandatory arguments are: @code{msg} and @code{email}. Optional +arguments are: @code{x} and @code{pfx}. The actual number of +parameters supplied to the function is returned by a special construct +@code{$#}. In addition, the special construct @code{@@@var{arg}} +evaluates to the ordinal number of variable @var{arg} in the list of +formal parameters (the first argument has number @samp{0}). These two +constructs can be used to verify whether an argument is supplied to +the function. + +@cindex optional arguments, checking if supplied + The actual parameter for argument @code{n} is supplied if the number +of actual parameters (@code{$#}) is greater than its ordinal number +in the declaration list (@code{@@@var{n}}). This, to check if +@var{pfx} is given: + +@smallexample +func foo(string msg, string email; number x, string pfx) +do + if $# > @@pfx + @dots{} + fi +@end smallexample + + The default @command{mailfromd} installation provides a special +macro for this purpose: @pxref{defined}. Using it, the example above +will be rewritten as: + +@smallexample +func foo(string msg, string email; number x, string pfx) +do + if defined(pfx) + @dots{} + fi +@end smallexample + + Within a function body, optional arguments are referenced +exactly the same way as the mandatory ones. Attempt to dereference an +optional argument for which no actual aparameter was supplied, results +in an undefined value, so be sure to chech whether a parameter is +passed before dereferencing it. + @cindex return statement, defined The @var{function-body} is any list of valid @command{mailfromd} statements. In addition to the statements discussed below @@ -8952,13 +9204,138 @@ available to your filter program, use the following statement: The @code{#require} statement looks up the module @file{@var{modname}.mf} in the include path and attempts to compile it (@pxref{require}). It is not an error to require the same module -several times. However, requiring a not existing module results in +several times. However, requiring a non-existing module results in compilation error. @node Preprocessor @section @acronym{MFL} Preprocessor @cindex preprocessor @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 +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 scope of this document. You will find a complete user manual in +@ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}. + + The rest of this section assumes the reader is sufficiently +acquainted with @command{m4} macro processor. + +@flindex pp-setup + The preprocessor is invoked with @option{-s} flag, instructing +it to include line synchornizattion information in its output, which +is subsequently used by @acronym{MFL} compiler for purposes of error +reporting. The initial set of macro definitions is supplied in file +@file{pp-setup}, located in the library search path@footnote{It is +usually located in +@file{/usr/local/share/mailfromd/@value{VERSION}/include/pp-setup}.}, +which is fed to the preprocessor input before the script file itself. +The default @file{pp-setup} file renames all @command{m4} builtin +macro names so they all start with the prefix @samp{m4_}@footnote{This +is similar to GNU m4 @option{--prefix-builtin} options. This approach +was chosen to allow for using non-GNU m4's as well.}. It changes +comment characters to @samp{/*}, @samp{*/} pair, and leaves the +default quoting characters, grave (@samp{`}) and acute (@samp{'}) +accents without change. Finally, @file{pp-setup} defines the +following macros: + +@anchor{defined} +@deftypefn {M4 Macro} boolean defined (@var{identifier}) +The @var{identifier} must be the name of an optional abstract +argument to the function. This macro must be used only within a function +definition. It expands to the @acronym{MFL} expression that yields +@code{true} if the actual parameter is supplied for @var{identifier}. +For example: + +@smallexample +func rcut(string text; number num) +do + if (defined(num)) + return substr(%text, length(%text) - %num) + else + return %text + fi +done +@end smallexample + + This function will return last @var{num} characters of @var{text} if +@var{num} is supplied, and entire @var{text} otherwise, e.g.: + +@smallexample +@group +rcut("text string") @result{} "text string" +rcut("text string", 3) @result{} "ing" +@end group +@end smallexample + + Invoking the @code{defined} macro with the name of a mandatory argument +yields @code{true} +@end deftypefn + +@deffn {M4 Macro} printf (@var{format}, @dots{}) + Provides a @code{printf} statement, that formats its optional +parameters in accordance with @var{format} and sends the resulting +string to the current log output (@pxref{Logging and Debugging}). +@xref{String formatting}, for the description of @var{format}. + + Example usage: + +@smallexample +printf("Function `%s' returned %d", %funcname, %retcode) +@end smallexample +@end deffn + +@deftypefn {M4 Macro} string _ (@var{msgid}) +A convenience macro. Expands to a call to @code{gettext} (@pxref{NLS +Functions}). +@end deftypefn + +@deffn {M4 Macro} N_ (@var{msgid}) +A convenience macro, that expands to @var{msgid} verbatim. It is +intended to be used as a marker for literal strings that should appear +in the @file{.po} file, if actual call to @code{gettext} cannot +be used. For example: + +@smallexample +/* Mark the variable for translation: cannot use gettext here */ +string message N_("Mail accepted") + +prog envfrom +do + @dots{} + /* Translate and log the message */ + echo gettext(%message) +@end smallexample +@end deffn + +@cindex E, -E @r{option, described} + You can obtain the preprocessed output, without starting actual +compilation, using @option{-E} command line option: + +@smallexample +$ @kbd{mailfromf -E file.mf} +@end smallexample + +The output is in the form of preprocessed source code, which is sent +to the standard output. This can be useful, among others, to debug +your own macro definitions. + +The following two options are supplied mainly for debugging purposes: + +@table @option +@xopindex{no-preprocessor, usage} +@item --no-preprocessor +Disables the external preprocessor. + +@xopindex{preprocessor, usage} +@item --preprocessor=@var{command} +Use @var{command} as external preprocessor. Be especially careful +with this option, because @command{mailfromd} cannot verify whether +@var{command} is actually some kind of a preprocessor or not. +@end table @node Filter Script Example @section Example of a Filter Script File @@ -9432,6 +9809,10 @@ mailfrom_address=@var{string}} instead. @item --mtasim This option is reserved for use by @command{mtasim} (@pxref{mtasim}). +@opsummary{no-preprocessor} +@item --no-preprocessor +Do not run the preprocessor. @xref{Preprocessor}. + @opsummary{optimize} @item -O[@var{level}] @itemx --optimize[=@var{level}] @@ -9460,6 +9841,11 @@ Used with @option{--list} enables printing of the estimated times of sending along with the @samp{rate} database dump. Implies @option{--list --format=rate}. @xref{estimated time of sending}. +@opsummary{preprocessor} +@item --preprocessor=@var{command} +Use @var{command} as the external preprocessor instead of the default +@command{m4}. @xref{Preprocessor}. + @opsummary{relayed-domain-file} @item --relayed-domain-file=@var{file} @anchor{option relay} @@ -9583,6 +9969,12 @@ printable form to the terminal. Print a cross-reference of variables used in the filter script. @xref{Testing Filter Scripts}. +@cindex E, -E @r{option, summary} +@item -E +Stop after the preprocessing stage; do not run the compiler proper. +The output is in the form of preprocessed source code, which is sent +to the standard output. @xref{Preprocessor}. + @opsummary{lint} @item --lint Check script file syntax and exit. If the file is @sc{ok}, return 0 @@ -338,14 +338,6 @@ host_in_relayed_domain_p(char *client) static int option_string(char *opt, void **pval, char *newval); -/* Deprecated options: */ -static int -option_deprecated(char *opt, void **pval, char *newval) -{ - parse_warning("deprecated option %s ignored", opt); - return 0; -} - static int option_ehlo(char *opt, void **pval, char *newval) { @@ -745,11 +737,8 @@ struct option_cache { { "milter-timeout", NULL, option_time, set_milter_timeout }, { "pidfile", NULL, option_pidfile, set_pidfile }, { "mailfrom", NULL, option_mailfrom, set_mailfrom }, - { "retry", NULL, option_deprecated, NULL }, { "timeout", NULL, option_time, set_io_timeout }, - { "io-retry", NULL, option_deprecated, NULL }, { "io-timeout", NULL, option_time, set_io_timeout }, - { "connect-retry", NULL, option_deprecated, NULL }, { "connect-timeout", NULL, option_time, set_connect_timeout }, { "initial-response-timeout", NULL, option_time, set_response_timeout }, |