diff options
| -rw-r--r-- | doc/mailfromd.texi | 98 |
1 files changed, 49 insertions, 49 deletions
diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi index 8d72ec45..1043082f 100644 --- a/doc/mailfromd.texi +++ b/doc/mailfromd.texi @@ -983,13 +983,13 @@ the corresponding section below. 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. +@xref{Preprocessor}, for more information. @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 @@ -1050,18 +1050,18 @@ warning: `#pragma option ehlo' is deprecated, steps: @enumerate 1 @item Change @code{#pragma option mailfrom @var{value}} to @code{set mailfrom_address @var{value}}. Refer to -@ref{mailfrom_address}, for the detailed discussion of this variable. +@ref{mailfrom_address}, for a detailed discussion of this variable. @item Change @code{#pragma option ehlo @var{value}} to @code{set ehlo_domain @var{value}}. Refer to -@ref{ehlo_domain}, for the detailed discussion of this variable. +@ref{ehlo_domain}, for a detailed discussion of this variable. @item Include @file{status.mfh}. Add the following line to the top of your startup file: @smallexample @@ -1078,26 +1078,26 @@ use the following @command{sed} expression: @samp{s/&\([a-z]\)/\1/g}. to the top of your script: @smallexample #require dns @end smallexample -@xref{Modules}, for the detailed description of the module system. +@xref{Modules}, for a detailed description of the module system. @item Replace all occurrences of @code{next} with @code{pass}. @item If your code uses function @code{match_cidr}, add the following line to the top of your script: @smallexample #require match_cidr @end smallexample -@xref{Modules}, for the description of @acronym{MFL} module system. +@xref{Modules}, for a description of @acronym{MFL} module system. @end enumerate @node 30x-31x @section Upgrading from 3.0.x to 3.1 @cindex upgrading from 3.0.x to 3.1 @@ -1603,13 +1603,13 @@ hostname($client_addr) hostname $client_addr @end smallexample @noindent However, such syntax creates several ambiguities, so use it sparingly if at all. We recommend to always use parentheses when calling a -function; @xref{Cautions}, for the detailed analysis of of this syntax. +function; @xref{Cautions}, for a detailed analysis of of this syntax. When a function does not deliver a result, it should only be called as a statement. Functions may be recursive, even mutually recursive. @@ -1792,13 +1792,13 @@ the remote host. @item I/O timeout Maximum amount of time for finishing an input/output operation with the remote @acronym{SMTP} server. @end table These three timeouts can be set using the following @dfn{pragmatic -comments}@footnote{@xref{Pragmatic comments}, for the detailed +comments}@footnote{@xref{Pragmatic comments}, for a detailed description of pragmatic comments.} in the script file: @smallexample @group #pragma option connect-timeout @var{interval} #pragma option initial-response-timeout @var{interval} @@ -1980,13 +1980,13 @@ where @var{expr} is any valid @acronym{MFL} expression. declarations as well as outside of them. There are two kinds of @command{Mailfromd} variables: @dfn{global variables}, that are visible to all handlers and functions, and @dfn{automatic variables}, that are available only within the handler or function where they are declared. For our purpose we need a global -variable (@xref{Variables, Variable classes}, for the detailed description +variable (@xref{Variables, Variable classes}, for detailed descriptions of both kinds of variables). The following example illustrates the approach that allows to use the @code{HELO} domain name in any handler: @smallexample @@ -2283,13 +2283,13 @@ to the reader. @anchor{whitelisting} @cindex whitelisting One special case is @dfn{whitelisting}, which is often used together with greylisting. To implement it, @command{mailfromd} provides the function @code{dbmap}, which takes two mandatory arguments: @code{dbmap(@var{file}, @var{key})} (it also allows an optional third -argument, see @ref{dbmap}, for the description of it). The first argument is +argument, see @ref{dbmap}, for more information on it). The first argument is the name of the @acronym{DBM} file where to search for the key, the second one is the key to be searched. Assuming you keep your whitelist database in file @file{/var/run/whitelist.db}, a more practical example will be: @smallexample @group @@ -2870,13 +2870,13 @@ administrator is to make sure it is available by configuring @code{Sendmail} to export the macro @samp{i} to @command{mailfromd}. The rule of thumb is: make @samp{i} available to the very first handler @command{mailfromd} executes. It is not necessary to export it to the rest of the handlers, since @command{mailfromd} will cache it. For example, if your filter script contains @samp{envfrom} and @samp{envrcpt} handlers, export @samp{i} for @samp{envfrom}. -@xref{Sendmail Configuration}, for the instructions on how to ensure +@xref{Sendmail Configuration}, for instructions on how to ensure it. @xopindex{debug, introduced} @cindex debugging level @cindex verbosity level To push the log verbosity further, use @code{#pragma option debug} @@ -3039,13 +3039,13 @@ regular expression. For example: @end table @anchor{uncaught exceptions} @subheading Uncaught exceptions Another kind of runtime errors are @dfn{uncaught exceptions}, i.e. exceptional conditions for which no handler was installed -(@xref{Exceptions}, for the information on exceptions and on how to +(@xref{Exceptions}, for information on exceptions and on how to handle them). These errors mean that the programmer (i.e. you), made no provision for some specific conditions. For example, consider the following code: @smallexample @group @@ -3604,13 +3604,13 @@ The following options control @acronym{I/O} operations over @acronym{TCP}. @deffn {pragma option} connect-timeout @var{interval} @xprindex{connect-timeout} Sets initial connection timeout. If the connection is not established within this time, the corresponding probing function returns temporary failure. The default value is -@value{CONNECT-TIMEOUT}. @xref{SMTP Timeouts}, for the +@value{CONNECT-TIMEOUT}. @xref{SMTP Timeouts}, for a detailed description. @end deffn @deffn {pragma option} initial-response-timeout @var{interval} @xprindex{initial-response-timeout} Sets the time to wait for the initial @acronym{SMTP} response. Default is @@ -3622,13 +3622,13 @@ the detailed description. @deffnx {pragma option} timeout @var{interval} @xprindex{io-timeout} @xprindex{timeout} Sets @acronym{I/O} operation timeout in seconds. @command{Mailfromd} will wait the given amount of time for the success of each @acronym{I/O} operation with the remote @acronym{MX}. Default timeout is @value{IO-TIMEOUT}. -@xref{SMTP Timeouts}, for the detailed description. +@xref{SMTP Timeouts}, for a detailed description. The form @code{timeout} is retained for backward compatibility and is considered deprecated. @end deffn @ignore @@ -3703,22 +3703,22 @@ debugging @command{mailfromd}. @end deffn @deffn {pragma option} stack-trace @var{boolean} @xprindex{stack-trace} Enables dumping stack traces on runtime errors. This feature is useful for locating the source of an error, especially in complex -scripts. @xref{tracing runtime errors}, for the detailed description. +scripts. @xref{tracing runtime errors}, for a detailed description. @end deffn @noindent These options control program privileges after startup: @deffn {pragma option} user @var{string} @xprindex{user} Switch to this user's privileges after startup. -@xref{Starting and Stopping}, for the discussion of +@xref{Starting and Stopping}, for a discussion of the privileges @command{mailfromd} runs under and the options that affect them. See also @code{group} below. @end deffn @deffn {pragma option} group @var{string} @xprindex{group} @@ -3821,13 +3821,14 @@ syntax is: @table @code @item #pragma database @var{dbname} file @var{filename} Set the database file name for the database @var{dbname}. @item #pragma database @var{dbname} expire-interval @var{interval} Set the expiration interval for the database -@var{dbname}. (@xref{time interval specification}, for the syntax of @var{interval}). +@var{dbname}. (@xref{time interval specification}, for more +information on @var{interval} syntax). @end table The parameter @var{dbname} can be one of the following: @samp{cache}, @samp{dns}, @samp{rate} and @samp{greylist} for main cache, @acronym{DNS} lookup, sending rate and greylisting databases, correspondingly. @@ -4096,13 +4097,13 @@ split at compilation time into a series of concatenated atoms. Thus, our sample string will actually be compiled as: @smallexample $f " last connected from " %last_ip ";" @end smallexample -@xref{Concatenation}, for the description of this construct. You can +@xref{Concatenation}, for a description of this construct. You can easily see how various strings are interpreted by using @option{--dump-tree} option (@pxref{--dump-tree}). For our sample string it will produce: @smallexample CONCAT: @@ -4130,13 +4131,13 @@ will be expanded to A @dfn{back reference} is a sequence @samp{\@var{d}}, where @var{d} is a decimal number. It refers to the @var{d}th parenthesized subexpression in the last @command{matches} statement@footnote{The subexpressions are numbered by the positions of their opening parentheses, left to right.}. Any back reference occurring within a double-quoted string is replaced by the value of the corresponding -subexpression. @xref{Special comparisons}, for the detailed +subexpression. @xref{Special comparisons}, for a detailed description of this process. Back reference interpretation is performed at run time. @anchor{singe-vs-double} @subheading Single-quoted strings @@ -4372,13 +4373,13 @@ patch level. For stable versions, expands to @samp{0}. 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 + @xref{Preprocessor}, for information on preprocessor and its features. @end deftypevr @deftypevr {Built-in constant} string __version__ Expands to the textual representation of the program version (e.g. @samp{3.0.90}) @@ -6097,14 +6098,14 @@ A mx10.gnu.org: Sun Dec 3 10:56:12 2006 199.232.76.166 @end smallexample The above example shows that the @acronym{IP} address of @samp{mx10.gnu.org} and that it expires on Sunday, December 3d, at 10:56:12. Of course, the rest of database management options are also valid -for @acronym{DNS} database. @xref{Database Maintenance}, for the detailed -discussion of these. +for @acronym{DNS} database. @xref{Database Maintenance}, for more +information on these. @node Database functions @subsubsection Database Functions @anchor{dbmap} @deftypefn {Built-in Function} boolean dbmap (string @var{db}, @ @@ -6147,13 +6148,13 @@ database error occurs while attempting to retrieve the record, @smallexample #require safedb @end smallexample @noindent -@xref{Modules}, for the description of @acronym{MFL} module system. +@xref{Modules}, for a description of @acronym{MFL} module system. @end deftypefn @deftypefn {Built-in Function} void dbput (string @var{db}, @ string @var{key}, string @var{value} [, number @var{null}]) Inserts in the database a record with the given @var{key} and @var{value}. If a record with the given @var{key} already exists, its @@ -6174,13 +6175,13 @@ the function returns without reporting an error. @smallexample #require safedb @end smallexample @noindent -@xref{Modules}, for the description of @acronym{MFL} module system. +@xref{Modules}, for a description of @acronym{MFL} module system. @end deftypefn @deftypefn {Built-in Function} void dbdel (string @var{db}, @ string @var{key}) @deftypefnx {Built-in Function} void dbdel (string @var{db}, @ string @var{key}, number @var{null}) @@ -6361,16 +6362,16 @@ measured in seconds. @deftypefnx {Built-in Function} string strftime (string @var{fmt}, @ number @var{timestamp}, boolean @var{gmt}) Formats the time @var{timestamp} (seconds since the Epoch) according to the format specification @var{format}. Ordinary characters placed in the format string are copied to the output without conversion. Conversion specifiers are introduced by a @samp{%} character. -@xref{Time and Date Formats}, for the detailed description of the +@xref{Time and Date Formats}, for a detailed description of the conversion specifiers. We recommend using single quotes around @var{fmt} to prevent @samp{%} specifiers from being interpreted -as @code{Mailfromd} variables (@xref{Literals}, for the +as @code{Mailfromd} variables (@xref{Literals}, for a discussion of quoted literals and variable interpretation within them). The @var{timestamp} argument can be a return value of @code{time} function (see above). @@ -6564,13 +6565,13 @@ done @cindex greylist_seconds_left, global variable Returns true if the @var{key} is found in the greylist database (controlled by @code{#pragma database greylist} pragma, @pxref{database}). The argument @var{interval} gives the greylisting interval in seconds. The function stores the number of seconds left to the end of greylisting period in the internal variable -@code{greylist_seconds_left}. @xref{Greylisting}, for the detailed +@code{greylist_seconds_left}. @xref{Greylisting}, for a detailed explanation. The function @code{greylist} can signal @code{dbfailure} exception. @end deftypefn @deftypefn {Built-in Function} boolean listens (string @var{host}, [number @var{port}]) @@ -6580,13 +6581,13 @@ explanation. @anchor{rate} @deftypefn {Built-in Function} number rate (string @var{key}, @ number @var{sample-interval}) Returns the mail sending rate for @var{key} per -@var{sample-interval}. @xref{Sending Rate}, for the detailed +@var{sample-interval}. @xref{Sending Rate}, for a detailed discussion. @end deftypefn @deftypefn {Built-in Function} boolean validuser (string @var{name}) Returns @code{true} if authenticity of the user @var{name} is confirmed using mailutils authentication system. @xref{Local Account @@ -7211,16 +7212,15 @@ Normally it is the domain portion of the @code{MAIL FROM} or @item helo The @code{HELO} identity. @end table Before returning, the @code{check_host} function stores additional information in the same global variables, as -@code{spf_check_host}. @xref{spf-globals, the list}, for the -description of these. In addition, it sets the variable -@code{spf_cached} to @samp{1} if cached data were used, or to @samp{0} -otherwise. +@code{spf_check_host}. @xref{spf-globals, the list}, for details. +In addition, it sets the variable @code{spf_cached} to @samp{1} if +cached data were used, or to @samp{0} otherwise. @end deftypefn @deftypefn {Library Function} string spf_status_string (number @var{code}) Converts numeric @acronym{SPF} result @var{code} to its string representation. @end deftypefn @@ -7397,13 +7397,13 @@ The @code{dngettext} functions attempts to translate a text string into the language specified by the current locale, by looking up the appropriate singular or plural form of the translation in a message catalog, set for the textual domain @var{domain}. @xref{Plural forms, Additional functions for plural forms, Additional functions for plural forms, gettext, GNU gettext -utilities}, for the detailed discussion of the plural form handling in +utilities}, for a discussion of the plural form handling in different languages. @end deftypefn @deftypefn {Library Function} string textdomain (string @var{domain}) The @code{textdomain} function sets the current message domain to @var{domain}, if it is not empty. In any case the function returns @@ -7432,25 +7432,25 @@ The @code{ngettext} functions attempts to translate a text string into the language specified by the current locale, by looking up the appropriate singular or plural form of the translation in a message catalog, set for the current textual domain. @xref{Plural forms, Additional functions for plural forms, Additional functions for plural forms, gettext, GNU gettext -utilities}, for the detailed discussion of the plural form handling in +utilities}, for a discussion of the plural form handling in different languages. @end deftypefn @node Debugging Functions @subsubsection Debugging Functions These functions allow to enable debugging and tracing for a certain piece of code. @deftypefn {Built-in Function} void debug (string @var{spec}) Enable debugging. The value of @var{spec} sets the debugging level. -@xref{debugging level specification}, for the description of its format. +@xref{debugging level specification}, for a description of its format. @end deftypefn @deftypefn {Built-in Function} number debug_level ([string @var{srcname}]) This function returns the debugging level currently in effect for the source module @var{srcname}, or the global debugging level, if called without arguments. @@ -7533,13 +7533,13 @@ simultaneously: debug("%dspec") @end group @end smallexample @deftypefn {Built-in Function} void program_trace (string @var{module}) Enable tracing for a set of modules given in @var{module} argument. -@xref{--trace-program}, for the description of its format. +@xref{--trace-program}, for a description of its format. @end deftypefn @deftypefn {Built-in Function} void cancel_program_trace (string @var{module}) Disable tracing for given modules. @end deftypefn @@ -7856,13 +7856,13 @@ done @end group @end smallexample @cindex valid_domain, definition @item @code{valid_domain}@* -@xref{valid_domain}, for the description of this function. Its +@xref{valid_domain}, for a description of this function. Its definition follows: @smallexample @group #require dns @@ -8106,13 +8106,13 @@ fi Remember that the grouping symbols are @samp{\(} and @samp{\)} for basic regular expressions, and @samp{(} and @samp{)} for extended regular expressions. Also make sure you properly escape all special characters (backslashes in particular) in double-quoted strings, or use single-quoted strings to avoid having to do so -(@pxref{singe-vs-double}, for the comparison of the two forms). +(@pxref{singe-vs-double}, for a comparison of the two forms). @node Boolean expressions @subsection Boolean Expressions @cindex and @cindex or @@ -8868,13 +8868,13 @@ when its first argument is not a valid @acronym{IP} address. @code{interval} function if its argument is not a valid time interval (@pxref{time interval specification}). @cindex ioerr, exception type @item ioerr An error occurred during the input-output operation. @xref{I/O -functions}, for the description of functions that can signal this +functions}, for a description of functions that can signal this exception. @cindex macroundef, exception type @item macroundef A Sendmail macro is undefined. @@ -9466,13 +9466,13 @@ 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}. +@xref{String formatting}, for a description of @var{format}. Example usage: @smallexample printf('Function %s returned %d', %funcname, %retcode) @end smallexample @@ -10061,24 +10061,24 @@ the action to all available databases. @xref{compact cronjob}. @opsummary{domain} @item -D @var{string} @itemx --domain=@var{string} Set default @acronym{SMTP} domain. Overrides @samp{#pragma option ehlo} (@pxref{pragma ehlo}). This option is -deprecated@footnote{@xref{31x-400}, for the detailed description of +deprecated@footnote{@xref{31x-400}, for a detailed description of why it is deprecated.}: use @option{-v ehlo_domain=@var{string}} instead. @opsummary{ehlo} @itemx --ehlo=@var{string} Same as @option{--domain}. @opsummary{expire-interval} @item -e @var{interval} @itemx --expire-interval=@var{interval} Set expiration intervals for all databases to the specified interval. -@xref{time interval specification}, for the description of +@xref{time interval specification}, for a description of @var{interval} format. The option overrides @samp{#pragma option expire-interval} (@pxref{pragma expire-interval}), which you are advised to use instead. @opsummary{foreground} @item --foreground @@ -10109,13 +10109,13 @@ compaction if any such error is encountered. @opsummary{include} @item --include=@var{dir} @itemx -I @var{dir} Add the directory @var{dir} to the list of directories to be searched for header files. This will affect the functioning of @code{#include} -statement. @xref{include}, for the discussion of file inclusion. +statement. @xref{include}, for a discussion of file inclusion. @opsummary{lock-retry-count} @item --lock-retry-count=@var{number} Set maximum number of attempts to acquire the lock on a database. See the description of @code{#pragma option lock-retry-count}, @ref{pragma lock-retry-count}, for more information about the database @@ -10127,13 +10127,13 @@ Set the time span between the two locking attempts. See the description of @code{#pragma option lock-retry-count}, @ref{pragma lock-retry-count}, for more information about database locking. This option overrides the value set by @code{#pragma option lock-retry-timeout} (@pxref{pragma lock-retry-timeout}. -@xref{time interval specification}, for the description of valid +@xref{time interval specification}, for a description of valid @var{interval} formats. @opsummary{mailer} @item --mailer=@var{url} @itemx -M @var{url} Set the @acronym{URL} of the mailer to use. @xref{Mail Sending @@ -10141,13 +10141,13 @@ Functions}. @opsummary{mailfrom} @item --mailfrom=@var{email} Set postmaster email address. Overrides @samp{#pragma option ehlo}, which you are advised to use instead (@pxref{pragma ehlo}). The default is null return address (@samp{""}). This option is -deprecated@footnote{@xref{31x-400}, for the detailed +deprecated@footnote{@xref{31x-400}, for a detailed description of why it is deprecated.}: use @option{-v mailfrom_address=@var{string}} instead. @opsummary{mtasim} @item --mtasim This option is reserved for use by @command{mtasim} (@pxref{mtasim}). @@ -10218,13 +10218,13 @@ Set source address for TCP connections. Overrides @samp{#pragma option source}, which you are advised to use instead (@pxref{pragma source}). @opsummary{time-format} @item --time-format=@var{format} Set format to be used for timestamps in listings, produced by @option{--list}. The @var{format} is any valid @code{strftime} format -string, see @ref{Time and Date Formats}, for the detailed description. +string, see @ref{Time and Date Formats}, for a detailed description. The default @var{format} is @samp{%c} (@pxref{%c time format}). To analyze @kbd{mailfromd --list} output using text tools, such as @code{awk} or @code{grep}, the following format might be useful: @samp{%s} (@pxref{%s time format}). Another format I find useful is @samp{%Y-%m-%d_%H:%M:%S}. @@ -10237,26 +10237,26 @@ user}). Default user is @samp{@value{DEFAULT-USER}}. @opsummary{variable} @item -v @var{var}=@var{value} @itemx --variable @var{var}=@var{value} Assign @var{value} to the global variable @var{var}. The variable must be declared in your startup script. @xref{overriding initial -values}, for the detailed discussion of this option. +values}, for a detailed discussion of this option. @ignore -- Not used any more, but supported for backward compatibility @opindex config-file -- Reserved for future use @opindex compile @end ignore @end table @node Timeout Control @subsection Timeout Control -@xref{time interval specification}, for the format of @var{interval} value. +@xref{time interval specification}, for information on @var{interval} format. @table @option @opsummary{milter-timeout} @item --milter-timeout=@var{interval} Set @acronym{MTA} connection timeout. Overrides @samp{#pragma option milter-timeout}, which you are advised to use instead (@pxref{pragma @@ -10296,13 +10296,13 @@ script file, the detailed dump of the lexer states and matched rules will be output. @opsummary{dump-macros} @item --dump-macros Show Sendmail macros used in the script file. The macro names are displayed as comma-separated lists, grouped by handler names. -@xref{Sendmail Configuration}, for the detailed description of this +@xref{Sendmail Configuration}, for a detailed description of this option and its usage. @opsummary{dump-tree} @item --dump-tree Parse and compile the script file and dump the parse tree in a printable form to the terminal. @@ -10332,13 +10332,13 @@ else but for debugging, as it terribly degrades performance! @opsummary{stack-trace} @item --stack-trace Add @acronym{MFL} stack trace information to runtime error output. Overrides @code{#pragma option stack-trace}, which you are advised to use instead (@pxref{pragma stack-trace}). @xref{tracing runtime -errors}, for the detailed description of this feature. +errors}, for more information on this feature. @opsummary{gacopyz-log} @item --gacopyz-log=@var{level} Set desired logging level for @command{gacopyz} library (@pxref{Gacopyz}). There are five logging levels. The following table lists them in order of decreasing priority: |