Revise the GDBM Manual

2 files changed, 229 insertions, 189 deletions

diff --git a/doc/gdbm.3 b/doc/gdbm.3
index 2ee817b..612795c 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 "October 17, 2021" "GDBM" "GDBM User Reference"
+.TH GDBM 3 "October 18, 2021" "GDBM" "GDBM User Reference"
 .SH NAME
 GDBM \- The GNU database manager.  Includes \fBdbm\fR and \fBndbm\fR
 compatibility.
@@ -254,6 +254,7 @@ 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
diff --git a/doc/gdbm.texi b/doc/gdbm.texi
index 7ca5549..ce038ed 100644
--- a/doc/gdbm.texi
+++ b/doc/gdbm.texi
@@ -84,11 +84,11 @@ Documentation License.''
 @node Top
 @top The GNU database manager
 
-GNU @command{dbm} is a library of functions implementing a hashed database
-on a disk file.  This manual documents GNU @command{dbm} Version
-@value{VERSION} (@code{gdbm}).  The software was originally written by
-Philip A.@: Nelson.  This document was originally written by Pierre
-Gaumond from texts written by Phil.
+GNU @command{dbm} (@command{GDBM}) is a library of functions
+implementing a hashed database on a disk file.  This manual documents
+GNU @command{dbm} Version @value{VERSION}.  The software was
+originally written by Philip A.@: Nelson.  This document was
+originally written by Pierre Gaumond from texts written by Phil.
 @end ifnottex
 
 @menu
@@ -116,7 +116,7 @@ Functions:
 * Locking::                    File locking.
 * Variables::                  Useful global variables.
 * Additional functions::       Functions for verifying internal structures.
-* Error codes::                Error codes returned by @code{gdbm} calls.
+* Error codes::                Error codes returned by GDBM calls.
 * Compatibility::              Compatibility with UNIX dbm and ndbm.
 
 Programs
@@ -166,51 +166,51 @@ gdbmtool interactive mode
 @chapter Copying Conditions
 This library is @dfn{free}; this means that everyone is free to use
 it and free to redistribute it on a free basis.  GNU @command{dbm}
-(@code{gdbm}) is not in the public domain; it is copyrighted and there
+(@command{GDBM}) is not in the public domain; it is copyrighted and there
 are restrictions on its distribution, but these restrictions are
 designed to permit everything that a good cooperating citizen would want
 to do.  What is not allowed is to try to prevent others from further
-sharing any version of @code{gdbm} that they might get from
+sharing any version of @command{GDBM} that they might get from
 you.
 
   Specifically, we want to make sure that you have the right to give
-away copies @code{gdbm}, that you receive
+away copies of @command{GDBM}, that you receive
 source code or else can get it if you want it, that you can change these
 functions or use pieces of them in new free programs, and that you know
 you can do these things.
 
   To make sure that everyone has such rights, we have to forbid you to
 deprive anyone else of these rights.  For example, if you distribute
-copies @code{gdbm}, you must give the recipients all
+copies of @command{GDBM}, you must give the recipients all
 the rights that you have.  You must make sure that they, too, receive or
 can get the source code.  And you must tell them their rights.
 
   Also, for our own protection, we must make certain that everyone finds
-out that there is no warranty for anything in the @code{gdbm} distribution.
+out that there is no warranty for anything in the @command{GDBM} distribution.
 If these functions are modified by someone else and passed on, we want
 their recipients to know that what they have is not what we distributed,
 so that any problems introduced by others will not reflect on our
 reputation.
 
-@code{Gdbm} is currently distributed under the terms of the GNU General
+@command{GDBM} is currently distributed under the terms of the GNU General
 Public License, Version 3.  (@emph{NOT} under the GNU General Library
 Public License.)  A copy the GNU General Public License is included with
-the distribution of @code{gdbm}.
+the distribution of @command{GDBM}.
 
 @node Intro
 @chapter Introduction to GNU @command{dbm}
 
-GNU @command{dbm} (@code{gdbm}) is a library of database functions that use
-extensible hashing and works similar to the standard UNIX @command{dbm}
+GNU @command{dbm} (@command{GDBM}) is a library of database functions that use
+extensible hashing and work similar to the standard UNIX @command{dbm}
 functions.  These routines are provided to a programmer needing to
