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,3 +1,3 @@ -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 See the end of file for copying conditions. @@ -146,4 +146,19 @@ also expired if no mails were received during a time span greater than 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 ** Second argument to envfrom and envrcpt diff --git a/doc/Makefile.am b/doc/Makefile.am index 8003e824..c10bb0b1 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -26,4 +26,5 @@ mailfromd_TEXINFOS=\ smap.texi\ 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,4 +1,3 @@ @setfilename fdl.info -@appendix GNU Free Documentation License @cindex FDL, GNU Free Documentation License @center Version 1.2, November 2002 diff --git a/doc/gacopyz.texi b/doc/gacopyz.texi index 5eecc6f2..7354db6c 100644 --- a/doc/gacopyz.texi +++ b/doc/gacopyz.texi @@ -5,5 +5,4 @@ @c Invariant Sections, with the Front-Cover texts being ``Mailfromd Manual'', @c and with the Back-Cover Texts at your option. -@appendix Gacopyz @ifhtml diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi index 8276c6f9..8ac9d7bb 100644 --- a/doc/mailfromd.texi +++ b/doc/mailfromd.texi @@ -88,11 +88,11 @@ Software Foundation raise funds for GNU development.'' @contents -@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 @menu @@ -117,4 +117,5 @@ Appendices * Gacopyz:: * Time and Date Formats:: +* Upgrading:: * Copying This Manual:: The GNU Free Documentation License. * Concept Index:: Index of Concepts. @@ -140,17 +141,4 @@ Sender Address Verification. * Limitations:: -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 @@ -360,8 +348,21 @@ Configuration Example * Inetd Pies:: +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 @end menu -@node Preface, Intro, Top, Top +@node Preface @unnumbered Preface @@ -526,9 +527,10 @@ invested a lot of his time in finding bugs and testing bugfixes. @cindex Ben McKeegan John McEleney and Ben McKeegan contributed the token bucket filter -implementation (@code{tbf_rate} function, @FIXME-pxref{}). +implementation (@pxref{TBF}). @cindex Con Tassios 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}). The following people (in alphabetical order) provided bug reports @@ -544,5 +546,5 @@ Alan Dobkin, Brent Spencer, Jeff Ballard, Nacho Gonz@'alez L@'opez, Phil Miller, Simon Christian, Thomas Lynch. -@node Intro, Building, Preface, Top +@node Intro @chapter Introduction to @command{mailfromd} @@ -822,5 +824,5 @@ commands. The framework is explained in detail in @acronym{RFC} 4408 using @acronym{SPF} to control mail flow. -@node Building, Tutorial, Intro, Top +@node Building @chapter Building the Package @@ -1103,439 +1105,13 @@ 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 @@ -1547,7 +1123,8 @@ 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. @menu @@ -2798,26 +2375,28 @@ Manual}). Here we will give only some practical advices for 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 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: @smallexample @group -:mailfromd --authorization=pam:system \ - --pam-service=mailfromd +program mailfromd @{ + auth @{ + authorization pam:system; + @} + + pam @{ + service mailfromd; + @} +@} @end group @end smallexample @@ -2863,5 +2442,5 @@ time after which a record is considered expired. To obtain the list of available databases along with their preconfigured settings, run @kbd{mailfromd --show-defaults}. You will -see a similar output: +see an output similar to this: @smallexample @@ -4168,5 +3747,5 @@ Future versions of the program will provide a non-ambiguous way of referring to variables and constants from literal strings. -@node MFL, Using MFL Mode, Tutorial, Top +@node MFL @chapter Mail Filtering Language @cindex MFL @@ -5355,10 +4934,10 @@ 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.: +@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 @@ -5367,4 +4946,12 @@ features. @end deftypevr +@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__ Expands to the textual representation of the program version @@ -5372,9 +4959,13 @@ Expands to the textual representation of the program version @end deftypevr -@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 @@ -6211,7 +5802,6 @@ invocation syntax is the same for both groups. 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. @menu @@ -6808,5 +6398,16 @@ done @node Header modification functions @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. @deftypefn {Built-in Function} void header_add (string @var{name}, @ @@ -6833,5 +6434,5 @@ i.e. it inserts a header @samp{@var{name}: @samp{value}} at [, number @var{index}]) 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}. Notice the differences between this function and the @code{delete} @@ -6985,5 +6586,5 @@ functions}, for a description of functions for accessing messages. @node Mailbox functions @subsubsection Mailbox Functions -@UNREVISED{} +@cindex mailbox functions A set of functions is provided for accessing mailboxes and messages within them. In this subsection we describe the functions for @@ -7049,16 +6650,36 @@ descriptior @var{nsmg} must be obtained from a previous call to @node Message functions @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 @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 @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 @@ -7099,6 +6720,7 @@ raised. If another error occures, the @code{failure} exception is 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}). @end deftypefn @@ -7147,6 +6769,6 @@ there are no more lines to read, raise the @code{not_found} exception. @FIXME{Probably a special exception type is needed for that.} -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 @@ -7787,10 +7409,13 @@ 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 @var{value}. If a record with the given @var{key} already exists, its 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 @@ -7810,8 +7435,10 @@ the function returns without reporting an error. @noindent @xref{Modules}, for a description of @acronym{MFL} module system. +@FIXME{safedbput should probably take an optional mode argument, as +dbput does.} @end deftypefn @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 there are no such record, return without signalling error. @@ -7819,4 +7446,7 @@ there are no such record, return without signalling error. If the optional @var{null} argument is given and is not zero, the 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 @@ -12000,5 +11630,5 @@ Any keyword beginning with a @samp{m4_} prefix is a reserved preprocessor symbol. -@node Using MFL Mode, Mailfromd Configuration, MFL, Top +@node Using MFL Mode @chapter Using the GNU Emacs MFL Mode @cindex Emacs, @acronym{MFL} mode @@ -12217,5 +11847,5 @@ loop for set n 0 @end defvr -@node Mailfromd Configuration, Sendmail, Using MFL Mode, Top +@node Mailfromd Configuration @chapter Configuring @command{mailfromd} @@ -12980,5 +12610,5 @@ instructions on how to do so depend on the operating system you use and are beyond the scope of this manual. -@node Sendmail, MeTA1, Mailfromd Configuration, Top +@node Sendmail @chapter Using @command{mailfromd} with Sendmail. @@ -13104,25 +12734,25 @@ f, @{client_addr@} @end smallexample -@node MeTA1, mtasim, Sendmail, Top +@node MeTA1 @chapter Using @command{mailfromd} with MeTA1. @WRITEME{} -@node mtasim, smap, MeTA1, Top +@node mtasim @chapter @command{mtasim} --- a testing tool @include mtasim.texi -@node smap, pmult, mtasim, Top +@node smap @chapter A universal socket-map program for MeTA1. @include smap.texi -@node pmult, pies, smap, Top +@node pmult @chapter Pmilter multiplexer program. @include pmult.texi -@node pies, Reporting Bugs, pmult, Top +@node pies @chapter Pies -- a program execution supervisor. @include pies.texi -@node Reporting Bugs, Gacopyz, pies, Top +@node Reporting Bugs @chapter How to Report a Bug @@ -13159,15 +12789,21 @@ line options used). @end itemize -@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, |