aboutsummaryrefslogtreecommitdiff
path: root/doc/gdbm.3
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org>2021-10-17 11:40:16 +0300
committerSergey Poznyakoff <gray@gnu.org>2021-10-17 12:21:08 +0300
commit1733320d47df1d18d622e6b3565d3d6c51b9deeb (patch)
tree13b4027313ec3a9e3df13d8497616df7f89702ab /doc/gdbm.3
parente3866a39dd09ebee2c891228d766661ce14d09c7 (diff)
downloadgdbm-1733320d47df1d18d622e6b3565d3d6c51b9deeb.tar.gz
gdbm-1733320d47df1d18d622e6b3565d3d6c51b9deeb.tar.bz2
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
Diffstat (limited to 'doc/gdbm.3')
-rw-r--r--doc/gdbm.31182
1 files changed, 911 insertions, 271 deletions
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