-create and manipulate a hashed database. (@code{gdbm} is @emph{NOT} a
+create and manipulate a hashed database. (@command{GDBM} is @emph{NOT} a
 complete database package for an end user.)
 
 @tpindex datum
-The basic use of @code{gdbm} is to store key/data pairs in a data file.
+The basic use of @command{GDBM} is to store key/data pairs in a data file.
 Each key must be unique and each key is paired with only one data item.
 The keys can not be directly accessed in sorted order.  The basic unit
-of data in @code{gdbm} is the structure:
+of data in @command{GDBM} is the structure:
 
 @example
 typedef struct
@@ -223,30 +223,34 @@ typedef struct
 This structure allows for arbitrary sized keys and data items.  In
 particular, zero-length keys or data (@code{dsize = 0}) are allowed.
 However, the @code{dptr} field is required to point to a valid memory
-location.  In other words, @code{dptr} cannot be NULL.
-
-The key/data pairs are stored in a @code{gdbm} disk file, called a
-@dfn{gdbm database}.  An application must open a @code{gdbm} database
-to be able manipulate the keys and data contained in the database.
-@code{gdbm} allows an application to have multiple databases open at the
-same time.  When an application opens a @code{gdbm} database, it is
-designated as a @code{reader} or a @code{writer}.  A @code{gdbm}
+location.  In other words, @code{dptr} cannot be NULL.  Note also that
+its type is @code{char *} for purely historic reasons.  You can use
+any C data type (either scalar or aggregate) both as for key and for
+data.
+
+The key/data pairs are stored in a @command{GDBM} disk file, called a
+@dfn{gdbm database}.  An application must open a @command{GDBM} database
+to be able manipulate the keys and data contained in it.
+@command{GDBM} allows an application to have multiple databases open at the
+same time.  When an application opens a @command{GDBM} database, it is
+designated as a @code{reader} or a @code{writer}.  A @command{GDBM}
 database can be opened by at most one writer at a time.  However, many
 readers may open the database simultaneously.  Readers and writers can
-not open the @code{gdbm} database at the same time.
+not open the @command{GDBM} database at the same time.
 
 Speaking about @dfn{application} we usually mean a separate process.
 However, it is entirely normal for a multi-thread program to operate
-as a @code{gdbm} reader in one thread and writer in another, provided,
-of course, that the two threads don't operate on the same database.
+as a @command{GDBM} reader in one thread and writer in another, provided,
+of course, that the two threads don't operate on the same database
+simultaneously.
 
 @flindex gdbm.h
-To use the @code{gdbm} functions, the programmer must first include
+To use the @command{GDBM} functions, the programmer must first include
 the header file @file{gdbm.h}.
 
 @tpindex GDBM_FILE
 This file defines, among others, the @code{GDBM_FILE} data type, an
-opaque pointer to the structure that represents the opened @code{gdbm}
+opaque pointer to the structure that represents the opened @command{GDBM}
 database.  To access the database, the programmer must first open it
 using the @code{gdbm_open} function.  The function takes several
 arguments, the name of the database file being one of them, and
@@ -256,7 +260,7 @@ the database is no longer needed, the programmer @dfn{closes} it using
 the @code{gdbm_close} call.
 
 These and other functions are discussed in detail in chapters that
-follow.  Here we show an example illustrating the use of @code{gdbm}
+follow.  Here we show an example illustrating the use of @command{GDBM}
 to look up a key in the database.
 
 @example
@@ -282,8 +286,8 @@ main (int argc, char **argv)
     @}
 
   /*
-   * Open the database.  The GDBM_READER flag indicates that we only intend
-   * to read from it.
+   * Open the database.  The GDBM_READER flag indicates that we only
+   * intend to read from it.
    */
   gdbf = gdbm_open (argv[1], 0, GDBM_READER, 0, NULL);
   if (gdbf == NULL)
@@ -350,7 +354,7 @@ cc -oexample example.c -lgdbm
 
 To run it, you will need an example database.  The easiest way to
 create it is by using the @command{gdbtool} program, which is part
-of the @code{gdbm} package (@pxref{gdbmtool}):
+of the @command{GDBM} package (@pxref{gdbmtool}):
 
 @example
 $ gdbmtool test.gdbm store foo bar
@@ -375,21 +379,19 @@ no such key
 @cindex database, opening or creating
 @deftypefn {gdbm interface} GDBM_FILE gdbm_open (const char *@var{name}, int @var{block_size}, @
   int @var{flags}, int @var{mode}, void (*@var{fatal_func})(const char *))
-Initializes @code{gdbm} system.  If the file has a size of zero bytes, a file
-initialization procedure is performed, setting up the initial structure in the
-file.
+Opens or creates a @command{GDBM} database file.
 
 The arguments are:
 
 @table @var
 @item name
