Implement getpw.* interfaces

* mfd/bi_getpw.m4: New file.
* mfd/Makefile.am (M4_FILES): Add bi_getpw.m4
* doc/Makefile.am (check-builtins): Take into
account @deftypefnx
* NEWS, doc/mailfromd.texi: Update

4 files changed, 69 insertions, 3 deletions

diff --git a/NEWS b/NEWS
index 780bdcc7..a1b052a3 100644
--- a/NEWS
+++ b/NEWS
@@ -1,2 +1,2 @@
-Mailfromd NEWS -- history of user-visible changes. 2009-06-14
+Mailfromd NEWS -- history of user-visible changes. 2009-08-18
 Copyright (C) 2005, 2006, 2007, 2008, 2009 Sergey Poznyakoff
@@ -90,3 +90,22 @@ do so, its first argument must be a valid socket URL prefixed with
 The I/O operations on `fd' will write to and read from the opened socket.
-  
+
+* System user database functions
+
+These functions provide interfaces to corresponding POSIX calls:
+
+- string getpwnam (string NAME)
+- string getpwuid (number UID)
+
+The return value is the string in the usual /etc/passwd format.
+If argument is not found in the system password database, these
+functions raise the e_not_found exception.
+
+In addition, the following two functions are provided for checking
+whether the given key is present in the system password database:
+
+- boolean mappwnam (string NAME)
+- boolean mappwuid (number UID)
+
+These functions never raise exceptions.
+ 
 * New I/O functions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 1a7396c4..499c2181 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -67,3 +67,3 @@ check-builtins:
     s/[ \t]*MF_DEFUN_CTYPE *(\([a-zA-Z_][a-zA-Z0-9_]*\))/\1/p}'\
-    's/@deftypefn {Built-in Function} *[^ ][^ ]* *\([^ ]*\).*/\1/p' \
+    's/@deftypefnx\{0,1\} {Built-in Function} *[^ ][^ ]* *\([^ ]*\).*/\1/p' \
     $(top_srcdir)/mfd/bi_*.m4 -- \
diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi
index 86f4d845..60af5b07 100644
--- a/doc/mailfromd.texi
+++ b/doc/mailfromd.texi
@@ -245,2 +245,3 @@ Built-in and Library Functions
 * System functions::
+* Passwd functions::
 * Sieve Interface::
@@ -5888,2 +5889,3 @@ in version @value{VERSION}.
 * System functions::
+* Passwd functions::
 * Sieve Interface::
@@ -8024,2 +8026,46 @@ mask.
 
+@node Passwd functions
+@subsubsection System User Database
+
+@deftypefn {Built-in Function} string getpwnam (string @var{name})
+@deftypefnx {Built-in Function} string getpwuid (number @var{uid})
+Look for the user @var{name} (@code{getpwnam}) or user ID @var{uid}
+(@code{getpwuid}) in the system password database and return the
+corresponding record, if found.  If not found, raise the
+@samp{e_not_found} exception.
+
+The returned record consists of six fields, separated by colon sign:
+
+@smallexample
+uname:passwd:uid:gid:gecos:dir:shell
+@end smallexample
+
+@multitable @columnfractions 0.3 0.6
+@headitem Field @tab Meaning
+@item uname     @tab user name
+@item passwd    @tab user password
+@item uid       @tab user ID
+@item gid       @tab group ID
+@item gecos     @tab real name 
+@item dir       @tab home directory 
+@item shell     @tab shell program
+@end multitable
+
+For example:
+
+@smallexample
+getpwnam("gray")
+@result{} "gray:x:1000:1000:Sergey Poznyakoff:/home/gray:/bin/bash"
+@end smallexample
+@end deftypefn
+
+Following two functions can be used to test for existence of a key in
+the user database:
+
+@deftypefn {Built-in Function} boolean mappwnam (string @var{name})
+@deftypefnx {Built-in Function} boolean mappwuid (number @var{uid})
+Return @samp{true} if @var{name} (or @var{uid}) is found in the system
+user database.
+@end deftypefn
+
 @node Sieve Interface
diff --git a/mfd/Makefile.am b/mfd/Makefile.am
index cf5637c3..962dc589 100644
--- a/mfd/Makefile.am
+++ b/mfd/Makefile.am
@@ -30,2 +30,3 @@ M4_FILES=\
  bi_getopt.m4\
+ bi_getpw.m4\
  bi_gettext.m4\