Document #pragma dbprop

1 files changed, 96 insertions, 20 deletions

diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi
index 8b2b4f83..8a6d66b5 100644
--- a/doc/mailfromd.texi
+++ b/doc/mailfromd.texi
@@ -46,7 +46,7 @@ Published by the Free Software Foundation,
 51 Franklin Street, Fifth Floor,
 Boston, MA 02110-1301 USA 
 
-Copyright @copyright{} 2005, 2006, 2007, 2008 Sergey Poznyakoff
+Copyright @copyright{} 2005, 2006, 2007, 2008, 2009 Sergey Poznyakoff
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.2 or
@@ -2597,7 +2597,9 @@ database.  The name of @acronym{PAM} service to use is @samp{mailfromd}.
 
 @smallexample
 @group
-if dbmap("/etc/mail/aliases.db", localpart($rcpt_addr), 1)
+#pragma /etc/mail/aliases.db null
+
+if dbmap("/etc/mail/aliases.db", localpart($rcpt_addr))
    and validuser localpart $rcpt_addr
   @dots{}
 fi
@@ -2605,6 +2607,7 @@ fi
 @end smallexample
 
 For more information about @code{dbmap} function, see @ref{dbmap}.
+For a description of @code{dbprop} pragma, see @ref{Database functions}.
 
 @node Examining mail contents
 @section Examining mail contents
@@ -4111,6 +4114,7 @@ and @samp{#pragma regex} controls the compilation of regular expressions.
 * database::    Pragma database.
 * stacksize::   Pragma stacksize.
 * regex::       Pragma regex.
+* dbprop::      Pragma dbprop.
 @end menu
 
 @node option
@@ -4656,6 +4660,18 @@ regex settings.  E.g.:
 @end group
 @end smallexample
 
+@node dbprop
+@subsection Pragma dbprop
+@cindex dbprop, pragma
+@cindex #pragma dbprop
+
+@smallexample
+#pragma dbprop @var{pattern} @var{prop} [@var{prop}]
+@end smallexample
+
+This pragma configures properties for a @acronym{DBM} database.
+@xref{Database functions}, for its detailed description.
+
 @node Data Types
 @section Data Types
 
@@ -7376,19 +7392,85 @@ information on these.
 @node Database functions
 @subsubsection Database Functions
 
+The functions described below provide a user interface to 
+@acronym{DBM} databases.
+
+Each @acronym{DBM} database is a separate disk file that keeps 
+@dfn{key/value pairs}.  The interface allows to retrieve the value
+corresponding to a given key.  Both @samp{key} and @samp{value} are
+null-terminated character strings.  To lookup a key, it is important
+to know whether its length includes the terminating null byte.  By
+default, it is assumed that it does not.
+
+Another important database property is the @dfn{file mode} of the
+database file.  The default file mode is @samp{640}
+(i.e. @samp{rw-r----}, in symbolic notation).
+
+Both properties can be configured using the @code{dbprop} pragma:
+
+@kwindex dbprop, 
+@cindex dbprop, pragma
+@cindex #pragma dbprop
+@smallexample
+#pragma dbprop @var{pattern} @var{prop} [@var{prop}]
+@end smallexample
+
+The @var{pattern} is the database name or shell-style globbing
+pattern.  Properties defined by that pragma apply to each database
+whose name matches this pattern.  If several @code{dbprop} pragmas
+match the database name, the one that matches exactly is preferred.
+
+The rest of arguments define properties for that database.  The valid
+values for @var{prop} are:
+
+@enumerate 1
+@item 
+The word @samp{null}, meaning that the terminating null byte is
+included in the key length.
+
+Setting @samp{null} property is necessary, for databases created with
+@command{makemap -N hash} command.
+
+@item
+File mode for the disk file.  It can be either an octal number, or
+a symbolic mode specification in ls-like format.  E.g., the following
+two formats are equivalent:
+
+@smallexample
+@group
+640
+rw-r----
+@end group
+@end smallexample
+@end enumerate
+
+For example, consider the following pragmas:
+
+@smallexample
+#pragma dbprop /etc/mail/*.db null 600
+#pragma dbprop /etc/mail/whitelist.db 640
+#pragma dbprop /etc/mail/blacklist.db 640
+@end smallexample
+
+The first of them tells that each database in @file{/etc/mail}
+directory must have the mode @samp{600} and include the null
+terminator in the key length.  The remaining two pragmas define
+two exceptions: the databases @file{whitelist.db} and
+@file{blacklist.db} have privileges @samp{640} and do not include
+null in the key length.
+
+Additionally, for compatibility with previous versions (up to 5.0),
+the terminating null property can be requested via an optional
+argument to the database functions (in description below, marked as
+@var{null}).
+
 @anchor{dbmap}
 @deftypefn {Built-in Function} boolean dbmap (string @var{db}, @
     string @var{key}, [number @var{null}])
   Looks up @var{key} in the @acronym{DBM} file @var{db} and returns
 @code{true} if it is found.
 
-  If the third argument is given and it is not zero, @code{dbmap} will
-include trailing null character into the key.  This is necessary, for
-example, for searching in @file{/etc/mail/aliases.db}.
-
-   In general, if the database @var{db} was created with
-@command{makemap -N hash} command, then you need to use non-zero third
-argument in the invocation of @code{dbmap}.
+  See above for the meaning of @var{null}.
 
 @xref{whitelisting}, for an example of using this function.
 @end deftypefn
@@ -7399,10 +7481,7 @@ argument in the invocation of @code{dbmap}.
 associated with it.  If the key is not found returns @var{default}, if
 specified, or empty string otherwise.
 
-  If the optional @var{null} argument is given and is not zero, the
-terminating null character will be included in @var{key} length.  It
-is useful if @var{db} was created using @command{makemap -N hash}
-command.
+  See above for the meaning of @var{null}.
 @end deftypefn
 
 @deftypefn {Library Function} string safedbget (string @var{db}, @
@@ -7429,8 +7508,7 @@ database error occurs while attempting to retrieve the record,
 @var{value}.  If a record with the given @var{key} already exists, its
 value is replaced with the supplied one.
 
-  If the optional @var{null} argument is given and is not zero, the
-terminating null character will be included in @var{key} length.
+  See above for the meaning of @var{null}.
 @end deftypefn
 
 @deftypefn {Library Function} void safedbput (string @var{db}, @
@@ -7451,14 +7529,12 @@ the function returns without reporting an error.
 @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})
+ string @var{key} [, number @var{null}])
   Delete from the database the record with the given @var{key}.  If
 there are no such record, return without signalling error.
 
-  The optional @var{null} argument has the same meaning as for the
-rest of database functions (see above).
+  If the optional @var{null} argument is given and is not zero, the
+terminating null character will be included in @var{key} length.
 @end deftypefn
 
 @anchor{dbm-seq}