-The name of the file (the complete name, @code{gdbm} does not append any
+The name of the file (the complete name, @command{GDBM} does not append any
 characters to this name).
+
 @item block_size
-It is used during initialization to determine the size of various
-constructs.  It is the size of a single transfer from disk to
-memory.  This parameter is ignored if the file has been previously
-initialized.  If the value is less than 512, the file system block
+This parameter is used only when @code{gdbm_open} has to create a new
+database file and represents the size of a single transfer from disk to
+memory.  If its 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.  However, if the
@@ -418,42 +420,24 @@ empty database structure is created in its place.
 The following constants may also be logically or'd into the database
 flags:
 
-@table @code
-@kwindex GDBM_SYNC
-@item GDBM_SYNC
-Synchronize all database operations to disk immediately.  Notice, that
-this option entails severe performance degradation and does not
-necessarily ensure that the resulting database state is consistent.
-In general, we discourage its use (@pxref{Sync}).
-@xref{Crash Tolerance}, for a discussion of how to ensure database
-consistency with minimal performance overhead.
-
-@kwindex GDBM_FAST
-@item GDBM_FAST
-A reverse of @code{GDBM_SYNC}.  Synchronize writes only when needed.
-This is the default.  The flag is provided for compatibility with
-previous versions of @command{GDBM}.
-
-@kwindex GDBM_NUMSYNC
-@item GDBM_NUMSYNC
-Useful only together with @code{GDBM_NEWDB}, this bit instructs
-@code{gdbm_open} to create new database in @dfn{extended database
-format}, suitable for effective crash recovery.  @xref{Numsync}, for a
-detailed discussion of this format, and @ref{Crash Tolerance}, for a
-discussion of crash recovery.
+@defvr {gdbm_open flag} GDBM_CLOEXEC
+@cindex close-on-exec
+Set the close-on-exec flag on the database file descriptor.  The
+@code{libc} must support the @code{O_CLOEXEC} flag
+(@pxref{O_CLOEXEC,,,open(2),open(2) man page}).
+@end defvr
 
-@kwindex GDBM_NOLOCK
-@item GDBM_NOLOCK
+@defvr {gdbm_open flag} GDBM_NOLOCK
 Don't lock the database file.  Use this flag if you intend to do
-locking separately.
+locking separately.  @xref{Locking}.
+@end defvr
 
-@kwindex GDBM_NOMMAP
-@item GDBM_NOMMAP
-Disable memory mapping mechanism.  This degrades performance.
+@defvr {gdbm_open flag} GDBM_NOMMAP
+Disable memory mapping mechanism.  Note, that this degrades performance.
+@end defvr
 
-@kwindex GDBM_PREREAD
-@item GDBM_PREREAD
-When mapping GDBM file to memory, read its contents immediately,
+@defvr {gdbm_open flag} GDBM_PREREAD
+When mapping @command{GDBM} file to memory, read its contents immediately,
 instead of when needed (@dfn{prefault reading}).  This can be
 advantageous if you open a @emph{read-only} database and are going to
 do a lot of look-ups on it.  In this case entire database will be
@@ -466,49 +450,80 @@ updates, especially for inserts: this will degrade performance.
 This flag has no effect if @code{GDBM_NOMMAP} is given, or if the
 operating system does not support prefault reading.  It is known
 to work on Linux and FreeBSD kernels.
+@end defvr
 
-@kwindex GDBM_BSEXACT
-@item GDBM_BSEXACT
-If this flag is set and the requested @var{block_size} cannot be used
-without adjustment, @code{gdbm_open} will refuse to create the
-databases.  In this case it will set the @code{gdbm_errno}
-variable to @code{GDBM_BLOCK_SIZE_ERROR} and return @code{NULL}.
-
-@kwindex GDBM_CLOEXEC
-@cindex close-on-exec
-@item GDBM_CLOEXEC
-Set the close-on-exec flag on the database file descriptor.  The
-@code{libc} must support the @code{O_CLOEXEC} flag
-(@pxref{O_CLOEXEC,,,open(2),open(2) man page}).
-
-@kwindex GDBM_XVERIFY
-@item GDBM_XVERIFY
+@defvr {gdbm_open flag} GDBM_XVERIFY
 Enable additional consistency checks.  With this flag, eventual
 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.
 
 @xref{Additional functions}.
-@end table
+@end defvr
+
+The following additional flags are valid when the database is opened
+for writing (i.e. together with @code{GDBM_WRITER},
+@code{GDBM_WRCREAT}, or @code{GDBM_NEWDB}):
+
+@defvr {gdbm_open flag} GDBM_SYNC
+Synchronize all database operations to disk immediately.  Notice, that
+this option entails severe performance degradation and does not
+necessarily ensure that the resulting database state is consistent.
+In general, we discourage its use (@pxref{Sync}).
+@xref{Crash Tolerance}, for a discussion of how to ensure database
+consistency with minimal performance overhead. 
+@end defvr
+
+@defvr {gdbm_open flag} GDBM_FAST
+A reverse of @code{GDBM_SYNC}.  Synchronize writes only when needed.
+This is the default.  The flag is provided for compatibility with
+previous versions of @command{GDBM}.
+@end defvr
+
+The following flags can be used together with @code{GDBM_NEWDB}.  They
+also take effect when used with @code{GDBM_WRCREAT}, if the requested
+database file doesn't exist:
+
+@defvr {gdbm_open flag} GDBM_BSEXACT
+If this flag is set and the requested @var{block_size} cannot be used
+without adjustment, @code{gdbm_open} will refuse to create the
+databases.  In this case it will set the @code{gdbm_errno}
+variable to @code{GDBM_BLOCK_SIZE_ERROR} and return @code{NULL}.
+@end defvr
+
+@defvr {gdbm_open flag} GDBM_NUMSYNC
+Useful only together with @code{GDBM_NEWDB}, this bit instructs
+@code{gdbm_open} to create new database in @dfn{extended database
+format}, a format best suitable for effective crash recovery.
+@xref{Numsync}, for a detailed discussion of this format, and
+@ref{Crash Tolerance}, for a discussion of crash recovery.
+@end defvr
 
 @item mode
 File mode@footnote{@xref{chmod,,,chmod(2),chmod(2) man page},
 and @xref{open,,open a file,open(2), open(2) man page}.},
 which is used if the file is created.
+
 @item fatal_func
-A function for @code{gdbm} to call if it detects a fatal error.  The only
-parameter of this function is a string.  If the value of @code{NULL} is
-provided, @code{gdbm} will use a default function.
+This parameter is deprecated and must always be @code{NULL}.
+
+Early versions of @command{GDBM} (prior to 1.13) lacked proper error
+handling and would abort on any ``fatal'' error (such as out of memory
+condition, disk write error, or the like).  In these versions,
+@code{fatal_func} was provided as a hook, allowing the caller to do
+proper cleanup before such abnormal exit.  As of version
+@value{VERSION}, this functionality is deprecated, although still
+supported for backward compatibility.
 @end table
 
 The return value, is the pointer needed by all other functions to
-access that @code{gdbm} file.  If the return is the @code{NULL} pointer,
+access that @command{GDBM} file.  If the return is the @code{NULL} pointer,
 @code{gdbm_open} was not successful.  The errors can be found in
 @code{gdbm_errno} variable (@pxref{Variables, gdbm_errno}).  Available
 error codes are discussed in @ref{Error codes}.
 
 In all of the following calls, the parameter @var{dbf} refers to the pointer
-returned from @code{gdbm_open}.
+returned from @code{gdbm_open} (or @code{gdbm_fd_open}, described below).
 @end deftypefn
 
 @anchor{gdbm_fd_open}
@@ -516,11 +531,20 @@ returned from @code{gdbm_open}.
   const char *@var{name}, int @var{block_size}, @
   int @var{flags}, int @var{mode}, void (*@var{fatal_func})(const char *))
 
-Alternative function for opening a GDBM database.  The @var{fd}
+Alternative function for opening a @command{GDBM} database.  The @var{fd}
 argument is the file descriptor of the database file obtained by a
 call to @code{open}(2), @code{creat}(2) or similar functions.  The
 descriptor is not dup'ed, and will be closed when the returned
