Update the docs

* Makefile.am: Use plain git log to format the ChangeLog.
* git2chg.awk: Remove.

* NOTE-WARNING: Update.
* README: Likewise.
* README-alpha: Likewise.
* README-hacking: Likewise.
* doc/gdbm.3: Likewise.
* doc/gdbm.texi

8 files changed, 967 insertions, 407 deletions

diff --git a/Makefile.am b/Makefile.am
index d7667fd..25e200d 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -14,7 +14,7 @@
 # You should have received a copy of the GNU General Public License
 # along with GDBM. If not, see <http://www.gnu.org/licenses/>. */
 
-EXTRA_DIST = build-aux/config.rpath NOTE-WARNING git2chg.awk
+EXTRA_DIST = build-aux/config.rpath NOTE-WARNING
 
 if COMPAT_OPT
   MAYBE_COMPAT = compat
@@ -49,8 +49,18 @@ prev_change_log = ChangeLog.cvs
 .PHONY: ChangeLog
 ChangeLog:
 	$(AM_V_GEN)if test -d .git; then                                    \
-                git log --pretty='format:%ct  %an  <%ae>%n%n%s%n%n%b%n'     \
-                        --since=$(gen_start_date) |                         \
-                awk -f $(top_srcdir)/git2chg.awk                            \
-                    -v append=$(top_srcdir)/$(prev_change_log) > ChangeLog; \
+          (git log --pretty='format:%ad  %cn  <%ae>%n%n%w(72,8,8)%s%n%n%b'  \
+                   --date=short                                             \
+                   --since=$(gen_start_date);                               \
+           echo "";                                                         \
+           cat $(prev_change_log);                                          \
+           echo "";                                                         \
+           echo "Local Variables:";                                         \
+           echo "mode: change-log";                                         \
+           echo "version-control: never";                                   \
+           echo "buffer-read-only: t";                                      \
+           echo "End:") > ChangeLog.tmp;                                    \
+          cmp ChangeLog ChangeLog.tmp > /dev/null 2>&1 ||                   \
+            mv ChangeLog.tmp ChangeLog;                                     \
+          rm -f ChangeLog.tmp;                                              \
         fi
diff --git a/NOTE-WARNING b/NOTE-WARNING
index 3f21c13..a731a9b 100644
--- a/NOTE-WARNING
+++ b/NOTE-WARNING
@@ -12,7 +12,7 @@ please dump it into a portable format using gdbm_dump and send the resulting
 file instead. The receiving party will be able to recreate the database from
 the dump using the gdbm_load command.
 
-Please refer to the documentation, chapters 22 and 23, for a detailed
+Please refer to the documentation, chapters 25 and 26, for a detailed
 discussion of these two tools. Run `info gdbm gdbm_dump', if gdbm is
 already installed on your system, or `info -f doc/gdbm.info gdbm_dump'
 to read the docs from the source tree.
diff --git a/README b/README
index d7c1380..185c2e3 100644
--- a/README
+++ b/README
@@ -72,19 +72,21 @@ on how to install this file.
   
 * Bug reporting
 
-Please report bugs to <bug-gdbm@gnu.org>
+Please report bugs via email to <bug-gdbm@gnu.org>.  You can also use
+bug-tracker at <https://puszcza.gnu.org.ua/bugs/?group=gdbm>.
 
 * Documentation, updates etc.
 
 For the latest updates, visit <http://www.gnu.org/software/gdbm>,
 
 In particular, a copy of GDBM documentation in various formats is
-available online at <http://www.gnu.org/software/gdbm/manual>.
+available online at <https://www.gnu.org/software/gdbm/manual>.
 
-Latest versions of GDBM can be downloaded from anonymous
-ftp://ftp.gnu.org/gnu/gdbm.
+Latest versions of GDBM can be downloaded from
+<https://ftp.gnu.org/gnu/gdbm>.  You can also use anonymous fpt at
+the same location, if you prefer.
 
-To track the development, visit 
+To track the development, visit
 <http://puszcza.gnu.org.ua/projects/gdbm>.
 
 
diff --git a/README-alpha b/README-alpha
index 7743535..02c09e4 100644
--- a/README-alpha
+++ b/README-alpha
@@ -4,13 +4,13 @@ See end of file for copying conditions.
 * Introduction
 
 This is a *pre-release* version, and not ready for production use yet.
-If you are taking source from CVS, you will need to have several
+If you are taking source from git repository, you will need to have several
 special tools to help contribute.  See the file README-hacking for more
 information.  See chapter `Building' for the detailed instructions on
 how to build the package.
 
 Please, note that the accompanying documentation may be inaccurate
-or incomplete. The ChangeLog file is the authoritative documentation of
+or incomplete.  The ChangeLog file is the authoritative documentation of
 all recent changes.
 
 Please, send comments and problem reports to <bug-gdbm@gnu.org>.
@@ -18,42 +18,24 @@ Please, send comments and problem reports to <bug-gdbm@gnu.org>.
 * Checking Out the Sources
 
 The following instructions apply if you wish to obtain sources from
-the repository.  There are several repositories:
+the repository.
 
-1. CVS at Puszcza.gnu.org.ua - master repository
-   <https://puszcza.gnu.org.ua/cvs/?group=gdbm>
-2. Git at Puszcza.gnu.org.ua - slave
-   <http://puszcza.gnu.org.ua/git/?group=gdbm>
-3. CVS at Savannah.gnu.org - slave
-   <http://savannah.gnu.org/cvs/?group=gdbm>
-4. Git at Savannah.gnu.org - slave
-   <http://savannah.gnu.org/git/?group=gdbm>
-
-Slave repositories are synchronized with the master 8 times a day.
-
-** CVS
-
-To checkout the source tree from CVS issue the following command:
-
-  cvs -d:pserver:anonymous@cvs.gnu.org.ua:/cvsroot/gdbm co gdbm
-
-Or, to checkout the sources from CVS mirror at Savannah, issue the
-following command:
-
-  cvs -d :pserver:anoncvs@cvs.savannah.gnu.org:/cvsroot/gdbm checkout gdbm
+To clone the Git repository, run:
 
-** Git  
+  git clone https://git.gnu.org.ua/gdbm.git
 
-To clone the Git repository, run:
+This will create a directory named `gdbm' and populate it with
+the sources.
 
