diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-05-06 00:19:33 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-05-06 00:44:49 +0300 |
commit | d2d21d1e6a06239fa97e50435abcea66b60678ae (patch) | |
tree | fc99ddaed8b77da3877a36b1b87e35cbf9455e51 | |
parent | 2e9e8087eef5452299cfc839b7b4cc23bb2feb6c (diff) | |
download | mailfromd-d2d21d1e6a06239fa97e50435abcea66b60678ae.tar.gz mailfromd-d2d21d1e6a06239fa97e50435abcea66b60678ae.tar.bz2 |
Minor changes.
* NEWS: Update.
* doc/mailfromd.texi: Reorder material.
* doc/upgrade.texi: New file.
* doc/fdl.texi, doc/gacopyz.texi, doc/strftime.texi: Move
sectioning commands to the main source.
* etc/mailfromd.rc: Reflect recent changes.
* mfd/lex.l: Change semantics of __statedir__
and __preproc__. Introduce __defstatedir__ and
__defpreproc__.
-rw-r--r-- | NEWS | 17 | ||||
-rw-r--r-- | doc/Makefile.am | 1 | ||||
-rw-r--r-- | doc/fdl.texi | 1 | ||||
-rw-r--r-- | doc/gacopyz.texi | 1 | ||||
-rw-r--r-- | doc/mailfromd.texi | 664 | ||||
-rw-r--r-- | doc/strftime.texi | 1 | ||||
-rw-r--r-- | doc/upgrade.texi | 474 | ||||
-rw-r--r-- | etc/mailfromd.rc | 25 | ||||
-rw-r--r-- | mfd/lex.l | 14 |
9 files changed, 666 insertions, 532 deletions
@@ -1,2 +1,2 @@ -Mailfromd NEWS -- history of user-visible changes. 2009-05-04 +Mailfromd NEWS -- history of user-visible changes. 2009-05-06 Copyright (C) 2005, 2006, 2007, 2008, 2009 Sergey Poznyakoff @@ -147,2 +147,17 @@ the value of the 2nd argument to the rate (or rateok) function. +* The __statedir__ built-in constant. + +The __statedir__ built-in constant is now expanded to the current +value of the program state directory. In prior releases it used to +expand to the default program state directory. A new built-in +constant __defstatedir__ is introduced, which expands to the value of +the default program state directory. + +* The __preproc__ built-in constant. + +Similarly, the __preproc__ built-in constant, which used to signify +the default preprocessor command line, now expands to its current +value. The new constant __defpreproc__ expands to the default +preprocessor command line. + * Bugfixes diff --git a/doc/Makefile.am b/doc/Makefile.am index 8003e824..c10bb0b1 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -27,2 +27,3 @@ mailfromd_TEXINFOS=\ strftime.texi\ + upgrade.texi\ values.texi diff --git a/doc/fdl.texi b/doc/fdl.texi index a3c8c6fa..7da87389 100644 --- a/doc/fdl.texi +++ b/doc/fdl.texi @@ -1,3 +1,2 @@ @setfilename fdl.info -@appendix GNU Free Documentation License @cindex FDL, GNU Free Documentation License diff --git a/doc/gacopyz.texi b/doc/gacopyz.texi index 5eecc6f2..7354db6c 100644 --- a/doc/gacopyz.texi +++ b/doc/gacopyz.texi @@ -6,3 +6,2 @@ @c and with the Back-Cover Texts at your option. -@appendix Gacopyz diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi index 8276c6f9..8ac9d7bb 100644 --- a/doc/mailfromd.texi +++ b/doc/mailfromd.texi @@ -89,9 +89,9 @@ Software Foundation raise funds for GNU development.'' -@node Top, Preface, (dir), (dir) +@ifnottex +@node Top +@top Mailfromd -@ifinfo -@chapter Mailfromd This edition of the @cite{Mailfromd Manual}, last updated @value{UPDATED}, documents @command{mailfromd} Version @value{VERSION}. -@end ifinfo +@end ifnottex @@ -118,2 +118,3 @@ Appendices * Time and Date Formats:: +* Upgrading:: * Copying This Manual:: The GNU Free Documentation License. @@ -141,15 +142,2 @@ Sender Address Verification. -Building the Package - -* 500-510:: Upgrading from 5.0 to 5.1 -* 440-500:: Upgrading from 4.4 to 5.0 -* 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 -* 31x-400:: Upgrading from 3.1.x to 4.0 -* 30x-31x:: Upgrading from 3.0.x to 3.1 -* 2x-30x:: Upgrading from 2.x to 3.0.x -* 1x-2x:: Upgrading from 1.x to 2.x - Tutorial @@ -361,2 +349,15 @@ Configuration Example +Upgrading + +* 500-510:: Upgrading from 5.0 to 5.1 +* 440-500:: Upgrading from 4.4 to 5.0 +* 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 +* 31x-400:: Upgrading from 3.1.x to 4.0 +* 30x-31x:: Upgrading from 3.0.x to 3.1 +* 2x-30x:: Upgrading from 2.x to 3.0.x +* 1x-2x:: Upgrading from 1.x to 2.x + @end detailmenu @@ -364,3 +365,3 @@ Configuration Example -@node Preface, Intro, Top, Top +@node Preface @unnumbered Preface @@ -527,3 +528,3 @@ invested a lot of his time in finding bugs and testing bugfixes. John McEleney and Ben McKeegan contributed the token bucket filter -implementation (@code{tbf_rate} function, @FIXME-pxref{}). +implementation (@pxref{TBF}). @@ -531,3 +532,4 @@ implementation (@code{tbf_rate} function, @FIXME-pxref{}). Con Tassios helped to find and fix various bugs and contributed the -new implementation of the @code{greylist} function (@FIXME-pxref{}). +new implementation of the @code{greylist} function (@pxref{greylisting +types}). @@ -545,3 +547,3 @@ Phil Miller, Simon Christian, Thomas Lynch. -@node Intro, Building, Preface, Top +@node Intro @chapter Introduction to @command{mailfromd} @@ -823,3 +825,3 @@ using @acronym{SPF} to control mail flow. -@node Building, Tutorial, Intro, Top +@node Building @chapter Building the Package @@ -1104,437 +1106,11 @@ and mode. @item Examine filter script file -(@file{@var{sysconfdir}/mailfromd.etc}) and edit it, if necessary. If -you are upgrading from an older version of @command{mailfromd}, see -the corresponding section below. -@end enumerate - -@menu -* 500-510:: Upgrading from 5.0 to 5.1 -* 440-500:: Upgrading from 4.4 to 5.0 -* 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 -* 31x-400:: Upgrading from 3.1.x to 4.0 -* 30x-31x:: Upgrading from 3.0.x to 3.1 -* 2x-30x:: Upgrading from 2.x to 3.0.x -* 1x-2x:: Upgrading from 1.x to 2.x -@end menu - -@node 500-510 -@section Upgrading from 5.0 to 5.1 -@cindex Upgrading from 5.0 to 5.1 -@WRITEME - -@node 440-500 -@section Upgrading from 4.4 to 5.0 -@cindex Upgrading from 4.4 to 5.0 - - This version of Mailfromd requires -@uref{http://www.gnu.org/software/mailutils, GNU mailutils} version -2.0 or later. - - Upgrading from version 4.4 to 5.0 requires no additional -changes. The major differences between these two versions are -summarized below: - -@enumerate 1 -@item Support for @samp{MeTA1}. - -@item New @samp{Mailutils} configuration file. - -@item New @acronym{MFL} functions. - -@enumerate a -@item Message functions. @xref{Message functions}. -@item Mailbox functions. @xref{Mailbox functions}. -@item Mail body functions. @xref{Mail body functions}. -@item Header modification functions. @xref{Header modification functions}. -@item Envelope modification functions. @xref{Envelope modification functions}. -@item Quarantine functions. @xref{Quarantine functions}. -@item @code{getopt} and @code{varptr}. @xref{getopt}. -@item Macro access functions. @xref{Macro access}. -@item Character type functions. @xref{Character Type}. -@item New string functions (@pxref{String manipulation}): -@code{verp_extract_user}, @code{sa_format_report_header}, -@code{sa_format_score}. -@item Sequential access to DBM files. @xref{dbm-seq}. -@end enumerate - -@item Changes in @acronym{MFL} - -@enumerate 1 -@item @xref{variadic functions}. -@item @xref{function alias}. -@end enumerate - -@item New operation mode: @xref{Run Mode}. - -@item Improved stack growth technique. - -The stack can be grown either by fixed size blocks, or -exponentially. Upper limit can be specified. @xref{stacksize}. - -@item Milter ports can be specified using @acronym{URL} notation. - -@item Removed deprecated features. - -Support for some deprecated features has been withdrawn. These are: - -@enumerate a -@item Command line options @option{--ehlo}, -@option{--postmaster-email}, and @option{--mailfrom}. -These became deprecated in version 4.0. @xref{31x-400}. -@end enumerate - -@end enumerate - -@node 43x-440 -@section Upgrading from 4.3.x to 4.4 -@cindex Upgrading from 4.3.x to 4.4 - - The deprecated @option{--domain} command line option has been -withdrawn. The short option @option{-D} now defines a preprocessor -symbol (@pxref{Preprocessor Options}). - - This version correctly handles name clashes between constants and -variables, which remained unnoticed in previous releases. -@xref{variable--constant shadowing}, for a detailed description of it. - - To minimize chances of name clashes, all symbolic exception codes has -been renamed by prefixing them with the @samp{e_}, thus, e.g. @code{divzero} -became @code{e_divzero}, etc. The @code{ioerr} exception code is renamed to -@code{e_io}. @xref{status.mfh}, for a full list of the new exception codes. - -@cindex @code{OLD_EXCEPTION_CODES}, preprocessor symbol - For consistency, the following most often used codes are available without -the @samp{e_} previx: success, not_found, failure, temp_failure. This -makes most existing user scripts suitable for use with version 4.4 -without any modification. If your script refers to any exception -codes other than these four, you can still use it by defining a -preprocessor symbol @code{OLD_EXCEPTION_CODES}, for example: - -@smallexample -$ mailfromd -DOLD_EXCEPTION_CODES -@end smallexample - -@node 420-43x -@section Upgrading from 4.2 to 4.3.x -@cindex Upgrading from 4.2 to 4.3.x -@cindex @code{DEFAULT_SYSLOG_ASYNC}, @command{configure} variable - - Upgrading from 4.2 to 4.3 or 4.3.1 does not require any changes to -your configuration and scripts. The only notable change in these -versions is the following: - - The asynchronous syslog implementation was reported to malfunction -on some systems (notably on Solaris), so this release does not enable -it by default. The previous meaning of the @option{--enable-syslog-async} -configuration option is also restored. Use this option in order to -enable asynchronous syslog feature. To set default syslog -implementation, use @code{DEFAULT_SYSLOG_ASYNC} configuration variable -(@pxref{syslog-async}). - -The following deprecated features are removed: - -@enumerate -@item @code{#pragma option ehlo} statement. - -It became deprecated in version 4.0. @xref{pragma-option-ehlo}. - -@item @code{#pragma option mailfrom} statement. - -It became deprecated in version 4.0. @xref{pragma-option-ehlo}. +(@file{@var{sysconfdir}/mailfromd.etc}) and edit it, if necessary. -@item The @option{--config-file} command line option. - -It became deprecated in version 3.1. @xref{30x-31x}. - -@item Built-in exception codes in catch statements. - -They are deprecated since version 4.0. @xref{31x-400}. -@end enumerate +@item Upgrading +If you are upgrading from an earlier release of Mailfromd, refer to +@ref{Upgrading}, for detailed instructions. -@node 410-420 -@section Upgrading from 4.1 to 4.2 -@cindex Upgrading from 4.1 to 4.2 - Upgrading to this version does not require any special efforts. You -can use your configuration files and filter scripts without any -changes. The only difference worth noticing is that starting from this -version @command{mailfromd} is always compiled with asynchronous -syslog implementation. The @option{--enable-syslog-async} -configuration file option is still available, but its meaning has -changed: it sets the @emph{default} syslog implementation to use -(@pxref{syslog-async}). Thus, it can be used the same way it was in -previous versions. You can also select the syslog implementation at -run time, see @ref{Logging and Debugging, --syslog-async option}, for -more detailed information. - -@node 400-410 -@section Upgrading from 4.0 to 4.1 -@cindex Upgrading from 4.0 to 4.1 - - 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 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 -(@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 - - Before building this version, please re-read the chapter -@xref{Building}, especially the section @ref{syslog-async, Using -non-blocking syslog}. - - Starting from the version 4.0, @acronym{MFL} no longer uses the -predefined symbolic names for exception codes (previous versions used -the @samp{&} prefix to dereference them). Instead, it relies on -constants defined in the include file @file{status.mfh} -(@pxref{status.mfh}). - - However, the script files from 3.1 series will still work, but -the following warning messages will be displayed: - -@smallexample -Warning: obsolete constant form used: &failure -Warning: remove leading '&' and include <status.mfh> - -Warning: Using built-in exception codes is deprecated -Warning: Please include <status.mfh> -@end smallexample - -@anchor{pragma-option-ehlo} - Another important difference is that pragmatic options @samp{ehlo} -and @samp{mailfromd} are now deprecated, as well as their command line -equivalents @option{--ehlo} and @option{--domain}. These options -became superfluous after the introduction of @code{mailfrom_address} -and @code{ehlo_domain} built-in variables. For compatibility with the -previous versions, they are still supported by @command{mailfromd} -4.0, but a warning message is issued if they are used: - -@smallexample -@group -warning: `#pragma option ehlo' is deprecated, - consider using `set ehlo_domain "domain.name"' instead -@end group -@end smallexample - - To update your startup scripts for the new version follow these -steps: - -@enumerate 1 -@item - Change @code{#pragma option mailfrom @var{value}} to -@code{set mailfrom_address @var{value}}. Refer to -@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 a detailed discussion of this variable. -@item - Include @file{status.mfh}. Add the following line to the top of -your startup file: - -@smallexample -#include_once <status.mfh> -@end smallexample - -@item - Remove all instances of @samp{&} in front of the constants. You can -use the following @command{sed} expression: @samp{s/&\([a-z]\)/\1/g}. - -@item - If your code uses any of the following functions: @code{hostname}, -@code{resolve}, @code{hasmx} or @code{ismx}, add the following line -to the top of your script: - -@smallexample -#require dns -@end smallexample - -@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 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 - -@enumerate 1 -@item - The @command{mailfromd} binary no longer supports -@option{--config-file} (@option{-c}) option. To use an alternative -script file, give it as an argument, i.e. instead of: - -@smallexample -$ @kbd{mailfromd --config-file @var{file.rc}} -@end smallexample - -@noindent -write: -@smallexample -$ @kbd{mailfromd @var{file.rc}} -@end smallexample - - For backward compatibility, the old style invocation still works but -produces a warning message. However, if @command{mailfromd} -encounters the @option{-c} option it will print a diagnostic message -and exit immediately. This is because the semantics of this option -will change in the future releases. - -@item - If a variable is declared implicitly within a function, it is -created as automatic. This differs from the previous versions, where -all variables were global. It is a common practice to use global -variables to pass additional information between handlers (@xref{HELO -Domain}, for an example of this approach). If your filter uses it, -make sure the variable is declared as global. For example, this code: - -@float Figure, old-code -@caption{Implicit declaration, old style} -@smallexample -prog helo -do - # @r{Save the host name for further use} - set helohost $s -done -@end smallexample -@end float - -@noindent -has to be rewritten as follows: - -@float Figure, new-code -@caption{Implicit declaration, new style} -@smallexample -set helohost "" - -prog helo -do - # @r{Save the host name for further use} - set helohost $s -done -@end smallexample -@end float - -@item - Starting from version 3.1 the function @code{dbmap} takes an -optional third argument indicating whether or not to count the -terminating null character in key (@pxref{dbmap}). If your startup -script contained any calls to @code{dbmap}, change them as follows: - -@multitable @columnfractions 0.5 0.5 -@headitem in 3.0.x @tab in 3.1 -@item dbmap(@var{db}, @var{key}) @tab dbmap(@var{db}, @var{key}, 1) -@end multitable - -@end enumerate - - -@node 2x-30x -@section Upgrading from 2.x to 3.0.x -@cindex upgrading from 2.x to 3.0.x - Update your startup scripts and/or crontab entries. The -@command{mailfromd} binary is now installed in @file{$@{prefix@}/sbin}. - - We also encourage you to update the startup script (run -@kbd{cp etc/rc.mailfromd /wherever-your-startup-lives}), since the new -version contains lots of enhancements. - -@node 1x-2x -@section Upgrading from 1.x to 2.x -@cindex upgrading from 1.x to 2.x - If you are upgrading from version 1.x to 2.0, you will have to do -the following: - -@enumerate 1 -@item -Edit your script file and enclose the entire code section into: - -@smallexample -@group -prog envfrom -do - @dots{} -done -@end group -@end smallexample - -@noindent -@xref{Handlers}, for more information about the @code{prog} statement. - -@item -If your code contained any @code{rate} statements, convert them to -function calls (@pxref{Rate limiting functions, rate}), using the -following scheme: - -@smallexample -@group -Old statement: if rate @var{key} @var{limit} / @var{expr} -New statement: if rate(@var{key}, interval("@var{expr}")) > @var{limit} -@end group -@end smallexample - -For example, -@smallexample - rate $f 180 / 1 hour 25 minutes -@end smallexample -@noindent -should become -@smallexample - rate($f, interval("1 hour 25 minutes")) > 180 -@end smallexample - -@item -Rebuild your databases using the following command: - -@smallexample -mailfromd --compact --all -@end smallexample - -@noindent -This is necessary since the format of @command{mailfromd} databases -has changed in version 2.0: the key field now includes the trailing -@samp{NUL} character, which is also reflected in its length. This -allows for empty (zero-length) keys. @xref{Database Maintenance}, for -more information about the database compaction. -@end enumerate - -@node Tutorial, MFL, Building, Top +@node Tutorial @chapter Tutorial @@ -1548,5 +1124,6 @@ common practical tasks. If you are familiar to @command{mailfromd}, you can skip this -chapter and go directly to the next one, that contains detailed -discussion of the configuration language and @command{mailfromd} -interaction with the Mail Transport Agent. +chapter and go directly to the next one (@pxref{Mail Filtering +Language}), which contains detailed discussion of the mail filtering +language and @command{mailfromd} interaction with the Mail Transport +Agent. @@ -2799,3 +2376,3 @@ implementing it in @command{mailfromd} filters. - The actual list of authorization module available depends on your + The actual list of available authorization modules depends on your @command{mailutils} installation. Usually it includes, apart from @@ -2803,15 +2380,10 @@ traditional @acronym{UNIX} @file{passwd} database, the functions for verifying @acronym{PAM}, @acronym{RADIUS} and @acronym{SQL} database accounts. -Each of the authorization -methods is configured using special command line options. Run -@command{mailfromd --help} and you will get the listing of those under -@samp{Authentication options} section. For the exact meaning of each -particular option, refer to @ref{auth, auth, Authentication and -Authorization Options, mailutils, GNU Mailutils Manual}. It is often -inconvenient to specify all required options in the command line, so you are -advised to use @dfn{mailutils system configuration file}. -@xref{configuration, Mailutils Configuration File, Mailutils -Configuration File, mailutils, GNU Mailutils Manual}, for its -description. Its use boils down to placing in it all -the necessary authorization options, prefixed by the label -@code{:mailfromd}. For example, the following @file{mailutils.rc} statement: +Each of the authorization methods is configured using special +configuration file statements. For the description of the Mailutils +configuration files, @xref{configuration, Mailutils Configuration +File, Mailutils Configuration File, mailutils, GNU Mailutils Manual}. +You can obtain the template for @command{mailfromd} configuration by +running @command{mailfromd --config-help}. + + For example, the following @file{mailutils.rc} file: @@ -2819,4 +2391,11 @@ the necessary authorization options, prefixed by the label @group -:mailfromd --authorization=pam:system \ - --pam-service=mailfromd +program mailfromd @{ + auth @{ + authorization pam:system; + @} + + pam @{ + service mailfromd; + @} +@} @end group @@ -2864,3 +2443,3 @@ time after which a record is considered expired. preconfigured settings, run @kbd{mailfromd --show-defaults}. You will -see a similar output: +see an output similar to this: @@ -4169,3 +3748,3 @@ referring to variables and constants from literal strings. -@node MFL, Using MFL Mode, Tutorial, Top +@node MFL @chapter Mail Filtering Language @@ -5356,8 +4935,8 @@ patch level. For stable versions, expands to @samp{0}. -@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.: +@deftypevr {Built-in constant} string __defpreproc__ + Expands to the default external preprocessor command line, if the +preprocessor is used, or to an empty string if it is not, e.g.: @smallexample -__preproc__ @result{} "/usr/bin/m4 -s" +__defpreproc__ @result{} "/usr/bin/m4 -s" @end smallexample @@ -5368,2 +4947,10 @@ features. +@deftypevr {Built-in constant} string __preproc__ + Expands to the current external preprocessor command line, if the +preprocessor is used, or to an empty string if it is not. Notice, +that it equals @code{__defpreproc__}, unless the preprocessor was +redefined using @option{--preprocessor} command line option +(@pxref{Preprocessor, --preprocessor}). +@end deftypevr + @deftypevr {Built-in constant} string __version__ @@ -5373,7 +4960,11 @@ Expands to the textual representation of the program version -@deftypevr {Built-in constant} string __statedir__ +@deftypevr {Built-in constant} string __defstatedir__ Expands to the default state directory (@pxref{statedir}). -@FIXME{Should have a way to determine the current value of statedir, -as set by state-directory pragma, or, better yet, have a variable -reflecting it (r/w).} +@end deftypevr + +@deftypevr {Built-in constant} string __statedir__ +Expands to the current value of the program state directory +(@pxref{statedir}). Notice, that it is the same as +@code{__defstatedir__} unless the state directory was redefined at run +time. @end deftypevr @@ -6212,5 +5803,4 @@ functions}. In addition to these you can define your own functions. - @FIXME{In subsequent sections we will discuss the library and built-in -functions first, and then we will explain how to write your -functions}. + In subsequent sections we will discuss the library and built-in +functions, and then we will explain how to write new functions. @@ -6809,3 +6399,14 @@ done @subsubsection Header Modification Functions -@UNREVISED{} +@cindex header modification + + There are two ways to modify message headers in a @acronym{MFL} +script. First is to use header actions, described in @ref{Actions}, +and the second way is to use message modification functions. Compared +with the actions, the functions offer a series of advantages. For +example, using functions you can construct the name of the header to +operate upon (e.g. by concatenating several arguments), something +which is impossible when using actions. Moreover, apart from three +basic operations (add, modify and remove), as supported by header +actions, header functions allow to insert a new header into a +particular place. @@ -6834,3 +6435,3 @@ i.e. it inserts a header @samp{@var{name}: @samp{value}} at Delete header @var{name} from the envelope. If @var{index} is given, -delete @var{index}th instance of header @var{name}. +delete @var{index}th instance of the header @var{name}. @@ -6986,3 +6587,3 @@ functions}, for a description of functions for accessing messages. @subsubsection Mailbox Functions -@UNREVISED{} +@cindex mailbox functions A set of functions is provided for accessing mailboxes and messages @@ -7050,6 +6651,24 @@ descriptior @var{nsmg} must be obtained from a previous call to @subsubsection Message Functions -@UNREVISED{} - +@cindex message functions + The functions described below retrieve information from RFC822 +messages. The message to operate upon is identified by its +@dfn{descriptor}, an integer number returned by the previous call to +@code{mailbox_get_message} (@pxref{Mailbox functions, +mailbox_get_message}) or @code{current_message} +(@pxref{current_message}) function. + @deftypefn {Built-in Function} number message_size (number @var{nmsg}) -Return the size of the message @var{nmsg}, in bytes. +Return the size of the message @var{nmsg}, in bytes. @emph{Notice}, +that if @var{nmsg} refers to current message +(@pxref{current_message}), the returned value is less than the size +seen by the @acronym{MTA}, because @command{mailfromd} recodes +@acronym{CR-LF} sequences to @acronym{LF}, i.e. removes carriage +returns (@acronym{ASCII} 13) ocurring before line feeds +(@acronym{ASCII} 10. To obtain actual message length as seen by the +@acronym{MTA}, add the number of lines in the message: + +@smallexample + set actual_length message_size(%nmsg) + message_lines(%nmsg) +@end smallexample + @end deftypefn @@ -7057,3 +6676,4 @@ Return the size of the message @var{nmsg}, in bytes. @deftypefn {Built-in Function} number message_body_size (number @var{nmsg}) -Return the size, in bytes, of the body of message @var{nmsg}. +Return the size, in bytes, of the body of message @var{nmsg}. See the +note to the @code{message_size}, above. @end deftypefn @@ -7061,3 +6681,4 @@ Return the size, in bytes, of the body of message @var{nmsg}. @deftypefn {Built-in Function} number message_header_size (number @var{nmsg}) -Return the size, in bytes of the headers of message @var{nmsg}. +Return the size, in bytes of the headers of message @var{nmsg}. See the +note to the @code{message_size}, above. @end deftypefn @@ -7100,4 +6721,5 @@ raised. -The returned string is a verbatim copy of the message contents. You -might need to apply the @code{unfold} function to it (@pxref{Mail +The returned string is a verbatim copy of the message contents (except +for eventual @acronym{CR-LF} -> @acronym{LF} translation, see above). +You might need to apply the @code{unfold} function to it (@pxref{Mail header functions, unfold}). @@ -7148,4 +6770,4 @@ there are no more lines to read, raise the @code{not_found} exception. -Use @code{message_body_rewind} to rewind the body stream and read its -contents again. +Use @code{message_body_rewind} (see above) to rewind the body stream +and read its contents again. @end deftypefn @@ -7788,3 +7410,4 @@ database error occurs while attempting to retrieve the record, @deftypefn {Built-in Function} void dbput (string @var{db}, @ - string @var{key}, string @var{value} [, number @var{null}]) + string @var{key}, string @var{value} [, @ + number @var{null}, number @var{mode} ]) Inserts in the database a record with the given @var{key} and @@ -7793,3 +7416,5 @@ value is replaced with the supplied one. - See above for the meaning of @var{null}. + See above for the meaning of @var{null}. Optional @var{mode} allows +to explicitly specify the file mode for this database. See also +@code{#pragma dbprop}, described above. @end deftypefn @@ -7811,2 +7436,4 @@ the function returns without reporting an error. @xref{Modules}, for a description of @acronym{MFL} module system. +@FIXME{safedbput should probably take an optional mode argument, as +dbput does.} @end deftypefn @@ -7814,3 +7441,3 @@ the function returns without reporting an error. @deftypefn {Built-in Function} void dbdel (string @var{db}, @ - string @var{key} [, number @var{null}]) + string @var{key} [, number @var{null}, number @var{mode}]) Delete from the database the record with the given @var{key}. If @@ -7820,2 +7447,5 @@ there are no such record, return without signalling error. terminating null character will be included in @var{key} length. + + Optional @var{mode} allows to explicitly specify the file mode for +this database. See also @code{#pragma dbprop}, described above. @end deftypefn @@ -12001,3 +11631,3 @@ preprocessor symbol. -@node Using MFL Mode, Mailfromd Configuration, MFL, Top +@node Using MFL Mode @chapter Using the GNU Emacs MFL Mode @@ -12218,3 +11848,3 @@ loop for set n 0 -@node Mailfromd Configuration, Sendmail, Using MFL Mode, Top +@node Mailfromd Configuration @chapter Configuring @command{mailfromd} @@ -12981,3 +12611,3 @@ and are beyond the scope of this manual. -@node Sendmail, MeTA1, Mailfromd Configuration, Top +@node Sendmail @chapter Using @command{mailfromd} with Sendmail. @@ -13105,3 +12735,3 @@ f, @{client_addr@} -@node MeTA1, mtasim, Sendmail, Top +@node MeTA1 @chapter Using @command{mailfromd} with MeTA1. @@ -13109,3 +12739,3 @@ f, @{client_addr@} -@node mtasim, smap, MeTA1, Top +@node mtasim @chapter @command{mtasim} --- a testing tool @@ -13113,3 +12743,3 @@ f, @{client_addr@} -@node smap, pmult, mtasim, Top +@node smap @chapter A universal socket-map program for MeTA1. @@ -13117,3 +12747,3 @@ f, @{client_addr@} -@node pmult, pies, smap, Top +@node pmult @chapter Pmilter multiplexer program. @@ -13121,3 +12751,3 @@ f, @{client_addr@} -@node pies, Reporting Bugs, pmult, Top +@node pies @chapter Pies -- a program execution supervisor. @@ -13125,3 +12755,3 @@ f, @{client_addr@} -@node Reporting Bugs, Gacopyz, pies, Top +@node Reporting Bugs @chapter How to Report a Bug @@ -13160,13 +12790,19 @@ line options used). -@node Gacopyz, Time and Date Formats, Reporting Bugs, Top +@node Gacopyz +@appendix Gacopyz @include gacopyz.texi -@node Time and Date Formats, Copying This Manual, Gacopyz, Top +@node Time and Date Formats +@appendix Time and Date Formats @include strftime.texi -@node Copying This Manual, Concept Index, Time and Date Formats, Top +@node Upgrading +@appendix Upgrading +@include upgrade.texi + +@node Copying This Manual +@appendix GNU Free Documentation License @include fdl.texi -@node Concept Index, , Copying This Manual, Top -@comment node-name, next, previous, up +@node Concept Index @unnumbered Concept Index diff --git a/doc/strftime.texi b/doc/strftime.texi index 4e504dc6..bfed61df 100644 --- a/doc/strftime.texi +++ b/doc/strftime.texi @@ -5,3 +5,2 @@ -@appendix Time and Date Formats diff --git a/doc/upgrade.texi b/doc/upgrade.texi new file mode 100644 index 00000000..43663499 --- /dev/null +++ b/doc/upgrade.texi @@ -0,0 +1,474 @@ +@c Copyright (C) 2005, 2006, 2009 Sergey Poznyakoff +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.2 or +@c any later version published by the Free Software Foundation; with no +@c Invariant Sections, with the Front-Cover texts being ``Mailfromd Manual'', +@c and with the Back-Cover Texts at your option. + + +The following sections describe procedures for upgrading +between the consequtive Mailfromd releases. + +@menu +* 500-510:: Upgrading from 5.0 to 5.1 +* 440-500:: Upgrading from 4.4 to 5.0 +* 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 +* 31x-400:: Upgrading from 3.1.x to 4.0 +* 30x-31x:: Upgrading from 3.0.x to 3.1 +* 2x-30x:: Upgrading from 2.x to 3.0.x +* 1x-2x:: Upgrading from 1.x to 2.x +@end menu + +@node 500-510 +@appendixsec Upgrading from 5.0 to 5.1 +@cindex Upgrading from 5.0 to 5.1 + + Upgrading from 5.0 to 5.1 does not require any changes in your +filter scripts. Notice, however, the following important points: + +@itemize @bullet +@item The semantics of @code{_ |