-GDBM_FILE is closed.  Use @code{dup}(2) if that is not desirable.
+@code{GDBM_FILE} is closed.  Use @code{dup}(2) if that is not
+desirable.
+
+In case of error, the function behaves like @code{gdbm_open} and
+@emph{does not close} @var{fd}.  This can be altered by the following
+value passed in the @var{flags} argument:
+
+@defvr {gdbm_open flag} GDBM_CLOERROR
+Close @var{fd} before exiting on error.
+@end defvr
 @end deftypefn
 
 @deftypefn {gdbm interface} int gdbm_copy_meta (GDBM_FILE @var{dst},@
@@ -538,7 +562,7 @@ to properly update its disk structure and maintain a consistent
 locking state on the file.
 
 @deftypefn {gdbm interface} int gdbm_close (GDBM_FILE @var{dbf})
-This function closes the @code{gdbm} file and frees all memory
+This function closes the @command{GDBM} file and frees all memory
 associated with it.  The parameter is:
 
 @table @var
@@ -556,7 +580,7 @@ describing the error and returns -1.
 @cindex number of records
 @deftypefn {gdbm interface} int gdbm_count (GDBM_FILE @var{dbf}, @
   gdbm_count_t *@var{pcount})
-Counts number of records in the database @var{dbf}.  On success,
+Counts the number of records in the database @var{dbf}.  On success,
 stores it in the memory location pointed to by @var{pcount} and returns
 0.  On error, sets @code{gdbm_errno} (if relevant, also @code{errno})
 and returns -1.
@@ -564,7 +588,7 @@ and returns -1.
 
 @deftypefn {gdbm interface} int gdbm_bucket_count (GDBM_FILE @var{dbf}, @
   size_t *@var{pcount})
-Counts number of buckets in the database @var{dbf}.  On success,
+Counts the number of buckets in the database @var{dbf}.  On success,
 stores it in the memory location pointed to by @var{pcount} and return
 0.  On error, sets @code{gdbm_errno} (if relevant, also @code{errno})
 and returns -1.
@@ -592,10 +616,9 @@ The data to be associated with the key.
 @kwindex GDBM_REPLACE
 @kwindex GDBM_INSERT
 Defines the action to take when the key is already in the database.  The value
-@code{GDBM_REPLACE} (defined in @file{gdbm.h}) asks that the old data
-be replaced by the new @var{content}.  The value @code{GDBM_INSERT}
-asks that an error be returned and no action taken if the @var{key}
-already exists.
+@code{GDBM_REPLACE} asks that the old data be replaced by the new
+@var{content}.  The value @code{GDBM_INSERT} asks that an error be
+returned and no action taken if the @var{key} already exists.
 @end table
 
 This function can return the following values:
@@ -659,11 +682,11 @@ A seek error occurred on the underlying disk file.  Examine the system
 @end deftypefn
 
 If you store data for a @var{key} that is already in the data base,
-@code{gdbm} replaces the old data with the new data if called with
+@command{GDBM} replaces the old data with the new data if called with
 @code{GDBM_REPLACE}.  You do not get two data items for the same
 @code{key} and you do not get an error from @code{gdbm_store}.
 
-The size of datum in @code{gdbm} is restricted only by the maximum
+The size of datum in @command{GDBM} is restricted only by the maximum
 value for an object of type @code{int} (type of the @code{dsize} member of
 @code{datum}).
 
@@ -701,7 +724,10 @@ An example of using this function:
 content = gdbm_fetch (dbf, key);
 if (content.dptr == NULL)
   @{
-    fprintf(stderr, "key not found\n");
+    if (gdbm_errno == GDBM_ITEM_NOT_FOUND)
+      fprintf(stderr, "key not found\n");
+    else
+      fprintf(stderr, "error: %s\n", gdbm_db_strerror (dbf));
   @}
 else
   @{
@@ -753,8 +779,11 @@ The pointer returned by @code{gdbm_open}.
 The search key.
 @end table
 
-The function returns @code{-1} if the item is not present or the
-requester is a reader.  The return of @code{0} marks a successful delete.
+The function returns @code{-1} if the item is not present or if an
+error is encountered.  Examine the @code{gdbm_errno} variable or
+the return from @code{gdbm_last_errno (@var{dbf})} to know the reason.
+
+The return of @code{0} marks a successful delete.
 @end deftypefn
 
 @node Sequential
@@ -834,7 +863,8 @@ such a loop.  File visiting is based on a @dfn{hash table}.  The
 that any collisions in the table do not leave some item
 @dfn{un-findable}.  The original key order is @emph{not} guaranteed to
 remain unchanged in all instances.  So it is possible that some key
-will not be visited if a loop like the following is executed:
+will not be visited or will be visited twice, if a loop like the
+following is executed:
 
 @example
 @group
@@ -872,8 +902,8 @@ The pointer returned by @code{gdbm_open}.
 @end deftypefn
 
 If you have had a lot of deletions and would like to shrink the space
-used by the @code{gdbm} file, this function will reorganize the database.
-This results, in particular, in shortening the length of a @code{gdbm}
+used by the @command{GDBM} file, this function will reorganize the database.
+This results, in particular, in shortening the length of a @command{GDBM}
 file by removing the space occupied by deleted records.
 
 This reorganization requires creating a new file and inserting all the elements
@@ -883,11 +913,11 @@ correct information about the new file.  If an error is detected, the return
 value is negative.  The value zero is returned after a successful
 reorganization.
 
-@emph{Notice}, that calling this function disables crash tolerance,
-reverting the effect of the recent @code{gdbm_failure_atomic} call.
-You will have to call @code{gdbm_failure_atomic} again after
-@code{gdbm_reorganize} returns successfully.  This will be fixed in
-future releases.
+@emph{Notice}, that calling this function disables crash tolerance
+(@pxref{Crash Tolerance}), reverting the effect of the recent
+@code{gdbm_failure_atomic} call.  You will have to call
+@code{gdbm_failure_atomic} again after @code{gdbm_reorganize} returns
+successfully.  This will be fixed in future releases.
 
 @node Sync
 @chapter Database Synchronization
@@ -944,8 +974,8 @@ is used most often.  The @dfn{extended} database format is used to
 provide additional crash resistance (@pxref{Crash Tolerance}).
 
 Depending on the value of the @var{flags} parameter in a call to
-@code{gdbm_open} (@pxref{Open}), a database can be created in either
-format.
+@code{gdbm_open} (@pxref{Open, GDBM_NUMSYNC}), a database can be
+created in either format.
 
 The format of an existing database can be changed using the
 @code{gdbm_convert} function:
@@ -981,13 +1011,13 @@ returns success (0) without doing anything.
 @cindex Flat file format
 @cindex export
 @cindex import
-@code{Gdbm} databases can be converted into so-called @dfn{flat
+@command{GDBM} databases can be converted into so-called @dfn{flat
 format} files.  Such files cannot be used for searching, their sole
 purpose is to keep the data from the database for restoring it when
 the need arrives.  There are two flat file formats, which differ in
 the way they represent the data and in the amount of meta-information
 stored.  Both formats can be used, for example, to migrate between
-the different versions of @code{gdbm} databases.  Generally speaking,
+the different versions of @command{GDBM} databases.  Generally speaking,
 flat files are safe to send over the network, and can be used to
 recreate the database on another machine.  The recreated database is
 guaranteed to have the same format and contain the same set of
@@ -1012,11 +1042,12 @@ original database.  In general, such binary databases are not portable
 between machines, unless you follow some stringent rules on what data
 is written to them and how it is interpreted.
 
-The GDBM version @value{VERSION} supports two flat file formats.  The
-@dfn{binary} flat file format was first implemented in GDBM version
+@command{GDBM} version @value{VERSION} supports two flat file formats.  The
+@dfn{binary} flat file format was first implemented in version
 1.9.1.  This format stores only key/data pairs, it does not keep
 information about the database file itself.  As its name implies,
-files in this format are binary files.
+files in this format are binary files.  This format is supported for
+backward compatibility.
 
 The @dfn{ascii} flat file format encodes all data in Base64 and stores
 not only key/data pairs, but also the original database file metadata,
@@ -1113,7 +1144,7 @@ used to get more detail about the failure.
 
 @item GDBM_MALFORMED_DATA
 @itemx GDBM_ILLEGAL_DATA
-Input contained malformed data, i.e. it is not a valid @code{gdbm}
+Input contained malformed data, i.e. it is not a valid @command{GDBM}
 dump file.  This often means that the dump file got corrupted
 during the transfer.
 
@@ -1128,8 +1159,8 @@ this error equally as @code{GDBM_MALFORMED_DATA}.
 @end table
 
 Mild errors mean that the function was able to successfully load and
-restore the data, but was unable to change database file metadata
-afterward.  The table below lists possible values for @code{gdbm_errno}
+restore the data, but was unable to change the database file metadata
+afterwards.  The table below lists possible values for @code{gdbm_errno}
 in this case.  To get more detail, inspect the system @code{errno} variable.
 
 @table @asis
@@ -1173,7 +1204,7 @@ Format of the dump file.  See the @var{format} argument to the
 @deftypefn {gdbm interface} int gdbm_load_from_file (GDBM_FILE *@var{pdbf}, @
     FILE *@var{fp}, int @var{replace}, int @var{meta_mask}, @
     unsigned long *@var{line})
-This is an alternative entry point to @code{gdbm_dump}.  It writes the
+This is an alternative entry point to @code{gdbm_load}.  It writes the
 output to @var{fp} which must be a file open for writing.  The rest of
 arguments is the same as for @code{gdbm_load} (excepting of course
 @var{flag}, which is not needed in this case).
@@ -1183,7 +1214,7 @@ arguments is the same as for @code{gdbm_load} (excepting of course
            const char *@var{exportfile}, int @var{flag}, int @var{mode})
 This function is retained for compatibility with GDBM 1.10 and
 earlier.  It dumps the database to a file in binary dump format and
-is entirely equivalent to
+is equivalent to
 
 @example
 gdbm_dump(@var{dbf}, @var{exportfile}, GDBM_DUMP_FMT_BINARY, @var{flag}, @var{mode})
@@ -1198,7 +1229,7 @@ function writes to file @var{fp} a binary dump of the database @var{dbf}.
 
 @deftypefn {gdbm interface} int gdbm_import (GDBM_FILE @var{dbf}, @
            const char *@var{importfile}, int @var{flag})
-This function is retained for compatibility with GDBM 1.10 and
+This function is retained for compatibility with @command{GDBM} 1.10 and
 earlier.  It loads the file @var{importfile}, which must be a binary
 flat file, into the database @var{dbf} and is equivalent to the
 following construct:
@@ -1235,19 +1266,19 @@ gdbm_load_from_file (@var{dbf}, @var{fp}, @var{flag}, 0, NULL);
 @cindex error strings
 @cindex global error state
 The global variable @code{gdbm_errno} (@pxref{Variables, gdbm_errno})
-keeps the error code of the most recent error encountered by GDBM
+keeps the error code of the most recent error encountered by @command{GDBM}
 functions.
 
 To convert this code to human-readable string, use the following function:
 
 @deftypefn {gdbm interface} {const char *} gdbm_strerror (gdbm_error @var{errno})
-Converts @var{errno} (which is an integer value) into a human-readable
+Converts @var{errno} (an integer value) into a human-readable
 descriptive text.  Returns a pointer to a static string.  The caller
 must not free the returned pointer or alter the string it points to.
 @end deftypefn
 
 Detailed information about the most recent error that occurred while
-operating on a GDBM file is stored in the @code{GDBM_FILE} object
+operating on a @command{GDBM} file is stored in the @code{GDBM_FILE} object
 itself.  To retrieve it, the following functions are provided:
 
 @cindex error code, most recent
@@ -1255,13 +1286,20 @@ itself.  To retrieve it, the following functions are provided:
 @deftypefn {gdbm interface} {gdbm_error} gdbm_last_errno (GDBM_FILE @var{dbf})
 Returns the code of the most recent error encountered when operating
 on @var{dbf}.
+
+When @code{gdbm_last_errno} called immediately after the failed
+function, its return equals the value of the @code{gdbm_errno}
+variable.  However, @code{gdbm_errno} can be changed if any
+@command{GDBM} functions (operating on another databases) were called
+afterwards, and @code{gdbm_last_errno} will always return the code of
+the last error that occurred while working with @emph{that} database.
 @end deftypefn
 
 @deftypefn {gdbm interface} {int} gdbm_last_syserr (GDBM_FILE @var{dbf})
 Returns the value of the system @code{errno} variable associated with
 the most recent error.
 
-Notice, that not all GDBM errors have an associated system error
+Notice, that not all @command{GDBM} errors have an associated system error
 code.  The following are the ones that have:
 
 @itemize @bullet
@@ -1282,8 +1320,9 @@ For other errors, @code{gdbm_last_syserr} will return 0.
 
 @anchor{gdbm_check_syserr}
 @deftypefn {gdbm interface} {int} gdbm_check_syserr (gdbm_errno @var{err})
-Returns @code{1}, if system @code{errno} value should be checked to get more
-info on the error described by GDBM code @var{err}.
+Returns @code{1}, if the system @code{errno} value should be inspected
+to get more info on the error described by @command{GDBM} error code
+@var{err}.
 @end deftypefn
 
 To get a human-readable description of the recent error for a
@@ -1300,15 +1339,15 @@ described as well.
 
 @deftypefn {gdbm interface} void gdbm_clear_error (GDBM_FILE @var{dbf})
 Clears the error state for the database @var{dbf}.  Normally, this
-function is called upon the entry to any GDBM function.
+function is called upon the entry to any @command{GDBM} function.
 @end deftypefn
 
 Certain errors (such as write error when saving stored key) can leave
 database file in inconsistent state (@pxref{Database consistency}).
 When such a critical error occurs, the database file is marked as
-needing recovery.  Subsequent calls to any GDBM functions for that
+needing recovery.  Subsequent calls to any @command{GDBM} functions for that
 database file (except @code{gdbm_recover}), will return immediately
-with GDBM error value @code{GDBM_NEED_RECOVERY}.  Additionally, the
+with @command{GDBM} error code @code{GDBM_NEED_RECOVERY}.  Additionally, the
 following function can be used to check the state of the database file:
 
 @deftypefn {gdbm interface} int gdbm_needs_recovery (GDBM_FILE @var{dbf})
@@ -1367,8 +1406,8 @@ Certain errors (such as write error when saving stored key) can leave
 database file in @dfn{structurally inconsistent state}.  When such a
 critical error occurs, the database file is marked as needing
 recovery.  Subsequent calls to any GDBM functions for that database
-file (except @code{gdbm_recover}), will return immediately with GDBM
-error value @code{GDBM_NEED_RECOVERY}.
+file (except @code{gdbm_recover}), will return immediately with
+@command{GDBM} error code @code{GDBM_NEED_RECOVERY}.
 
 To escape from this state and bring the database back to operational
 state, use the following function:
@@ -1462,11 +1501,11 @@ Number of recovered buckets.
 @end deftypecv
 
 @deftypecv {output member} gdbm_recovery size_t failed_keys
-Number of key/data pairs that cannot be retrieved.
+Number of key/data pairs that could not be retrieved.
 @end deftypecv
 
 @deftypecv {output member} gdbm_recovery size_t failed_buckets
-Number of buckets that cannot be retrieved.
+Number of buckets that could not be retrieved.
 @end deftypecv
 
 @deftypecv {output member} gdbm_recovery {char *} backup_name
@@ -1705,7 +1744,7 @@ It is a programmer's error which means that your application needs to be
 fixed.
 
 @item ENOSYS
-Function is not implemented.  This means @code{GDBM} was built without
+Function is not implemented.  This means @command{GDBM} was built without
 crash-tolerance support.
 
 @item Other value (@code{EBADF}, @code{EFAULT}, etc)
@@ -1763,7 +1802,7 @@ by a colon and four fields, in this order:
 @item File permission bits in @command{ls -l} notation.
 @item Modification timestamp.
 @item Numsync counter.
-For databases in standard GDBM format, this field is @samp{N/A}.  If
+For databases in standard @command{GDBM} format, this field is @samp{N/A}.  If
 the counter cannot be obtained because of error, this field is @samp{?}.
 @end enumerate
 
@@ -1828,7 +1867,7 @@ The purpose of a parachute is not to hasten descent.  Crash tolerance
 is a safety mechanism, not a performance accelerator.  Reflink
 copying is designed to be as efficient as possible, but making
 snapshots of the GNU dbm database file on every @code{gdbm_sync} call
-entails overheads.  The performance impact of GDBM crash tolerance
+entails overheads.  The performance impact of @command{GDBM} crash tolerance
 will depend on many factors including the type and configuration of
 the underlying storage system, how often the application calls
 @code{gdbm_sync}, and the extent of changes to the database file
@@ -1844,7 +1883,7 @@ block storage services that mimic the interface of individual storage
 devices but that are implemented as high-availability fault-tolerant
 replicated distributed storage systems.  Installing a reflink-capable
 filesystem atop a high-availability storage system is a good starting
-point for a high-availability crash-tolerant GDBM.
+point for a high-availability crash-tolerant @command{GDBM}.
 
 @node Numsync
 @section Numsync Extension
@@ -2023,7 +2062,7 @@ user examine the snapshots and take the appropriate action.
 @cindex database options
 @cindex options, database
 
-@code{Gdbm} supports the ability to set certain options on an already
+@command{GDBM} supports the ability to set certain options on an already
 open database.
 
 @deftypefn {gdbm interface} int gdbm_setopt (GDBM_FILE @var{dbf}, int @var{option}, @
@@ -2105,7 +2144,7 @@ to an integer: @code{TRUE} to enable fast mode, and @code{FALSE} to
 disable it.
 
 This option is retained for compatibility with previous versions of
-@code{gdbm}.  Its effect is the reverse of @code{GDBM_SETSYNCMODE}
+@command{GDBM}.  Its effect is the reverse of @code{GDBM_SETSYNCMODE}
 (see below).
 
 @kwindex GDBM_SETSYNCMODE
@@ -2136,7 +2175,7 @@ point to an @code{int} where the status will be stored.
 @emph{NOTICE: This feature is still under study.}
 
 Set central free block pool to either on or off.  The default is off,
-which is how previous versions of @code{gdbm} handled free blocks.  If
+which is how previous versions of @command{GDBM} handled free blocks.  If
 set, this option causes all subsequent free blocks to be placed in the
 @emph{global} pool, allowing (in theory) more file space to be reused
 more quickly.  The @var{value} should point to an integer: @code{TRUE} to
@@ -2152,7 +2191,7 @@ earlier versions.
 @emph{NOTICE: This feature is still under study.}
 
 Set free block merging to either on or off.  The default is off, which
-is how previous versions of @code{gdbm} handled free blocks.  If set,
+is how previous versions of @command{GDBM} handled free blocks.  If set,
 this option causes adjacent free blocks to be merged.  This can become
 a @acronym{CPU} expensive process with time, though, especially if
 used in conjunction with GDBM_CENTFREE.  The @var{value} should point
@@ -2241,7 +2280,7 @@ calls.
 The following global variables and constants are available:
 
 @deftypevar gdbm_error gdbm_errno
-This variable contains error code from the last failed @code{gdbm}
+This variable contains error code from the last failed @command{GDBM}
 call.  @xref{Error codes}, for a list of available error codes and
 their descriptions.
 
@@ -2259,17 +2298,17 @@ text.
 @end deftypevar
 
 @deftypevar {int const} gdbm_syserr[]
-Array of boolean values indicating, for each GDBM error code, whether
+Array of boolean values indicating, for each @command{GDBM} error code, whether
 the value of @code{errno}(3) variable is meaningful for this error
 code.  @xref{gdbm_check_syserr}.
 @end deftypevar
 
 @defvr {Constant} _GDBM_MIN_ERRNO
-The minimum error code used by @code{gdbm}.
+The minimum error code used by @command{GDBM}.
 @end defvr
 
 @defvr {Constant} _GDBM_MAX_ERRNO
-The maximum error code used by @code{gdbm}.
+The maximum error code used by @command{GDBM}.
 @end defvr
 
 @cindex version number
@@ -2278,7 +2317,7 @@ A string containing the version information.
 @end deftypevar
 
 @deftypevar {int const} gdbm_version_number[3]
-This variable contains the @code{gdbm} version numbers:
+This variable contains the @command{GDBM} version numbers:
 
 @multitable @columnfractions 0.4 0.5
 @headitem Index @tab Meaning
@@ -2347,7 +2386,7 @@ needing recovery (@pxref{Recovery}) and return -1.
 @cindex error codes
 
 This chapter summarizes error codes which can be set by the
-functions in @code{gdbm} library.
+functions in @command{GDBM} library.
 
 @defvr {Error Code} GDBM_NO_ERROR
 No error occurred.
@@ -2401,12 +2440,12 @@ detailed diagnostics.
 
 @defvr {Error Code} GDBM_BAD_MAGIC_NUMBER
 The file given as argument to @code{gdbm_open} function is not a valid
-@code{gdbm} file: it has a wrong magic number.
+@command{GDBM} file: it has a wrong magic number.
 @end defvr
 
 @defvr {Error Code} GDBM_EMPTY_DATABASE
 The file given as argument to @code{gdbm_open} function is not a valid
-@code{gdbm} file: it has zero length.
+@command{GDBM} file: it has zero length.
 @end defvr
 
 @defvr {Error Code} GDBM_CANT_BE_READER
@@ -2460,7 +2499,7 @@ database and the @var{flag} parameter is not @code{GDBM_REPLACE}.
 @defvrx {Error Code} GDBM_ILLEGAL_DATA
 Input data was malformed in some way.  When returned by
 @code{gdbm_load}, this means that the input file was not a valid
-@code{gdbm} dump file (@pxref{gdbm_load function}).  When returned by
+@command{GDBM} dump file (@pxref{gdbm_load function}).  When returned by
 @code{gdbm_store}, this means that either @var{key} or @var{content}
 parameter had its @code{dptr} field set to @code{NULL}
 (@pxref{Store}).
@@ -2515,7 +2554,7 @@ 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.
 
-This error can be set by any GDBM function that does I/O.  Some of
+This error can be set by any @command{GDBM} function that does I/O.  Some of
 these functions are: @code{gdbm_delete}, @code{gdbm_exists},
 @code{gdbm_fetch}, @code{gdbm_dump}, @code{gdbm_load},
 @code{gdbm_export}, @code{gdbm_import}, @code{gdbm_reorganize},
@@ -2567,8 +2606,8 @@ recovery is needed (@pxref{Recovery}).
 
 @defvr {Error Code} GDBM_BAD_HEADER
 This error is set by @code{gdbm_open} and @code{gdbm_fd_open}, if the
-first block read from the database file does not contain a valid GDBM
-header.
+first block read from the database file does not contain a valid
+@command{GDBM} header.
 @end defvr
 
 @defvr {Error Code} GDBM_BAD_AVAIL
@@ -2670,7 +2709,7 @@ Older programs using @command{ndbm} or @command{dbm} interfaces can
 use @file{libgdbm_compat} without any changes.  To link a program with
 the compatibility library, add the following two options to the
 @command{cc} invocation: @option{-lgdbm -lgdbm_compat}.  The @option{-L}
-option may also be required, depending on where @code{gdbm} is
+option may also be required, depending on where @command{GDBM} is
 installed, e.g.:
 
 @example
@@ -2914,7 +2953,7 @@ never free it.
 @prindex gdbmtool
 
 The @command{gdbmtool} utility allows you to view and modify an
-existing @acronym{GDBM} database or to create a new one.
+existing @command{GDBM} database or to create a new one.
 
 @cindex default database, @command{gdbmtool}
 @flindex junk.gdbm
@@ -3167,7 +3206,7 @@ Default is @samp{,} (a comma).  This variable cannot be unset.
 
 @deftypevr {gdbmtool variable} string errorexit
 @deftypevrx {gdbmtool variable} bool errorexit
-Comma-delimited list of @code{gdbm} error codes which cause program
+Comma-delimited list of @command{GDBM} error codes which cause program
 termination.  Error codes are specified via their canonical names
 (@pxref{Error codes}).  The @code{GDBM_} prefix can be omitted.  Code
 name comparison is case-insensitive.  Each error code can optionally
@@ -3181,7 +3220,7 @@ and @code{false} (i.e. variable unset) is equivalent to @samp{-all}.
 
 @deftypevr {gdbmtool variable} string errormask
 @deftypevrx {gdbmtool variable} bool errormask
-Comma-delimited list of @code{gdbm} error codes which are masked, i.e.
+Comma-delimited list of @command{GDBM} error codes which are masked, i.e.
 which won't trigger a diagnostic message if they occur.  The syntax is
 the same as described for @code{errorexit}.
 @end deftypevr
@@ -3205,7 +3244,7 @@ follows:
 @headitem Sequence @tab Expansion
 @item %f @tab name of the current database file
 @item %p @tab program invocation name
-@item %P @tab package name (@code{GDBM})
+@item %P @tab package name (@samp{GDBM})
 @item %v @tab program version
 @item %_ @tab single space character
 @item %% @tab %
@@ -3366,10 +3405,10 @@ Flush all database writes on disk immediately.  Default is false.
 
 @deftypevr {gdbmtool variable} bool coalesce
 Enables the @emph{coalesce} mode, i.e. merging of the freed blocks of
-GDBM files with entries in available block lists. This provides for
-effective memory management at the cost of slight increase in
-execution time when calling @code{gdbm_delete}. @xref{Options,
-GDBM_SETCOALESCEBLKS}.
+@command{GDBM} files with entries in available block lists. This
+provides for effective memory management at the cost of slight
+increase in execution time when calling
+@code{gdbm_delete}. @xref{Options, GDBM_SETCOALESCEBLKS}.
 
 This variable affects the currently opened database immediately and
 will be used by @command{open} command, when it is invoked.
@@ -3550,9 +3589,9 @@ displays @var{count} last commands from the history.  With two
 arguments, displays @var{count} commands starting from @var{n}th
 command.  Command numbering starts with 1.
 
-This command is available only if GDBM was compiled with GNU Readline.
-The history is saved in file @file{.gdbmtool_history} in the user's
-home directory.  If this file exists upon startup, it is read to
+This command is available only if @command{GDBM} was compiled with GNU
+Readline.  The history is saved in file @file{.gdbmtool_history} in
+the user's home directory.  If this file exists upon startup, it is read to
 populate the history.  Thus, command history is preserved between
 @command{gdbmtool} invocations.
 @end deffn
@@ -3619,7 +3658,7 @@ Synchronize after each write.  Default is @code{off}.
 @end deffn
 
 @deffn {command verb} perror [@var{code}]
-Describe the given GDBM error code.
+Describe the given @command{GDBM} error code.
 
 The descripion occupies one or two lines.  The second line is present
 if the system error number should be checked when handling this code.
@@ -3739,7 +3778,7 @@ Print the version of @command{gdbm}.
 
 @node definitions
 @subsection Data Definitions
-GDBM databases are able to keep data of any type, both in the key and
+@command{GDBM} databases are able to keep data of any type, both in the key and
 in the content part of a record.  Quite often these data are
 structured, i.e. they consist of several fields of various types.
 @command{Gdbmtool} provides a mechanism for handling such kind of
@@ -3814,7 +3853,7 @@ part of datum.  Consider the following two definitions:
 
 @noindent
 Now, suppose we want to store the string "ab" in the key.  Using the
-definition (1), the @code{dptr} member of GDBM @code{datum} will
+definition (1), the @code{dptr} member of @command{GDBM} @code{datum} will
 contain two bytes: @samp{a}, and @samp{b}.  Consequently, the
 @code{dsize} member will have the value 2.  Using the definition (2),
 the @code{dptr} member will contain three bytes: @samp{a}, @samp{b},
@@ -3940,7 +3979,7 @@ define content @{
 @chapter The @command{gdbm_dump} utility
 @prindex gdbm_dump
 
-The @command{gdbm_dump} utility creates a flat file dump of a GDBM
+The @command{gdbm_dump} utility creates a flat file dump of a @command{GDBM}
 database (@pxref{Flat files}).  It takes one mandatory argument: the
 name of the source database file.  The second argument, if given,
 specifies the name of the output file.  If not given,
@@ -3984,7 +4023,7 @@ command line options.
 @chapter The @command{gdbm_load} utility
 @prindex gdbm_load
 
-The @command{gdbm_load} utility restores a GDBM database from a flat
+The @command{gdbm_load} utility restores a @command{GDBM} database from a flat
 file.  The utility requires at least one argument: the name of the
 input flat file.  If it is @samp{-}, the standard input will be read.
 The format of the input file is detected automatically.
@@ -4051,8 +4090,8 @@ command line options.
 @chapter Exit codes
 @cindex exit code
 
-All GDBM utilities return uniform exit codes.  These are summarized in
-the table below:
+All @command{GDBM} utilities return uniform exit codes.  These are
+summarized in the table below:
 
 @multitable @columnfractions 0.3 0.7
 @headitem Code @tab Meaning
@@ -4074,7 +4113,7 @@ a bug in the documentation!
 
 Before reporting a bug or trying to fix it yourself, try to isolate it
 to the smallest possible input file that reproduces the problem.  Then
-send us the input file and the exact results @code{gdbm} gave you.  Also
+send us the input file and the exact results @command{GDBM} gave you.  Also
 say what you expected to occur; this will help us decide whether the
 problem was really in the documentation.
 
@@ -4104,10 +4143,10 @@ Crash tolerance support written by Terence Kelly
 For the latest updates and pointers to additional resources, visit
 @uref{http://www.gnu.org/@/software/@/gdbm}.
 
-In particular, a copy of @code{gdbm} documentation in various formats
+In particular, a copy of @command{GDBM} documentation in various formats
 is available online at @uref{http://www.gnu.org/@/software/@/gdbm/@/manual.html}.
 
-Latest versions of @code{gdbm} can be downloaded from anonymous FTP:
+Latest versions of @command{GDBM} can be downloaded from anonymous FTP:
 @uref{ftp://ftp.gnu.org/@/gnu/@/gdbm}, or via HTTP from
 @uref{http://ftp.gnu.org/@/gnu/@/gdbm}, or via HTTPS from
 @uref{https://ftp.gnu.org/@/gnu/@/gdbm},
@@ -4120,7 +4159,7 @@ GNU mirror worldwide.  See @uref{http://www.gnu.org/@/order/@/ftp.html},
 for a list of mirrors.
 @end ifnothtml
 
-To track @code{gdbm} development, visit
+To track @command{GDBM} development, visit
 @uref{http://puszcza.gnu.org.ua/@/projects/@/gdbm}.
 
 @node GNU Free Documentation License