-  git clone git://git.gnu.org.ua/gdbm.git
+If you are not interested in the entire development history, you can
+minimize the traffic using the `--depth' option.  For example,
 
-Or, to clone the secondary GDBM Git mirrror repo, run:
+  git clone --depth 1 https://git.gnu.org.ua/gdbm.git
 
-  git clone git://git.savannah.gnu.org/gdbm.git
+will clone only the most recent revision from the repository.
 
-In all cases, this will give you read-only access.  If you think you need
-write access, contact <bug-gdbm@gnu.org>.
+For more information about git access, visit
+<https://puszcza.gnu.org.ua/git/?group=gdbm>.
 
 * Building
 
@@ -66,7 +48,6 @@ Usual procedures apply:
 See the files INSTALL and README for the detailed instructions.
 
 * Copyright information:
-Copyright information:
 
 Copyright (C) 1990-2021 Free Software Foundation, Inc.
 
diff --git a/README-hacking b/README-hacking
index a2c946b..e6e5534 100644
--- a/README-hacking
+++ b/README-hacking
@@ -3,16 +3,18 @@ GDBM.
 
 * Requirements
 
-You need the following packages to build the CVS version of GNU
+You need the following packages to build the development version of GNU
 DBM.  We do not make any efforts to accommodate older versions of
 these packages, so please make sure that you have the latest stable
 version. 
 
-- Automake <http://www.gnu.org/software/automake/>
-- Autoconf <http://www.gnu.org/software/autoconf/>
-- Libtool <http://www.gnu.org/software/libtool/>
-- Gettext <http://www.gnu.org/software/gettext/>
-- Texinfo <http://www.gnu.org/software/texinfo>
+- Automake <https://www.gnu.org/software/automake/>
+- Autoconf <https://www.gnu.org/software/autoconf/>
+- Libtool <https://www.gnu.org/software/libtool/>
+- Gettext <https://www.gnu.org/software/gettext/>
+- Texinfo <https://www.gnu.org/software/texinfo/>
+- Bison <https://www.gnu.org/software/bison/>
+- Flex <https://github.com/westes/flex/>
 
 * Bootstrapping
 
diff --git a/doc/gdbm.3 b/doc/gdbm.3
index 6f569dc..2ee817b 100644
--- a/doc/gdbm.3
+++ b/doc/gdbm.3
@@ -13,7 +13,7 @@
 .\"
 .\" You should have received a copy of the GNU General Public License
 .\" along with GDBM. If not, see <http://www.gnu.org/licenses/>. */
-.TH GDBM 3 "July 31, 2021" "GDBM" "GDBM User Reference"
+.TH GDBM 3 "October 17, 2021" "GDBM" "GDBM User Reference"
 .SH NAME
 GDBM \- The GNU database manager.  Includes \fBdbm\fR and \fBndbm\fR
 compatibility.
@@ -25,6 +25,8 @@ compatibility.
 .br
 .BI "extern char *" gdbm_version ;
 .br
+.BI "extern int "  gdbm_version[3] ;
+.br
 .BI "GDBM_FILE gdbm_open (const char *" name ", int " block_size ", "
 .ti +21
 .BI     "int " flags ", int " mode ", "
@@ -68,87 +70,52 @@ compatibility.
 .BI "int gdbm_failure_atomic (GDBM_FILE " dbf ", const char *" even ", const char *" odd ");"
 .br
 .BI "int gdbm_latest_snapshot (const char *" even ", const char *" odd ", const char **" result ");"
-.PP
-.SS DBM Compatibility routines:
-.PP
-.B #include <dbm.h>
-.sp
-.BI "int dbminit (const char *" name ");"
-.br
-.BI "int store (datum " key ", datum " content );
-.br
-.BI "datum fetch (datum " key );
-.br
-.BI "int delete (datum " key );
-.br
-.BI "datum firstkey (void);"
-.br
-.BI "datum nextkey (datum " key );
-.br
-.BI "int dbmclose (void);"
-.PP
-.SS NDBM Compatibility routines:
-.PP
-.B #include <ndbm.h>
-.sp
-.BI "DBM *dbm_open (const char *" name ", int " flags ", int " mode );
-.br
-.BI "void dbm_close (DBM *" file );
-.br
-.BI "datum dbm_fetch (DBM *" file ", datum " key );
-.br
-.BI "int dbm_store (DBM *" file ", datum " key ", datum " content ", int " flags );
-.br
-.BI "int dbm_delete (DBM *" file ", datum " key );
-.br
-.BI "datum dbm_firstkey (DBM *" file );
-.br
-.BI "datum dbm_nextkey (DBM *" file ", datum " key );
-.br
-.BI "int dbm_error (DBM *" file );
-.br
-.BI "int dbm_clearerr (DBM *" file );
-.br
-.BI "int dbm_pagfno (DBM *" file );
-.br
-.BI "int dbm_dirfno (DBM *" file );
-.br
-.BI "int dbm_rdonly (DBM *" file );
-.SH DESCRIPTION
-\fBGNU dbm\fR is a library of routines that manages data files that contain
-key/data pairs.  The access provided is that of storing, 
-retrieval, and deletion by key and a non-sorted traversal of all
-keys.  A process is allowed to use multiple data files at the
-same time.
-
+.SH NOTICE
 This manpage is a short description of the \fBGDBM\fR library.
-For a detailed discussion, including examples of the configuration and
-usage recommendations, refer to the \fBGDBM Manual\fR available in
+For a detailed discussion, including examples and usage
+recommendations, refer to the \fBGDBM Manual\fR available in
 Texinfo format.  To access it, run:
 
   \fBinfo gdbm\fR
 
+The documentation is also available online at
+
+  \fBhttps://www.gnu.org/software/gdbm/manual\fR
+  
 Should any discrepancies occur between this manpage and the
 \fBGDBM Manual\fR, the later shall be considered the authoritative
 source.
-
+.SH DESCRIPTION
+\fBGNU dbm\fR is a library of routines that manages data files that contain
+key/data pairs.  The access provided is that of storing, 
+retrieval, and deletion by key and a non-sorted traversal of all
+keys.  A process is allowed to use multiple data files at the
+same time.
+.SS Opening a database
 A process that opens a gdbm file is designated as a "reader" or a
 "writer".  Only one writer may open a gdbm file and many readers may
 open the file.  Readers and writers can not open the gdbm file at the
 same time. The procedure for opening a gdbm file is:
-
+.PP
 .BI "GDBM_FILE gdbm_open (const char *" name ", int " block_size ", "
 .ti +21
 .BI     "int " flags ", int " mode ", "
 .ti +21
 .BI "void (*" fatal_func ")(const char *))";
-
+.PP
 \fIName\fR is the name of the file (the complete name,
-gdbm does not append any characters to this name).  \fIBlock_size\fR is
-the size of a single transfer from disk to memory. This parameter is
-ignored unless the file is a new file.  The minimum size is 512.  If
-it is less than 512, dbm will use the stat block size for the file system.
-\fIRead_write\fR can have one of the following values:
+\fBgdbm\fR does not append any characters to this name).
+.PP
+\fIBlock_size\fR is the size of a single transfer from disk to
+memory.  If the value is less than 512, the file system block size is
+used instead.  The size is adjusted so that the block can hold exact
+number of directory entries, so that the effective block size can be
+slightly greater than requested.  This adjustment is disabled if the
+\fBGDBM_BSEXACT\fR \fIflag\fR is used.
+.PP
+The \fIflags\fR parameter is a bitmask, composed of the \fIaccess
+mode\fR and one or more modifier flags.  The \fIaccess mode\fR bit
+designates the process as a reader or writer and must be one of the following:
 .TP
 .B GDBM_READER
 reader
@@ -162,21 +129,37 @@ writer - if database does not exist create new one
 .B GDBM_NEWDB
 writer - create new database regardless if one exists
 .PP
-The \fBGDBM_NOMMAP\fR added to \fIread_write\fR by bitwise or instructs
-\fBgdbm_open\fR to disable the use of
-.BR mmap (2).
+Additional flags (\fImodifiers\fR) can be combined with these values
+by bitwise \fBOR\fR.  Not all of them are meaningful with all access
+modes.
 .PP
-For the last three (writers of the database) the following may be added
-added to \fIread_write\fR by bitwise or:
+Flags that are valid for any value of access mode are:
 .TP
-.B GDBM_SYNC
-Causes all database operations to be synchronized to the disk,
+.B GDBM_CLOEXEC
+Set the \fIclose-on-exec\fR flag on the database file descriptor.
 .TP
 .B GDBM_NOLOCK
 Prevents the library from performing any locking on the database file.
 .TP
-.B GDBM_CLOEXEC
-Set the close-on-exec flag on the database file descriptor.
+.B GDBM_NOMMAP
+Instructs \fBgdbm_open\fR to disable the use of
+.BR mmap (2).
+.TP
+.B GDBM_PREREAD
+When mapping GDBM file to memory, read its contents immediately,
+instead of when needed (\fIprefault reading\fR).  This can be
+advantageous if you open a \fIread-only\fR database and are going to
+do a lot of look-ups on it.  In this case entire database will be
+read at once and searches will operate on an in-memory copy.  In
+contrast, \fBGDBM_PREREAD\fR should not be used if you open a database
+(even in read-only mode) only to retrieve a couple of keys.
+.sp
+Finally, never use \fBGDBM_PREREAD\fR when opening a database for
+updates, especially for inserts: this will degrade performance.
+.sp
+This flag has no effect if \fBGDBM_NOMMAP\fR is given, or if the
+operating system does not support prefault reading.  It is known to
+work on Linux and FreeBSD kernels. 					     
 .TP
 .B GDBM_XVERIFY
 Enable additional consistency checks.  With this flag, eventual
@@ -184,123 +167,281 @@ corruptions of the database are discovered when opening it, instead of
 when a corrupted structure is read during normal operation.  However,
 on large databases, it can slow down the opening process.
 .PP
-The option
+The following additional flags are valid when the database is opened
+for writing (\fBGDBM_WRITER\fR, \fBGDBM_WRCREAT\fR, or
+\fBGDBM_NEWDB\fR):
+.TP
+.B GDBM_SYNC
+Causes all database operations to be synchronized to the disk.
+.sp
+\fBNOTE\fR: this option entails severe performance degradation and
+does not necessarily ensure that the resulting database state is
+consistent, therefore we discourage its use.  For a discussion of how
+to ensure database consistency with minimal performance overhead, see
+.B CRASH TOLERANCE
+below.
+.TP
 .B GDBM_FAST
-is now obsolete, since gdbm defaults to no-sync mode.
+A reverse of \fBGDBM_SYNC\fR: synchronize writes only when needed.
+This is the default.  This flag is provided only for compatibility
+with previous versions of GDBM.
+.PP
+The following flags can be used together with \fBGDBM_NEWDB\fR.  They
+also take effect when used with \fBGDBM_WRCREAT\fR, if the requested
+database file doesn't exist:
+.TP
+.B GDBM_BSEXACT
+If this flag is set and the requested \fIblock_size\fR value cannot
+be used, \fBgdbm_open\fR will refuse to create the database.  In this
+case it will set the \fBgdbm_errno\fR variable to
+\fBGDBM_BLOCK_SIZE_ERROR\fR and return \fBNULL\fR.
+.sp
+Without this flag, \fBgdbm_open\fR will silently adjust the
+\fIblock_size\fR to a usable value, as described above.
+.TP
+.B GDBM_NUMSYNC
+Create new database in \fIextended database format\fR, a format best
+suited for effective crash recovery.  For a detailed discussion, see
+the
+.B CRASH RECOVERY
+chapter below.
+.PP
+\fIMode\fR is the file mode (see
+.BR chmod (2)
+and
+.BR open (2)).
+It is used if the file is created.
+.PP
+\fIFatal_func\fR is a function to be called when \fBgdbm\fR if
+it encounters a fatal error.  This parameter is deprecated and must
+always be \fBNULL\fR.
 .PP
-\fIMode\fR is the file mode (see \fBchmod(2)\fR and \fBopen(2)\fR) if the
-file is created. \fI(*Fatal_func) ()\fR is a function for dbm to call
-if it detects a fatal error. The only parameter of this function is a string.
-If the value of 0 is provided, \fBgdbm\fR will use a default function.
-
 The return value is the pointer needed by all other routines to
-access that gdbm file.  If the return is the \fBNULL\fR pointer, \fBgdbm_open\fR
-was not successful.  The errors can be found in \fIgdbm_errno\fR for gdbm
-errors and in \fIerrno\fR for system errors.  (For error codes, see
-gdbmerrno.h.)
-
-In all of the following calls, the parameter \fIdbf\fR refers to the pointer
-returned from \fBgdbm_open\fR.
-
-It is important that every file opened is also closed.  This is needed to
-update the reader/writer count on the file.  This is done by:
-
+access that gdbm file.  If the return is the \fBNULL\fR pointer,
+\fBgdbm_open\fR was not successful.  In this case, the reason of the
+failure can be found in the \fIgdbm_errno\fR variable.  If the
+following call returns \fItrue\fR (non-zero value):
+.sp
+.nf
+.in +5
+  gdbm_check_syserr(gdbm_open)
+.in
+.fi
+.PP
+the system \fIerrno\fR variable must be examined in order to obtain more
+detail about the failure.
+.PP
+.BI "GDBM_FILE gdbm_fd_open (int " FD ", const char *" name ", int " block_size ", "
+.ti +21
+.BI     "int " flags ", int " mode ", "
+.ti +21
+.BI "void (*" fatal_func ")(const char *))";
+.PP
+This is an alternative entry point to \fBgdbm_open\fR.  \fIFD\fR is a
+valid file descriptor obtained as a result of a call to
+.BR open (2)
+or
+.BR creat (2).
+The function opens (or creates) a \fGDBM\fR database this descriptor
+refers to.  The descriptor is not \fBdup\fR'ed, and will be closed
+when the returned \fBGDBM_FILE\fR is closed.  Use
+.B dup (2)
+if that is not desirable.
+.PP
+In case of error, the function behaves like \fBgdbm_open\fR and
+\fBdoes not close\fR \fIFD\fR.  This can be altered by the following
+value passed in \fIflags\fR:
+.TP
+.B GDBM_CLOERROR
+Close \fIFD\fR before exiting on error.
+The rest of arguments are the same as for \fBgdbm_open\fR.
+.SS Calling convention
+.PP
+All \fBGDBM\fR functions take as their first parameter the
+\fIdatabase handle\fR (\fBGDBM_FILE\fR), returned from \fBgdbm_open\fR
+or \fBgdbm_fd_open\fR.
+.PP
+Any value stored in the \fBGDBM\fR database is described by
+\fIdatum\fR, an aggregate type defined as:
+.sp
+.nf
+.in +5
+typedef struct
+{
+  char *dptr;
+  int   dsize;
+} datum;
+.in
+.fi
+.PP
+The \fIdptr\fR field points to the actual data.  Its type is
+\fBchar *\fR for historical reasons.  Actually it should have been
+typed
+\fBvoid *\fR.  Programmers are free to store data of arbitrary
+complexity, both scalar and aggregate, in this field.
+.PP
+The \fIdsize\fR field contains the number of bytes stored in
+\fBdptr\fR.
+.PP
+The \fBdatum\fR type is used to describe both \fIkeys\fR and
+\fIcontent\fR (values) in the database.  Values of this type can
+be passed as arguments or returned from \fBGDBM\fR function calls.
+.PP
+\fBGDBM\fR functions that return \fBdatum\fR indicate failure by setting
+its \fIdptr\fR field to \fBNULL\fR.
+.PP
+Functions returning integer value, indicate success by returning
+0 and failure by returning a non-zero value (the only exception to this
+rule is \fBgdbm_exists\fR, for which the return value is reversed).
+.PP
+If the returned value indicates failure, the \fBgdbm_errno\fR variable
+contains an integer value indicating what went wrong.  A similar value
+is associated with the \fIdbf\fR handle and can be accessed using the
+\fBgdbm_last_errno\fR function.  Immediately after return from a
+function, both values are exactly equal.  Subsequent \fBGDBM\fR calls
+with another \fIdbf\fR as argument may alter the value of the global
+\fBgdbm_errno\fR, but the value returned by \fBgdbm_last_errno\fR will
+always indicate the most recent code of an error that occurred for
+\fIthat particular database\fR.  Programmers are encouraged to use
+such per-database error codes.
+.PP
+Sometimes the actual reason of the failure can be clarified by
+examining the system \fBerrno\fR value.  To make sure its value is
+meaningful for a given \fBGDBM\fR error code, use the
+\fBgdbm_check_syserr\fR function.  The function takes error code as
+argument and returns 1 if the \fBerrno\fR is meaningful for that
+error, or 0 if it is irrelevant.
+.PP
+Similarly to \fBgdbm_errno\fR, the latest \fBerrno\fR value associated
+with a particular database can be obtained using the
+\fBgdbm_last_syserr\fR function.
+.PP
+The \fBgdbm_clear_error\fR clears the error indicator (both \fBGDBM\fR
+and system error codes) associated with a database handle.
+.PP
+Some critical errors leave the database in a \fIstructurally
+inconsistent state\fR.  If that happens, all subsequent \fBGDBM\fR calls
+accessing that database will fail with the \fBGDBM\fR error code of
+\fBGDBM_NEED_RECOVERY\fR (a special function \fBgdbm_needs_recovery\fR
+is also provided, which returns true if the database handle given as
+its argument is structurally inconsistent).  To return such
+databases to consistent state, use the \fBgdbm_recover\fR function
+(see below).
+.PP
+The \fBGDBM_NEED_RECOVERY\fR error cannot be cleared using
+\fBgdbm_clear_error\fR.
+.SS Error functions
+This section describes the error handling functions outlined above.
+.TP
+.BI "gdbm_error gdbm_last_errno (GDBM_FILE " dbf ")"
+Returns the error code of the most recent failure encountered when operating
+on \fIdbf\fR.
+.TP
+.BI "int gdbm_last_syserr (GDBM_FILE " dbf ")"
+Returns the value of the system \fBerrno\fR variable associated with
+the most recent failure that occurred on \fIdbf\fR.
+.sp
+Notice that not all \fBgdbm_error\fR codes have a relevant system
+error code.  Use the following function to determine if a given code has.
+.TP
+.BI "int gdbm_check_syserr (gdbm_error " err ")"
+Returns \fB1\fR, if system \fBerrno\fR value should be checked to get more
+info on the error described by GDBM code \fIerr\fR.
+.TP
+.BI "void gdbm_clear_error (GDBM_FILE " dbf ")"
+Clears the error state for the database \fIdbf\fR.  This function is
+called implicitly upon entry to any GDBM function that operates on
+\fBGDBM_FILE\fR.
+.sp
+The \fBGDBM_NEED_RECOVERY\fR error cannot be cleared.
+.TP
+.BI "int gdbm_needs_recovery (GDBM_FILE " dbf ")"
+Return \fB1\fR if the database file \fIdbf\fR is in inconsistent state
+and needs recovery.
+.TP
+.BI "const char *gdbm_strerror (gdbm_error " err ")"
+Returns a textual description of the error code \fIerr\fR.
+.TP
+.BI "const char *gdbm_db_strerror (GDBM_FILE " dbf ")"
+Returns a textual description of the recent error in database
+\fIdbf\fR.  This description includes the system \fBerrno\fR value, if
+relevant.
+.SS Closing the database
+It is important that every database file opened is also closed.  This
+is needed to update the reader/writer count on the file.  This is done by:
+.TP
 .BI "int gdbm_close (GDBM_FILE " dbf ");"
-
-The database is used by 3 primary routines.  The first stores data in the
-database.
-
-.BI "int gdbm_store (GDBM_FILE " dbf ", datum " key ", datum " content ", int " flag );
-
-\fIDbf\fR is the pointer returned by \fBgdbm_open\fR.  \fIKey\fR is the
-key data.  \fIContent\fR is the data to be associated with the \fIkey\fR.
-\fIFlag\fR can have one of the following values:
+.SS Database lookups
 .TP
-.B GDBM_INSERT
-Insert only, generate an error if key exists;
+.BI "int gdbm_exists (GDBM_FILE " dbf ", datum " key );
+If the \fIkey\fR is found within the database, the return value 
+will be \fItrue\fR (\fB1\fR).  If nothing appropriate is found, \fIfalse\fR
+(\fB0\fR) is returned and \fBgdbm_errno\fR set to \fBGDBM_NO_ERROR\fR.
+.sp
+On error, returns 0 and sets \fBgdbm_errno\fR.
 .TP
-.B GDBM_REPLACE
-Replace contents if key exists.
-.PP
-If a reader calls \fBgdbm_store\fR, the return value will be  \-1.
-If called with \fBGDBM_INSERT\fR and \fIkey\fR is in the database, the return
-value will be 1.  Otherwise, the return value is 0.
-
-\fINOTICE: If you store data for a key that is already in the data base,
-\fBgdbm\fI replaces the old data with the new data if called with \fBGDBM_REPLACE\fI.
-You do not get two data items for the same key and you do not get an
-error from \fBgdbm_store\fI.
-
-NOTICE: The size in \fBgdbm\fI is not restricted like in \fBdbm\fI or \fBndbm\fI.  Your data
-can be as large as you want.\fR
-
-To search for some data, use:
-
 .BI "datum gdbm_fetch (GDBM_FILE " dbf ", datum " key );
-
 \fIDbf\fR is the pointer returned by \fBgdbm_open\fR.  \fIKey\fR is
 the key data.
-
+.sp
 If the \fIdptr\fR element of the return value is \fBNULL\fR, the
 \fBgdbm_errno\fR variable should be examined.  The value of 
 \fBGDBM_ITEM_NOT_FOUND\fR means no data was found for that \fIkey\fR.
 Other value means an error occurred.
-
+.sp
 Otherwise the return value is a pointer to the found data.
 The storage space for the \fIdptr\fR element is allocated using
-\fBmalloc(3)\fR.  \fBGdbm\fI does not automatically free this data.
+\fBmalloc(3)\fR.  \fBGDBM\fR does not automatically free this data.
 It is the programmer's responsibility to free this storage when it is
 no longer needed.
-
-To search for some data, without retrieving it:
-
-.BI "int gdbm_exists (GDBM_FILE " dbf ", datum " key );
-
-\fIDbf\fR is the pointer returned by \fBgdbm_open\fR.  \fIKey\fR is
-the key data to search for.
-
-If the \fIkey\fR is found within the database, the return value 
-will be true.  If nothing appropriate is found, false is returned.
-This routine is useful for checking for the existence of a record,
-without performing the memory allocation done by \fBgdbm_fetch\fR.
-.PP
-To remove some data from the database:
-
-.BI "int gdbm_delete (GDBM_FILE " dbf ", datum " key );
-
-\fIDbf\fR is the pointer returned by \fBgdbm_open\fR.  \fIKey\fR is the
-key data.
-
-The return value is \-1 if the item is not present or the requester is a reader.
-The return value is 0 if there was a successful delete.
-
-The next two routines allow for accessing all items in the database.  This 
-access is not key sequential, but it is guaranteed to visit every key in
-the database once.  (The order has to do with the hash values.)
-
+.SS Iterating over the database
+The following two routines allow for iterating over all items in the
+database.  Such iteration is not key sequential, but it is
+guaranteed to visit every key in the database exactly once.  (The
+order has to do with the hash values.)
+.TP
 .BI "datum gdbm_firstkey (GDBM_FILE " dbf ");"
-.br
+Returns first key in the database.
+.TP
 .BI "datum gdbm_nextkey (GDBM_FILE " dbf ", datum " key );
-
-\fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is the
-key data.
-
-The return values are both of type \fBdatum\fR.  If the \fIdptr\fR
-element of the return value is \fBNULL\fR, inspect the
-\fBgdbm_errno\fR.  If it is \fBGDBM_ITEM_NOT_FOUND\fR, there is no
-first key or next key.  Otherwise, an error occurred.
-
-Again, notice that \fIdptr\fR points to data allocated by \fBmalloc(3)\fR
-and \fBgdbm\fR will not free it for you. 
-
-These functions were intended to visit the database in read-only algorithms,
-for instance, to validate the database or similar operations.
-
-File `visiting' is based on a `hash table'.  \fIgdbm_delete\fR re-arranges the
-hash table to make sure that any collisions in the table do not leave some item
-`un-findable'.  The original key order is NOT guaranteed to remain unchanged in
-ALL instances.  It is possible that some key will not be visited if a loop like
-the following is executed:
+Given a \fIkey\fR, returns the database key that follows it.  End of
+iteration is marked by returning \fIdatum\fR with \fIdptr\fR field set
+to \fBNULL\fR and setting the \fBgdbm_errno\fR value to
+\fBGDBM_ITEM_NOT_FOUND\fR.
+.PP
+After successful return from both functions, \fIdptr\fR points to data
+allocated by
+.BR malloc (3).
+It is the caller responsibility to free the data when no longer
+needed.
+.PP
+A typical iteration loop looks like:
+.sp
+.nf
+.in +5
+datum key, nextkey, content;
+key = gdbm_firstkey (dbf);
+while (key.dptr)
+  {
+    content = gdbm_fetch (dbf, key);
+    /* Do something with key and/or content */
+    nextkey = gdbm_nextkey (dbf, key);
+    free (key.dptr);
+    key = nextkey;
+  }
+.in
+.fi
+.PP
+These functions are intended to visit the database in read-only
+algorithms.  Avoid any database modifications within the iteration loop.
+File \fIvisiting\fR is based on a hash table.  The \fBgdbm_delete\fR and,
+in most cases, \fBgdbm_store\fR, functions rearrange the hash table to
+make sure that any collisions in the table do not leave some item
+`un-findable'.  Thus, a call to either of these functions changes
+the order in which the keys are ordered.  Therefore, these functions
+should not be used when iterating over all the keys in the database.
+For example, the following loop is wrong: it is possible that some keys
+will not be visited or will be visited twice if it is executed: 
 .sp
 .nf
 .in +5
