diff options
Diffstat (limited to 'doc/mailfromd.texi')
| -rw-r--r-- | doc/mailfromd.texi | 128 |
1 files changed, 71 insertions, 57 deletions
diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi index e4b456d1..27ff4c46 100644 --- a/doc/mailfromd.texi +++ b/doc/mailfromd.texi @@ -133,6 +133,7 @@ Sender Address Verification. Building the Package +* 43x-440:: Upgrading from 4.3.x to 4.4 * 420-43x:: Upgrading from 4.2 to 4.3.x * 410-420:: Upgrading from 4.1 to 4.2 * 400-410:: Upgrading from 4.0 to 4.1 @@ -987,6 +988,7 @@ the corresponding section below. @end enumerate @menu +* 43x-440:: Upgrading from 4.3.x to 4.4 * 420-43x:: Upgrading from 4.2 to 4.3.x * 410-420:: Upgrading from 4.1 to 4.2 * 400-410:: Upgrading from 4.0 to 4.1 @@ -996,6 +998,11 @@ the corresponding section below. * 1x-2x:: Upgrading from 1.x to 2.x @end menu +@node 43x-440 +@section Upgrading from 4.3.x to 4.4 +@cindex Upgrading from 4.3.x to 4.4 +@UNREVISED{} + @node 420-43x @section Upgrading from 4.2 to 4.3.x @cindex Upgrading from 4.2 to 4.3.x @@ -3167,7 +3174,7 @@ done @end smallexample Another common case are undefined Sendmail macros. In this case the -@code{macroundef} exception is generated: +@code{e_macroundef} exception is generated: @smallexample RUNTIME ERROR near foo.c:34: Macro not defined: @{client_adr@} @@ -5386,7 +5393,7 @@ starting at @var{start}. If @var{length} is omitted, the rest of @var{str} is used. If @var{length} is greater than the actual length of the string, the -@code{range} exception is signalled. +@code{e_range} exception is signalled. @smallexample substr("mailfrom", 4) @result{} "from" @@ -5520,7 +5527,7 @@ 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 +@samp{e_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 @@ -5657,7 +5664,7 @@ arguments: @end table If the function is unable to encode the string, it raises the -exception @code{failure}. +exception @code{e_failure}. For example: @@ -5674,7 +5681,7 @@ message_header_encode(%string, "ISO-8859-1") (string @var{text}, [string @var{charset}]) @var{text} must be a header value encoded in accordance with @acronym{RFC} 2047. The function returns the decoded string. If the decoding fails, -it raises @code{failure} exception. The optional argument +it raises @code{e_failure} exception. The optional argument @var{charset} specifies the character set to use (default -- @samp{UTF-8}). @@ -5734,7 +5741,7 @@ using @var{domain} as @code{EHLO} domain and @var{mailfrom} as In contrast to @code{strictpoll} function, this function does not use cache database and does not fall back to polling @acronym{MX} servers if the main poll tempfails. The function can throw one of the following -exceptions: @code{failure}, @code{temp_failure}. +exceptions: @code{e_failure}, @code{e_temp_failure}. @end deftypefn @deftypefn {Built-in Function} number _pollmx @ @@ -5746,7 +5753,7 @@ FROM} address. Returns 0 or 1 depending on the result of the test. In contrast to @code{stdpoll} function, @code{_pollmx} does not use cache database and does not fall back to polling the @var{ip} if the poll fails. The function can throw one of the following -exceptions: @code{failure}, @code{temp_failure}. +exceptions: @code{e_failure}, @code{e_temp_failure}. @end deftypefn @deftypefn {Built-in Function} number stdpoll @ @@ -5755,7 +5762,7 @@ exceptions: @code{failure}, @code{temp_failure}. Performs standard poll for @var{email}, using @var{domain} as @code{EHLO} domain and @var{mailfrom} as @code{MAIL FROM} address. Returns 0 or 1 depending on the result of the test. Can raise one of -the following exceptions: @code{failure}, @code{temp_failure}. +the following exceptions: @code{e_failure}, @code{e_temp_failure}. In @code{on} statement context, it is synonymous to @code{poll} without explicit @var{host}. @FIXME{more details and references} @@ -5873,7 +5880,7 @@ inet_ntoa(len_to_netmask(24)) @result{} 255.255.255.0 inet_ntoa(len_to_netmask(7)) @result{} 254.0.0.0 @end smallexample -If @var{n} is greater than 32 the function raises @code{range} +If @var{n} is greater than 32 the function raises @code{e_range} exception. @end deftypefn @@ -6031,7 +6038,7 @@ returns the fully qualified domain name of the host represented by Sendmail variable @samp{client_addr}. If there is no @samp{PTR} record for @var{ip}, @code{primitive_hostname} -raises the exception @code{not_found}. +raises the exception @code{e_not_found}. If @acronym{DNS} query fails, the function raises @code{failure} or @code{temp_failure}, depending on the character of the failure. @@ -6066,7 +6073,7 @@ is a host name or @acronym{IP} address. records for the @var{domain}. If @var{domain} has no @samp{MX} records, @code{primitive_ismx} raises -exception @code{not_found}. +exception @code{e_not_found}. If @acronym{DNS} query fails, the function raises @code{failure} or @code{temp_failure}, depending on the character of the failure. @@ -6090,7 +6097,7 @@ function returns @code{false}. Reverse of @code{primitive_hostname}. The @code{primitive_resolve} function returns the @acronym{IP} address for the host name specified by @var{host} argument. If @var{host} has no A records, the function raises the -exception @code{not_found}. +exception @code{e_not_found}. If @acronym{DNS} lookup fails, the function raises @code{failure} or @code{temp_failure}, depending on the character of the failure. @@ -6312,14 +6319,14 @@ rest of database functions (see above). (@pxref{Database Formats}). If it is valid, the function returns the expiration interval for that format. @FIXME{How to obtain negative expiration??} Otherwise, @code{db_expire_interval} raises the -@code{not_found} exception. +@code{e_not_found} exception. @end deftypefn @deftypefn {Built-in Function} string db_name (string @var{fmtid}) The @var{fmt} argument is a database format identifier (@pxref{Database Formats}). The function returns the file name for that format. If @var{fmtid} does not match any known format, -@code{db_name} raises the @code{not_found} exception. +@code{db_name} raises the @code{e_not_found} exception. @end deftypefn @cindex getting cache status @@ -6327,7 +6334,7 @@ for that format. If @var{fmtid} does not match any known format, @deftypefn {Built-in Function} number db_get_active (string @var{fmtid}) Returns the flag indicating whether the cache database @var{fmtid} is currently enabled. If @var{fmtid} does not match any known format, -@code{db_name} raises the @code{not_found} exception. +@code{db_name} raises the @code{e_not_found} exception. @end deftypefn @cindex disabling cache @@ -6401,7 +6408,7 @@ the program's standard output. of an existing file and @code{open} will attempt to open this file for reading. - The @code{open} function will signal exception @code{failure} if it + The @code{open} function will signal exception @code{e_failure} if it is unable to open the resource or get the required access to it. @end deftypefn @@ -6410,7 +6417,7 @@ is unable to open the resource or get the required access to it. previous call to @code{open}. The function @code{close} closes the resource and deallocates any memory associated with it. - @code{close} will signal @code{range} exception if @var{rd} lies + @code{close} will signal @code{e_range} exception if @var{rd} lies outside of allowed range of resource descriptors. @FIXME{More info on it} @end deftypefn @@ -6425,8 +6432,8 @@ termination of the filtering program. Writes the string @var{str} to the resource descriptor @var{rd}. If the @var{size} argument is given, writes this number of bytes. - The function will signal @code{range} exception if @var{rd} lies -outside of allowed range of resource descriptors, and @code{ioerr} + The function will signal @code{e_range} exception if @var{rd} lies +outside of allowed range of resource descriptors, and @code{e_io} exception if an @acronym{I/O} error occurs. @end deftypefn @@ -6436,7 +6443,7 @@ descriptor @var{rd}. The terminating newline character will be removed from the return value. The function will signal @code{range} exception if @var{rd} lies -outside of allowed range of resource descriptors, and @code{ioerr} +outside of allowed range of resource descriptors, and @code{e_io} exception if an @acronym{I/O} error occurs. @end deftypefn @@ -6691,8 +6698,8 @@ message. @end table The @code{sa} function can signal the following exceptions: -@code{failure} if the connection fails, @code{url} if the supplied -@acronym{URL} is invalid and @code{range} if the supplied port number +@code{e_failure} if the connection fails, @code{e_url} if the supplied +@acronym{URL} is invalid and @code{e_range} if the supplied port number is out of the range 1--65535. The simplest way to use the function is: @@ -6749,8 +6756,8 @@ done @code{clamav_virus_name} global variable. The @code{clamav} function can signal the following exceptions: -@code{failure} if connection failed, @code{url} if the supplied -@acronym{URL} is invalid and @code{range} if the supplied port number +@code{e_failure} if connection failed, @code{e_url} if the supplied +@acronym{URL} is invalid and @code{e_range} if the supplied port number is out of the range 1--65535. An example usage: @@ -6781,7 +6788,7 @@ of greylisting period in the internal variable @code{greylist_seconds_left}. @xref{Greylisting}, for a detailed explanation. - The function @code{greylist} can signal @code{dbfailure} exception. + The function @code{greylist} can signal @code{e_dbfailure} exception. @end deftypefn @deftypefn {Built-in Function} boolean listens (string @var{host}, [number @var{port}]) @@ -8298,7 +8305,7 @@ returns true only if any of the @samp{MX}s for (domain or email) @var{x} match the globbing pattern @var{y}. Both @code{mx matches} and @code{mx fnmatches} can signal the -following exceptions: @code{temp_failure}, @code{failure}. +following exceptions: @code{e_temp_failure}, @code{e_failure}. The value of any parenthesized subexpression occurring within the right-hand side argument to @code{matches} or @code{mx matches} can be @@ -9047,69 +9054,71 @@ following table summarizes all the exception types implemented by @command{mailfromd} version @value{VERSION}: @table @code -@cindex dbfailure, exception type -@item dbfailure +@cindex e_dbfailure, exception type +@item e_dbfailure General database failure. For example, the database cannot be opened. This exception can be signaled by any function that queries any @acronym{DBM} database. -@cindex divzero, exception type -@item divzero +@cindex e_divzero, exception type +@item e_divzero Division by zero. +@cindex e_failure, exception type @cindex failure, exception type -@item failure +@item e_failure +@itemx failure A general failure has occurred. In particular, this exception is signaled by @acronym{DNS} lookup functions when any permanent failure occurs. This exception can be signaled by any @acronym{DNS}-related function (@code{hasmx}, @code{poll}, etc.) or operation (@code{mx matches}). -@cindex invcidr, exception type -@item invcidr +@cindex e_invcidr, exception type +@item e_invcidr Invalid @acronym{CIDR} notation. This is signaled by @code{match_cidr} function when its second argument is not a valid @acronym{CIDR}. -@cindex invip, exception type -@item invip +@cindex e_invip, exception type +@item e_invip Invalid @acronym{IP} address. This is signaled by @code{match_cidr} function when its first argument is not a valid @acronym{IP} address. -@cindex invtime, exception type -@item invtime +@cindex e_invtime, exception type +@item e_invtime Invalid time interval specification. It is signaled by @code{interval} function if its argument is not a valid time interval (@pxref{time interval specification}). -@cindex ioerr, exception type -@item ioerr +@cindex e_io, exception type +@item e_io An error occurred during the input-output operation. @xref{I/O functions}, for a description of functions that can signal this exception. -@cindex macroundef, exception type -@item macroundef +@cindex e_macroundef, exception type +@item e_macroundef A Sendmail macro is undefined. -@cindex noresolve, exception type -@item noresolve +@cindex e_noresolve, exception type +@item e_noresolve The argument of a @acronym{DNS}-related function cannot be resolved to host name or @acronym{IP} address. Currently only @code{ismx} (@pxref{ismx}) raises this exception. -@cindex range, exception type -@item range +@cindex e_range, exception type +@item e_range The supplied argument is outside the allowed range. This is signalled, for example, by @code{substring} function (@pxref{substring}). -@cindex regcomp, exception type -@item regcomp +@cindex e_regcomp, exception type +@item e_regcomp Regular expression cannot be compiled. This can happen when a regular expression (a right-hand argument of a @code{matches} operator) is built at the runtime and the produced string is an invalid regex. -@cindex ston_conv, exception type -@item ston_conv +@cindex e_ston_conv, exception type +@item e_ston_conv String-to-number conversion failed. This can be signaled when a string is used in numeric context which cannot be converted to the numeric data type. For example: @@ -9126,13 +9135,15 @@ data type. For example: The @code{if} condition will signal @code{ston_conv}, since @samp{10a} cannot be converted to a number. +@cindex e_temp_failure, exception type @cindex temp_failure, exception type -@item temp_failure +@item e_temp_failure +@itemx temp_failure A temporary failure has occurred. This can be signaled by @acronym{DNS}-related functions or operations. -@cindex url, exception type -@item url +@cindex e_url, exception type +@item e_url The supplied @acronym{URL} is invalid. @xref{Interfaces to Third-Party Programs}. @@ -9140,14 +9151,17 @@ Third-Party Programs}. @end table @cindex success, exception type +@cindex e_success, exception type @cindex not_found, exception type +@cindex e_not_found, exception type In addition to these, two symbols are defined that are not exception types in the strict sense of the world, but are provided to make writing filter scripts more convenient. These are @code{success}, meaning successful return from a function, and @code{not_found}, meaning that the required entity (e.g. domain name or email address) was not found. @xref{figure-poll-wrapper}, for an illustration on -how these can be used. +how these can be used. For consistency with other exception codes, +these can be spelled as @code{e_success} and @code{e_not_found}. @cindex exceptions, default handling @cindex default exception handling @@ -9179,8 +9193,8 @@ where @var{exception-list} is the list of exception types, separated by the word @code{or}. A special form @samp{*}, which stands for all exceptions, is allowed as well. The @var{handler-body} is the list of statements comprising the handler body. For example, the code below -installs a handler for exceptions 2 (@samp{failure}) and 3 -(@samp{temp_failure}): +installs a handler for exceptions 2 (@samp{e_failure}) and 3 +(@samp{e_temp_failure}): @smallexample @group @@ -9204,7 +9218,7 @@ above code snippet will look like: @group #include <status.mfh> -catch failure or temp_failure +catch e_failure or e_temp_failure do @dots{} done @@ -9255,7 +9269,7 @@ In the latter case, a log message is also issued: prog envfrom do - catch failure or temp_failure + catch e_failure or e_temp_failure do echo "Caught exception $1: $2" continue |