diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-04-09 16:33:54 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2009-04-09 16:33:54 +0300 |
commit | 8e51f4c4bcffd7e1610e237eb2be2cb2e9d978e6 (patch) | |
tree | 242ea586baade9dac032d9f21212caf50513a9f9 /doc | |
parent | 31de05a6d5105bb3f9350e2cfa217b057949edbe (diff) | |
download | mailfromd-8e51f4c4bcffd7e1610e237eb2be2cb2e9d978e6.tar.gz mailfromd-8e51f4c4bcffd7e1610e237eb2be2cb2e9d978e6.tar.bz2 |
Document #pragma dbprop
Diffstat (limited to 'doc')
-rw-r--r-- | doc/mailfromd.texi | 116 |
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} |