@@ -315,131 +456,282 @@ while (key.dptr)
   }
 .in
 .fi
+.SS Updating the database
+.TP
+.BI "int gdbm_store (GDBM_FILE " dbf ", datum " key ", datum " content ", int " flag );
+\fIDbf\fR is the pointer returned by \fBgdbm_open\fR.  \fIKey\fR is the
+key data.  \fIContent\fR is the data to be associated with the \fIkey\fR.
+\fIFlag\fR can have one of the following values:
+.RS 4
+.TP
+.B GDBM_INSERT
+Insert only, generate an error if key exists;
+.TP
+.B GDBM_REPLACE
+Replace contents if key exists.
+.RE
+.IP
+The function returns 0 on success and \-1 on failure.  If the key
+already exists in the database and the \fIflag\fR is
+\fBGDBM_INSERT\fR, the function does not modify the database.  It sets
+\fBgdbm_errno\fR to \fBGDBM_CANNOT_REPLACE\fR and returns 1.
+.TP
+.BI "int gdbm_delete (GDBM_FILE " dbf ", datum " key );
+Looks up and deletes the given \fIkey\fR from the database \fIdbf\fR.
+.sp
+The return value is 0 if there was a successful delete or \-1 on
+error.  In the latter case, the \fBgdbm_errno\fR value
+\fBGDBM_ITEM_NOT_FOUND\fR indicates that the key is not present in the
+database.  Other \fBgdbm_errno\fR values indicate failure.
+.SS Recovering structural consistency
+If a function leaves the database in structurally inconsistent state,
+it can be recovered using the \fBgdbm_recover\fR function.
+.TP
+.BI "int gdbm_recover (GDBM_FILE " dbf ", gdbm_recovery * " rcvr ", int " flags ")"
+Check the database file DBF and fix eventual inconsistencies.  The
+\fIrcvr\fR argument can be used both to control the recovery and to
+return additional statistics about the process, as indicated by
+\fIflags\fR.  For a detailed discussion of these arguments and their
+usage, see the \fBGDBM Manual\fR, chapter \fBRecovering structural
+consistency\fR.
+.sp
+You can pass \fBNULL\fR as \fIrcvr\fR and \fB0\fR as \fIflags\fR, if
+no such control is needed.
+.sp
+By default, this function first checks the database for
+inconsistencies and attempts recovery only if some were found.  The
+special \fIflags\fR bit \fBGDBM_RCVR_FORCE\fR instructs
+\fBgdbm_recovery\fR to skip this check and to perform database
+recovery unconditionally.
+.SS Export and import
+\fBGDBM\fR database files can be exported (dumped) to so called \fIflat
+files\fR or imported (loaded) from them.  A flat file contains exactly
+the same data as the original database, but it cannot be used for
+searches or updates.  Its purpose is to keep the data from the
+database for restoring it when the need arrives.  As such, flat files
+are used for backup purposes, and for sending databases over the wire.
 .PP
-The following routine should be used very infrequently.
-  
-.BI "int gdbm_reorganize (GDBM_FILE " dbf ");"
+As of \fBGDBM\fR version 1.21, there are two flat file formats.  The
+\fBASCII\fR file format encodes all data in Base64 and stores
+not only key/data pairs, but also the original database file metadata,
+such as file name, mode and ownership.  Files in this format can be
+sent without additional encapsulation over transmission channels that
+normally allow only ASCII data, such as, e.g. SMTP.  Due to additional
+metadata they allow for restoring an exact copy of the database,
+including file ownership and privileges, which is especially important
+if the database in question contained some security-related data.
+This is the preferred format.
+.PP
+Another flat file format is the \fBbinary\fR format.  It stores only
+key/data pairs and does not keep information about the database file
+itself.  It cannot be used to copy databases between different
+architectures.  The binary format was introduced in \fBGDBM\fR version
+1.9.1 and is retained mainly for backward compatibility.
+.PP
+The following functions are used to export or import \fBGDBM\fR
+database files.
+.TP
+.BI "int gdbm_dump (GDBM_FILE " dbf ", const char *" filename ","
+.PD 0
+.TP
+.ti +15
+.BI "int " format ", int " open_flag ", int " mode ")"
+.PD
+Dumps the database file \fIdbf\fR to the file \fIfilename\fR in
+requested \fIformat\fR.  Allowed values for \fIformat\fR are:
+.BR GDBM_DUMP_FMT_ASCII ,
+to create an ASCII dump file, and
+.BR GDBM_DUMP_FMT_BINARY ,
+to create a binary dump.
 
-If you have had a lot of deletions and would like to shrink the space
-used by the \fBgdbm\fR file, this routine will reorganize the database.
-\fBGdbm\fR will not shorten the length of a \fBgdbm\fR file except by
-using this reorganization.  (Deleted file space will be reused.)
+The value of \fIopen_flag\fR tells \fBgdbm_dump\fR what to do if
+\fIfilename\fR already exists.  If it is \fBGDBM_NEWDB\fR, the
+function will create a new output file, replacing it if it already
+exists.  If its value is \fBGDBM_WRCREAT\fR, the file will be created
+if it does not exist.  If it does exist, \fBgdbm_dump\fR will return
+error.
 
-Unless your database was opened with the \fBGDBM_SYNC\fR flag, \fBgdbm\fR does not
-wait for writes to be flushed to the disk before continuing.
-The following routine can be used to guarantee that the database is
-physically written to the disk file.
+The file mode to use when creating the output file is defined by the
+\fImode\fR parameter.  Its meaning is the same as for
+.BR open (2).
+.TP
+.BI "int gdbm_load (GDBM_FILE *" pdbf ", const char *" filename ","
+.PD 0
+.TP
+.ti +15
+.BI "int " flag ", int " meta_mask ", unsigned long *" errline ")"
+.PD
+Loads data from the dump file \fIfilename\fR into the database pointed
+to by \fIpdbf\fR.  If \fIpdbf\fR is \fBNULL\fR, the function will try
+to create a new database.  On success, the new \fBGDBM_FILE\fR object
+will be stored in the memory location pointed to by \fIpdbf\fR.  If
+the dump file carries no information about the original database file
+name, the function will set \fBgdbm_errno\fR to \fBGDBM_NO_DBNAME\fR
+and return -1, indicating failure.
 
-.BI "int gdbm_sync (GDBM_FILE " dbf ");"
+Otherwise, if \fIpdbf\fR points to an already open \fBGDBM_FILE\fR,
+the function will load data from \fIfilename\fR into that database.
 
+The \fIflag\fR parameter controls the function behavior if a key
+from the dump file already exists in the database.  See the
+\fBgdbm_store\fR function for its possible values.
+
+The \fImeta_mask\fR parameter can be used to disable restoring certain
+bits of file's meta-data from the information in the input dump file.
+It is a binary OR of zero or more of the following:
+.RS +4
+.TP
+.B GDBM_META_MASK_MODE
+Do not restore file mode.
+.TP
+.B GDBM_META_MASK_OWNER
+Do not restore file owner.
+.RE
+.SS Other functions
+.TP  
+.BI "int gdbm_reorganize (GDBM_FILE " dbf ");"
+If you have had a lot of deletions and would like to shrink the space
+used by the \fBGDBM\fR file, this routine will reorganize the
+database.
+.TP
+.BI "int gdbm_sync (GDBM_FILE " dbf ");"
+Synchronizes the changes in \fIdbf\fR with its disk file.
+.sp
 It will not return until the disk file state is synchronized with the
 in-memory state of the database.
+.TP
+.BI "int gdbm_setopt (GDBM_FILE " dbf ", int " option ", void *" value ", int " size );
+Query or change some parameter of an already opened database.  The
+\fIoption\fR argument defines what parameter to set or retrieve.  If
+the \fIset\fR operation is requested, \fIvalue\fR points to the new
+value.  Its actual data type depends on \fIoption\fR.  If the
+\fIget\fR operation is requested, \fIvalue\fR points to a memory
+region where to store the return value.  In both cases, \fIsize\fR
+contains the actual size of the memory pointed to by \fIvalue\fR.
+.sp
+Possible values of \fIoption\fR are:
+.RS +4
+.TP
+.B GDBM_SETCACHESIZE
+.TQ
+.B GDBM_CACHESIZE
+Set the size of the internal bucket cache.  The \fIvalue\fR should
+point to a \fBsize_t\fR holding the desired cache size, or the
+constant \fBGDBM_CACHE_AUTO\fR, to select the best cache size
+automatically.
 
-To convert a \fBgdbm\fR error code into English text, use this routine:
-
-.BI "const char *gdbm_strerror (gdbm_error " errno );
-
-\fBGdbm\fR now supports the ability to set certain options on an
-already open database.
-
-.BI "int gdbm_setopt (GDBM_FILE " dbf ", int " option ", int " value ", int " size );
+By default, a newly open database is configured to adapt the cache
+size to the number of index buckets in the database file.  This
+provides for the best performance.
 
-Where \fIdbf\fR is the return value from a previous call to \fBgdbm_open\fR,
-and \fIoption\fR specifies which option to set.  The valid options are
-currently:
+Use this option if you wish to limit the memory usage at the expense
+of performance.  If you chose to do so, please bear in mind that cache
+becomes effective when its size is greater then 2/3 of the number of
+index bucket counts in the database.  The best performance results are
+achieved when cache size equals the number of buckets.
 .TP
-.B GDBM_CACHESIZE
-Set the size of the internal bucket cache.  By default, the cache size
-is selected to provide for the optimal performance.  Use this option,
-if you wish to limit the memory usage at the expense of performance.
-.sp
-Use the
-.B GDBM_CACHE_AUTO
-constant to return to the default.
+.B GDBM_GETCACHESIZE
+Return the size of the internal bucket cache.  The \fIvalue\fR should
+point to a \fBsize_t\fR variable, where the size will be stored.
+.TP
+.B GDBM_GETFLAGS
+Return the flags describing current state of the database.  The
+\fIvalue\fR should point to an \fBint\fR variable where to store the
+flags.  On success, its value will be similar to the flags used when
+opening the database, except that it will reflect the current state
+(which may have been altered by another calls to \fBgdbm_setopt\fR).
 .TP
 .B GDBM_FASTMODE
- Set \fBfast mode\fR to either on or off.  This allows \fBfast mode\fR to
-be toggled on an already open and active database. \fIvalue\fR (see below)
-should be set to either TRUE or FALSE.  \fIThis option is now obsolete.\fR
+Enable or disable the \fIfast writes mode\fR, similar to the
+\fBGDBM_FAST\fR option to \fBgdbm_open\fR.
+
+This option is retained for compatibility with previous versions of
+\fBGDBM\fR.
 .TP
+.B GDBM_SETSYNCMODE
+.TQ
 .B GDBM_SYNCMODE
-Turn on or off file system synchronization operations.  This setting defaults
-to off; \fIvalue\fR (see below) should be set to either TRUE or FALSE.
+Turn on or off immediate disk synchronization after updates.  The
+\fIvalue\fR should point to an integer: 1 to turn synchronization on,
+and 0 to turn it off.
+
+\fBNOTE\fR: setting this option entails severe performance degradation
+and does not necessarily ensure that the resulting database state is
+consistent, therefore we discourage its use.  For a discussion of how
+to ensure database consistency with minimal performance overhead, see
+.B CRASH TOLERANCE
+below.
+.TP
+.B GDBM_GETSYNCMODE
+Return the current synchronization status.  The \fIvalue\fR should
+point to an \fBint\fR where the status will be stored.
 .TP
+.B GDBM_SETCENTFREE
+.TQ
 .B GDBM_CENTFREE
-Set \fBcentral free block pool\fR to either on or off.
-The default is off, which is how previous versions of \fBGdbm\fR
-handled free blocks. If set, this option causes all subsequent free
-blocks to be placed in the \fBglobal\fR pool, allowing (in thoery)
-more file space to be reused more quickly. \fIvalue\fR (see below) should
-be set to either TRUE or FALSE.
-\fINOTICE: This feature is still under study.\fR
+Enable or disable central free block pool.  The default is off,
+which is how previous versions of \fBGDBM\fR handled free blocks.  If
+set, this option causes all subsequent free blocks to be placed in the
+\fIglobal\fR pool, allowing (in theory) more file space to be reused
+more quickly.  The \fIvalue\fR should point to an integer: \fBTRUE\fR to
+turn central block pool on, and \fBFALSE\fR to turn it off.
+
+The \fBGDBM_CENTFREE\fR alias is provided for compatibility with
+earlier versions.
 .TP
+.B GDBM_SETCOALESCEBLKS
+.TQ
 .B GDBM_COALESCEBLKS
-Set \fBfree block merging\fR to either on or off.
-The default is off, which is how previous versions of \fBGdbm\fR
-handled free blocks. If set, this option causes adjacent free blocks
-to be merged.  This can become a CPU expensive process with time, though,
-especially if used in conjunction with \fBGDBM_CENTFREE\fR. \fIvalue\fR
-(see below) should be set to either TRUE or FALSE.
-\fINOTICE: This feature is still under study.\fR
-.PP
-\fIvalue\fR is the value to set \fIoption\fR to, specified as an integer
-pointer.  \fIsize\fR is the size of the data pointed to by \fIvalue\fR.
-The return value will be \-1 upon failure, or 0 upon success.  The global
-variable \fIgdbm_errno\fR will be set upon failure.
-
-For instance, to set a database to use a cache of 10, after opening it
-with \fBgdbm_open\fR, but prior to accessing it in any way, the following
-code could be used:
-.sp
-.nf
-.in +5
-int value = 10;
-  
-ret = gdbm_setopt( dbf, GDBM_CACHESIZE, &value, sizeof(int));
-.in
-.fi
-.PP
-If the database was opened with the \fBGDBM_NOLOCK\fR flag, the user may
-wish to perform their own file locking on the database file in order to
-prevent multiple writers operating on the same file simultaneously.
-
-In order to support this, the \fIgdbm_fdesc\fR routine is provided.
-
+Set free block merging to either on or off.  The default is off, which
+is how previous versions of \fBGDBM\fR handled free blocks.  If set,
+this option causes adjacent free blocks to be merged.  This can become
+a CPU expensive process with time, though, especially if used in
+conjunction with \fBGDBM_CENTFREE\fR.  The \fIvalue\fR should point 
+to an integer: \fBTRUE\fR to turn free block merging on, and \fBFALSE\fR to
+turn it off.
+.TP
+.B GDBM_GETCOALESCEBLKS
+Return the current status of free block merging.  The \fIvalue\fR should
+point to an \fBint\fR where the status will be stored.
+.TP
+.B GDBM_SETMAXMAPSIZE
+Sets maximum size of a memory mapped region.  The \fIvalue\fR should
+point to a value of type \fBsize_t\fR, \fBunsigned long\fR or
+\fBunsigned\fR.  The actual value is rounded to the nearest page
+boundary (the page size is obtained from \fBsysconf(_SC_PAGESIZE)\fR).
+.TP
+.B GDBM_GETMAXMAPSIZE
+Return the maximum size of a memory mapped region.  The \fIvalue\fR should
+point to a value of type \fBsize_t\fR where to return the data.
+.TP
+.B GDBM_SETMMAP
+Enable or disable memory mapping mode.  The \fIvalue\fR should point
+to an integer: \fBTRUE\fR to enable memory mapping or \fBFALSE\fR to
+disable it.
+.TP
+.B GDBM_GETMMAP
+Check whether memory mapping is enabled.  The \fIvalue\fR should point
+to an integer where to return the status.
+.TP
+.B GDBM_GETDBNAME
+Return the name of the database disk file.  The \fIvalue\fR should
+point to a variable of type \fBchar**\fR.  A pointer to the newly
+allocated copy of the file name will be placed there.  The caller is
+responsible for freeing this memory when no longer needed.
+.TP
+.B GDBM_GETBLOCKSIZE
+Return the block size in bytes.  The \fIvalue\fR should point to \fBint\fR.
+.RE
+.TP
 .BI "int gdbm_fdesc (GDBM_FILE " dbf );
-
-Where \fIdbf\fR is the return value from a previous call to \fBgdbm_open\fR.
-The return value will be the file descriptor of the database.
-
-The following two external variables may be useful:
-
-\fIgdbm_errno\fR is the variable that contains more information about
-gdbm errors.  (gdbm.h has the definitions of the error values and
-defines gdbm_errno as an external variable.)
-
-\fIgdbm_version\fR is the string containing the version information.
-
-There are a few more things of interest.  First, \fBgdbm\fR files are
-not "sparse".  You can copy them with the UNIX \fBcp(1)\fR command and
-they will not expand in the copying process.  Also, there is a
-compatibility mode for use with programs that already use UNIX
-\fBdbm\fR.  In this compatibility mode, no \fRgdbm\fR file pointer is
-required by the programmer, and only one file may be opened at a time.
-All users in compatibility mode are assumed to be writers.  If the
-\fBgdbm\fR file is a read only, it will fail as a writer, but will
-also try to open it as a reader.  All returned pointers in datum
-structures point to data that \fBgdbm\fR WILL free.  They should be
-treated as static pointers (as standard UNIX \fBdbm\fR does).
-
+Returns the file descriptor of the database \fIdbf\fR.
 .SH CRASH TOLERANCE
-
 By default \fBGNU dbm\fR does not protect the integrity of its
 databases from corruption or destruction due to failures such as
 power outages, operating system kernel panics, or application process
 crashes.  Such failures could damage or destroy the underlying
 database.
-
+.PP
 Starting with release 1.21 \fBGNU dbm\fR includes a mechanism that,
 if used correctly, enables post-crash recovery to a consistent state
 of the underlying database.  This mechanism requires OS and
@@ -450,6 +742,354 @@ that explicitly request it.  For details, see the chapter
 .B "Crash Tolerance"
 in the
 .BR "GDBM manual" .
+.SH GLOBAL VARIABLES
+.TP
+.B gdbm_error gdbm_errno
+This variable contains code of the most recent error that occurred.
+Note, that it is not C variable in the proper sense: you can use its
+value, assign any value to it, but taking its address will result in
+syntax error.  It is a per-thread memory location.
+.TP
+.B const char *gdbm_version
+A string containing the library version number and build date.
+.TP
+.B int const gdbm_version_number[3]
+This variable contains library version numbers: major, minor, and
+patchlevel.
+.SH VERSIONING
+The version information is kept in two places.  The version of the
+library is kept in the \fBgdbm_version_number\fR variable, described
+above.  Additionally, the header file \fBgdbm.h\fR defines the
+following macros:
+.TP
+.B GDBM_VERSION_MAJOR
+Major version number.
+.TP
+.B GDBM_VERSION_MINOR
+Minor version number.
+.TP
+.B GDBM_VERSION_PATCH
+Patchlevel number.  \fB0\fR means no patchlevel.
+.PP
+You can use this to compare whether your header file corresponds to
+the library the program is linked with.
+.PP
+The following function can be used to compare two version numbers:
+.TP
+.BI "int gdbm_version_cmp (int const " a "[3], int const " b "[3])"
+Compare two version numbers formatted as \fBgdbm_version_number\fR.
+Return negative number if \fBa\fR is older than \fBb\fR, positive
+number if \fBa\fR is newer than \fBb\fR, and 0 if they are equal.
+.SH ERROR CODES
+.TP
+.B GDBM_NO_ERROR
+No error occurred.
+.TP
+.B GDBM_MALLOC_ERROR
+Memory allocation failed.
+.TP
+.B GDBM_BLOCK_SIZE_ERROR
+This error is set by the \fBgdbm_open\fR function, if
+the value of its \fIblock_size\fR argument is incorrect and the
+\fBGDBM_BSEXACT\fR flag is set.
+.TP
+.B GDBM_FILE_OPEN_ERROR
+The library was not able to open a disk file.  This can be set by
+\fBgdbm_open\fR, \fBgdbm_fd_open\fR, \fBgdbm_dump\fR and
+\fBgdbm_load\fR functions.
+.sp
+Inspect the value of the system \fBerrno\fR variable to get more
+detailed diagnostics.
+.TP
+.B GDBM_FILE_WRITE_ERROR
+Writing to a disk file failed.  This can be set by
+\fBgdbm_open\fR, \fBgdbm_fd_open\fR, \fBgdbm_dump\fR and
+\fBgdbm_load\fR functions.
+.sp
+Inspect the value of the system \fBerrno\fR variable to get more
+detailed diagnostics.
+.TP
+.B GDBM_FILE_SEEK_ERROR
+Positioning in a disk file failed.  This can be set by
+\fBgdbm_open\fR function.
+.sp
+Inspect the value of the system \fBerrno\fR variable to get a more
+detailed diagnostics.
+.TP
+.B GDBM_FILE_READ_ERROR
+Reading from a disk file failed.  This can be set by
+\fBgdbm_open\fR, \fBgdbm_dump\fR and \fBgdbm_load\fR functions.
+.sp
+Inspect the value of the system \fBerrno\fR variable to get a more
+detailed diagnostics.
+.TP
+.B GDBM_BAD_MAGIC_NUMBER
+The file given as argument to \fBgdbm_open\fR function is not a valid
+\fBgdbm\fR file: it has a wrong magic number.
+.TP
+.B GDBM_EMPTY_DATABASE
+The file given as argument to \fBgdbm_open\fR function is not a valid
+\fBgdbm\fR file: it has zero length.  This error is returned unless
+the \fIflags\fR argument has \fBGDBM_NEWDB\fR bit set.
+.TP
+.B GDBM_CANT_BE_READER
+This error code is set by the \fBgdbm_open\fR function if it is not
+able to lock file when called in \fBGDBM_READER\fR mode.
+.TP
+.B GDBM_CANT_BE_WRITER
+This error code is set by the \fBgdbm_open\fR function if it is not
+able to lock file when called in writer mode.
+.TP
+.B GDBM_READER_CANT_DELETE
+Set by the \fBgdbm_delete\fR, if it attempted to operate on a database
+that is open in read-only mode.
+.TP
+.B GDBM_READER_CANT_STORE
+Set by the \fBgdbm_store\fR if it attempted to operate on a database
+that is open in read-only mode.
+.TP
+.B GDBM_READER_CANT_REORGANIZE
+Set by the \fBgdbm_reorganize\fR if it attempted to operate on a
+database that is open in read-only mode.
+.TP
+.B GDBM_ITEM_NOT_FOUND
+Requested item was not found.  This error is set by \fBgdbm_delete\fR
+and \fBgdbm_fetch\fR when the requested key value is not found in the
+database.
+.TP
+.B GDBM_REORGANIZE_FAILED
+The \fBgdbm_reorganize\fR function is not able to create a temporary
+database.
+.TP
+.B GDBM_CANNOT_REPLACE
+Cannot replace existing item.  This error is set by the
+\fBgdbm_store\fR if the requested key value is found in the 
+database and the \fIflag\fR parameter is not \fBGDBM_REPLACE\fR.
+.TP
+.B GDBM_MALFORMED_DATA
+Input data was malformed in some way.  When returned by
+\fBgdbm_load\fR, this means that the input file was not a valid
+\fBgdbm\fR dump file.  When returned by \fBgdbm_store\fR, this means
+that either \fIkey\fR or \fIcontent\fR parameter had its \fBdptr\fR
+field set to \fBNULL\fR. 
+.sp
+The \fBGDBM_ILLEGAL_DATA\fR is an alias for this error code,
+maintained for backward compatibility.
+.TP
+.B GDBM_OPT_ALREADY_SET
+Requested option can be set only once and was already set.  As of
+version 1.21, this error code is no longer used.  In prior
+versions it could have been returned by the \fBgdbm_setopt\fR
+function when setting the \fBGDBM_CACHESIZE\fR value.
+.TP
+.B GDBM_OPT_BADVAL
+The \fIoption\fR argument is not valid or the \fIvalue\fR argument
+points to an invalid value in a call to \fBgdbm_setopt\fR function.
+.sp
+\fBGDBM_OPT_ILLEGAL\fR is an alias for this error code, maintained
+for backward compatibility.  Modern applications should not use it.
+.TP
+.B GDBM_BYTE_SWAPPED
+The \fBgdbm_open\fR function attempts to open a database which is
+created on a machine with different byte ordering.
+.TP
+.B GDBM_BAD_FILE_OFFSET
+The \fBgdbm_open\fR function sets this error code if the file it tries
+to open has a wrong magic number.
+.TP
+.B GDBM_BAD_OPEN_FLAGS
+Set by the \fBgdbm_dump\fR function if supplied an invalid
+\fIflags\fR argument.
+.TP
+.B GDBM_FILE_STAT_ERROR
+Getting information about a disk file failed.  The system \fBerrno\fR
+will give more details about the error.
+.sp
+This error can be set by the following functions: \fBgdbm_open\fR,
+\fBgdbm_reorganize\fR.
+.TP
+.B GDBM_FILE_EOF
+End of file was encountered where more data was expected to be
+present.  This error can occur when fetching data from the database
+and usually means that the database is truncated or otherwise corrupted.
+.sp
+This error can be set by any GDBM function that does I/O.  Some of
+these functions are: \fBgdbm_delete\fR, \fBgdbm_exists\fR,
+\fBgdbm_fetch\fR, \fBgdbm_export\fR, \fBgdbm_import\fR,
+\fBgdbm_reorganize\fR, \fBgdbm_firstkey\fR, \fBgdbm_nextkey\fR,
+\fBgdbm_store\fR.
+.TP
+.B GDBM_NO_DBNAME
+Output database name is not specified.  This error code is set by
+\fBgdbm_load\fR if the first argument points to \fBNULL\fR and the
+input file does not specify the database name.
+.TP
+.B GDBM_ERR_FILE_OWNER
+This error code is set by \fBgdbm_load\fR if it is unable to restore
+the database file owner.  It is a mild error condition, meaning that
+the data have been restored successfully, only changing the target file
+owner failed.  Inspect the system \fBerrno\fR variable to get a more
+detailed diagnostics.
+.TP
+.B GDBM_ERR_FILE_MODE
+This error code is set by \fBgdbm_load\fR if it is unable to restore
+database file mode.  It is a mild error condition, meaning that the data
+have been restored successfully, only changing the target file owner
+failed.  Inspect the system \fBerrno\fR variable to get a more
+detailed diagnostics.
+.TP
+.B GDBM_NEED_RECOVERY
+Database is in inconsistent state and needs recovery.  Call
+\fBgdbm_recover\fR if you get this error.
+.TP
+.B GDBM_BACKUP_FAILED
+The GDBM engine is unable to create backup copy of the file.
+.TP
+.B GDBM_DIR_OVERFLOW
+Bucket directory would overflow the size limit during an attempt to split
+hash bucket.  This error can occur while storing a new key.
+.TP
+.B GDBM_BAD_BUCKET
+Invalid index bucket is encountered in the database.  Database
+recovery is needed.
+.TP
+.B GDBM_BAD_HEADER
+This error is set by \fBgdbm_open\fR and \fBgdbm_fd_open\fR, if the
+first block read from the database file does not contain a valid GDBM
+header.
+.TP
+.B GDBM_BAD_AVAIL
+The available space stack is invalid.  This error can be set by
+\fBgdbm_open\fR and \fBgdbm_fd_open\fR, if the extended database
+verification was requested (\fBGDBM_XVERIFY\fR).  It is also set
+by the \fBgdbm_avail_verify\fR function.
+.sp
+The database needs recovery.
+.TP
+.B GDBM_BAD_HASH_TABLE
+Hash table in a bucket is invalid.  This error can be set by the
+following functions: \fBgdbm_delete\fR, \fBgdbm_exists\fR,
+\fBgdbm_fetch\fR, \fBgdbm_firstkey\fR, \fBgdbm_nextkey\fR, and
+\fBgdbm_store\fR.
+.sp
+The database needs recovery.
+.TP
+.B GDBM_BAD_DIR_ENTRY
+Bad directory entry found in the bucket.  The database recovery is
+needed.
+.TP
+.B GDBM_FILE_CLOSE_ERROR
+The \fBgdbm_close\fR function was unable to close the database file
+descriptor.  The system \fBerrno\fR variable contains the
+corresponding error code.
+.TP
+.B GDBM_FILE_SYNC_ERROR
+Cached content couldn't be synchronized to disk.  Examine the
+\fBerrno\fR variable to get more info,
+.sp
+Database recovery is needed.
+.TP
+.B GDBM_FILE_TRUNCATE_ERROR
+File cannot be truncated.  Examine the \fBerrno\fR variable to get
+more info.
+.sp
+This error is set by \fBgdbm_open\fR and \fBgdbm_fd_open\fR when
+called with the \fBGDBM_NEWDB\fR flag.
+.TP
+.B GDBM_BUCKET_CACHE_CORRUPTED
+The bucket cache structure is corrupted.  Database recovery is needed.
+.TP
+.B GDBM_BAD_HASH_ENTRY
+This error is set during sequential access (@pxref{Sequential}), if
+the next hash table entry does not contain the expected key.  This
+means that the bucket is malformed or corrupted and the database needs
+recovery.
+.TP
+.B GDBM_ERR_SNAPSHOT_CLONE
+Set by the \fBgdbm_failure_atomic\fR function if it was unable to
+clone the database file into a snapshot.  Inspect the system
+\fBerrno\fR variable for the underlying cause of the error.  If
+\fBerrno\fR is \fBEINVAL\fR or \fBENOSYS\fR, crash tolerance
+settings will be removed from the database.
+.TP
+.B GDBM_ERR_REALPATH
+Set by the \fBgdbm_failure_atomic\fR function if the call to
+\fBrealpath\fR function failed.  \fBrealpath\fR is used to
+determine actual path names of the snapshot files.  Examine the system
+\fBerrno\fR variable for details.
+.TP
+.B GDBM_ERR_USAGE
+Function usage error.  That includes invalid argument values, and the
+like.
+.SH DBM COMPATIBILITY ROUTINES
+\fBGDBM\fR includes a compatibility library \fBlibgdbm_compat\fR, for
+use with programs that expect traditional UNIX \fBdbm\fR or
+\fBndbm\fR interfaces, such as, e.g. \fBSendmail\fR.  The library is
+optional and thus may be absent in some binary distributions.
+.PP
+As the detailed discussion of the compatibility API is beyond the scope
+of this document, below we provide only a short reference.  For
+details, see the \fBGDBM Manual\fR, chapter \fBCompatibility with
+standard dbm and ndbm\fR.
+.SS DBM compatibility routines
+In \fBdbm\fR compatibility mode only one file may be opened at a time.
+All users are assumed to be writers.  If the database file is read
+only, it will fail as a writer, but will be opened as a reader.  All
+returned pointers in datum structures point to data that the
+compatibility library \fBwill free\fR.  They should be
+treated as static pointers (as standard UNIX \fBdbm\fR does).
+.PP
+The following interfaces are provided:
+.PP
+.B #include <dbm.h>
+.sp
+.BI "int dbminit (const char *" name ");"
+.br
+.BI "int store (datum " key ", datum " content );
+.br
+.BI "datum fetch (datum " key );
+.br
+.BI "int delete (datum " key );
+.br
+.BI "datum firstkey (void);"
+.br
+.BI "datum nextkey (datum " key );
+.br
+.BI "int dbmclose (void);"
+.SS NDBM Compatibility routines:
+In this mode, multiple databases can be opened.  Each database is
+identified by a handle of type \fBDBM *\fR.  As in the original
+\fBNDBM\fR, all returned pointers in datum structures point to data
+that will be freed by the compatibility library.  They should be
+treated as static pointers.
+.PP
+The following interfaces are provided:
+.PP
+.B #include <ndbm.h>
+.sp
+.BI "DBM *dbm_open (const char *" name ", int " flags ", int " mode );
+.br
+.BI "void dbm_close (DBM *" file );
+.br
+.BI "datum dbm_fetch (DBM *" file ", datum " key );
+.br
+.BI "int dbm_store (DBM *" file ", datum " key ", datum " content ", int " flags );
+.br
+.BI "int dbm_delete (DBM *" file ", datum " key );
+.br
+.BI "datum dbm_firstkey (DBM *" file );
+.br
+.BI "datum dbm_nextkey (DBM *" file ", datum " key );
+.br
+.BI "int dbm_error (DBM *" file );
+.br
+.BI "int dbm_clearerr (DBM *" file );
+.br
+.BI "int dbm_pagfno (DBM *" file );
+.br
+.BI "int dbm_dirfno (DBM *" file );
+.br
+.BI "int dbm_rdonly (DBM *" file );
 .SH LINKING
 This library is accessed by specifying \fI\-lgdbm\fR as the last
 parameter to the compile line, e.g.:
diff --git a/doc/gdbm.texi b/doc/gdbm.texi
index 0f739e1..7ca5549 100644
--- a/doc/gdbm.texi
+++ b/doc/gdbm.texi
@@ -2366,8 +2366,8 @@ the value of its @var{block_size} argument is incorrect and the
 
 @defvr {Error Code} GDBM_FILE_OPEN_ERROR
 The library was not able to open a disk file.  This can be set by
-@code{gdbm_open} (@pxref{Open}), @code{gdbm_export} and
-@code{gdbm_import} functions (@pxref{Flat files}).
+@code{gdbm_open} (@pxref{Open}), @code{gdbm_dump} (@code{gdbm_export}) and
+@code{gdbm_load} (@code{gdbm_import}) functions (@pxref{Flat files}).
 
 Inspect the value of the system @code{errno} variable to get more
 detailed diagnostics.
@@ -2375,8 +2375,8 @@ detailed diagnostics.
 
 @defvr {Error Code} GDBM_FILE_WRITE_ERROR
 Writing to a disk file failed.  This can be set by
-@code{gdbm_open} (@pxref{Open}), @code{gdbm_export} and
-@code{gdbm_import} functions.
+@code{gdbm_open} (@pxref{Open}), @code{gdbm_dump} (@code{gdbm_export}) and
+@code{gdbm_load} (@code{gdbm_import}) functions.
 
 Inspect the value of the system @code{errno} variable to get more
 detailed diagnostics.
@@ -2392,8 +2392,8 @@ detailed diagnostics.
 
 @defvr {Error Code} GDBM_FILE_READ_ERROR
 Reading from a disk file failed.  This can be set by
-@code{gdbm_open} (@pxref{Open}), @code{gdbm_export} and
-@code{gdbm_import} functions.
+@code{gdbm_open} (@pxref{Open}), @code{gdbm_dump} (@code{gdbm_export}) and
+@code{gdbm_load} (@code{gdbm_import}) functions.
 
 Inspect the value of the system @code{errno} variable to get a more
 detailed diagnostics.
@@ -2498,8 +2498,8 @@ the file it tries to open has a wrong magic number.
 @end defvr
 
 @defvr {Error Code} GDBM_BAD_OPEN_FLAGS
-Set by the @code{gdbm_export} function if supplied an invalid
-@var{flags} argument.  @xref{Flat files}.
+Set by the @code{gdbm_dump} (@code{gdbm_export}) function if supplied
+an invalid @var{flags} argument.  @xref{Flat files}.
 @end defvr
 
 @defvr {Error Code} GDBM_FILE_STAT_ERROR
@@ -2517,9 +2517,9 @@ and usually means that the database is truncated or otherwise corrupted.
 
 This error can be set by any GDBM function that does I/O.  Some of
 these functions are: @code{gdbm_delete}, @code{gdbm_exists},
-@code{gdbm_fetch}, @code{gdbm_export}, @code{gdbm_import},
-@code{gdbm_reorganize}, @code{gdbm_firstkey}, @code{gdbm_nextkey},
-@code{gdbm_store}.
+@code{gdbm_fetch}, @code{gdbm_dump}, @code{gdbm_load},
+@code{gdbm_export}, @code{gdbm_import}, @code{gdbm_reorganize},
+@code{gdbm_firstkey}, @code{gdbm_nextkey}, @code{gdbm_store}.
 @end defvr
 
 @defvr {Error Code} GDBM_NO_DBNAME
@@ -2610,7 +2610,7 @@ Database recovery is needed (@pxref{Recovery}).
 
 @defvr {Error Code} GDBM_FILE_TRUNCATE_ERROR
 File cannot be truncated.  Examine the @code{errno} variable to get
-more info,
+more info.
 
 This error is set by @code{gdbm_open} and @code{gdbm_fd_open} when
 called with the @code{GDBM_NEWDB} flag.
diff --git a/git2chg.awk b/git2chg.awk
deleted file mode 100644
index 0fe263f..0000000
--- a/git2chg.awk
+++ /dev/null
@@ -1,75 +0,0 @@
-# This file is part of grecs
-# Copyright (C) 2007-2021 Sergey Poznyakoff
-#
-# Grecs is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation; either version 3, or (at your option)
-# any later version.
-#
-# Grecs is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Grecs.  If not, see <http://www.gnu.org/licenses/>.
-
-BEGIN {
-  if (since)
-    split(since,since_a,"-")
-}
-
-function timeok(t,   a) {
-	if (!since)
-		return 1
-	split(t,a,"-")
-	if (a[1] < since_a[1])
-		return 0
-	if (a[1] > since_a[1])
-		return 1
-	if (a[2] < since_a[2])
-		return 0
-	if (a[2] > since_a[2])
-		return 1
-	return a[3] > since_a[3]
-}
-      
-/^[0-9]+ .* +<[^>]+>/ {
-	s = strftime("%F", $1)
-	if (!timeok(s))
-	  exit
-	sub(/^[0-9]+ +/,"")
-	if (s == datestr && author == $0)
-		next
-	datestr = s
-	author = $0
-	if (runlen) { runlen = 0; print "" }
-	printf("%s  %s\n", datestr, author)
-	next
-}
-/^Signed-off-by:/ { next }
-/^<unknown>$/ { next }
-NF==0 {
-	runlen++
-	next
-}
-{ if (runlen) { runlen = 0; print "" }
-  print "\t" $0 }
-
-END {
-	if (append) {
-		print ""
-		while ((getline < append) > 0) {
-			if (match($0, /^Local *Variables:/))
-				break
-			print
-		}
-	}
-	print "\f"
-	# Make sure Emacs won't recognize this line:
-	print "Local", "Variables:"
-	print "mode: change-log"
-	print "version-control: never"
-	print "buffer-read-only: t"
-	print "End:"
-}