aboutsummaryrefslogtreecommitdiff
path: root/doc/gdbm.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/gdbm.texi')
-rw-r--r--doc/gdbm.texi815
1 files changed, 543 insertions, 272 deletions
diff --git a/doc/gdbm.texi b/doc/gdbm.texi
index 159a108..5f42ced 100644
--- a/doc/gdbm.texi
+++ b/doc/gdbm.texi
@@ -44,7 +44,7 @@ Published by the Free Software Foundation,
51 Franklin Street, Fifth Floor
Boston, MA 02110-1301, USA
-Copyright @copyright{} 1989-1999, 2007-2020 Free Software Foundation,
+Copyright @copyright{} 1989-1999, 2007-2021 Free Software Foundation,
Inc.
Permission is granted to copy, distribute and/or modify this document
@@ -68,7 +68,7 @@ Documentation License.''
@sp 1
@center Edition @value{EDITION}
@sp 1
-@center for GNU @code{dbm}, Version @value{VERSION}
+@center for GNU @command{dbm}, Version @value{VERSION}
@page
@vskip 0pt plus 1filll
@insertcopying
@@ -85,8 +85,8 @@ Documentation License.''
@node Top
@top The GNU database manager.
-GNU @code{dbm} is a library of functions implementing a hashed database
-on a disk file. This manual documents GNU @code{dbm} Version @value{VERSION}
+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.
@@ -97,7 +97,6 @@ Introduction:
* Copying:: Your rights.
* Intro:: Introduction to GNU dbm.
-* List:: List of functions.
Functions:
@@ -116,7 +115,7 @@ Functions:
* Options:: Setting internal options.
* Locking:: File locking.
* Variables:: Useful global variables.
-
+* Additional functions::
* Error codes:: Error codes returned by @code{gdbm} calls.
* Compatibility:: Compatibility with UNIX dbm and ndbm.
@@ -134,37 +133,42 @@ Other topics:
* GNU Free Documentation License:: Document license.
* Index:: Index
+@ifset WEBDOC
+@ifhtml
+* This Manual in Other Formats::
+@end ifhtml
+@end ifset
@end menu
@node Copying
@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 @code{dbm} (@code{gdbm})
-is not in the public domain; it is copyrighted and there
+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
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
-you.@refill
+you.
Specifically, we want to make sure that you have the right to give
away copies @code{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.@refill
+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
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.@refill
+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.
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.@refill
+reputation.
@code{Gdbm} is currently distributed under the terms of the GNU General
Public License, Version 3. (@emph{NOT} under the GNU General Library
@@ -172,30 +176,32 @@ Public License.) A copy the GNU General Public License is included with
the distribution of @code{gdbm}.
@node Intro
-@chapter Introduction to GNU @code{dbm}.
+@chapter Introduction to GNU @command{dbm}.
-GNU @code{dbm} (@code{gdbm}) is a library of database functions that use
-extensible hashing and works similar to the standard UNIX @code{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}
functions. These routines are provided to a programmer needing to
create and manipulate a hashed database. (@code{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.
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:
@example
- typedef struct @{
- char *dptr;
- int dsize;
- @} datum;
+typedef struct
+@{
+ char *dptr;
+ int dsize;
+@} datum;
@end example
This structure allows for arbitrary sized keys and data items.
The key/data pairs are stored in a @code{gdbm} disk file, called a
-@code{gdbm} database. An application must open a @code{gdbm} database
+@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
@@ -204,40 +210,133 @@ 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.
-@node List
-@chapter List of functions.
-
-The following is a quick list of the functions contained in the @code{gdbm}
-library. The include file @code{gdbm.h}, that can be included by the user,
-contains a definition of these functions.
+@flindex gdbm.h
+To use the @code{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 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
+returns a @code{GDBM_FILE} object on success. This object is then
+passed to other functions in order to manipulate the database. When
+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}
+to look up a key in the database.
@example
+#include <stdio.h>
+#include <string.h>
#include <gdbm.h>
-GDBM_FILE gdbm_open(name, block_size, flags, mode, fatal_func);
-int gdbm_close(dbf);
-int gdbm_store(dbf, key, content, flag);
-datum gdbm_fetch(dbf, key);
-int gdbm_delete(dbf, key);
-datum gdbm_firstkey(dbf);
-datum gdbm_nextkey(dbf, key);
-int gdbm_reorganize(dbf);
-int gdbm_sync(dbf);
-int gdbm_exists(dbf, key);
-char *gdbm_strerror(errno);
-int gdbm_setopt(dbf, option, value, size);
-int gdbm_fdesc(dbf);
-int gdbm_export (GDBM_FILE, const char *, int, int);
-int gdbm_export_to_file (GDBM_FILE dbf, FILE *fp);
-int gdbm_import (GDBM_FILE, const char *, int);
-int gdbm_import_from_file (GDBM_FILE dbf, FILE *fp, int flag);
-int gdbm_count (GDBM_FILE dbf, gdbm_count_t *pcount);
-int gdbm_version_cmp (int const a[], int const b[]);
+int
+main (int argc, char **argv)
+@{
+ GDBM_FILE gdbf; /* Database file object pointer */
+ datum key, content; /* Key and content data */
+ int status = 0; /* Exit status of the program: 0 - OK, 1 - key
+ not found, 2 - error. */
+
+ /*
+ * Validate arguments.
+ */
+ if (argc != 3)
+ @{
+ fprintf (stderr, "usage: %s DBFILE KEY\n", argv[0]);
+ return 2;
+ @}
+
+ /*
+ * 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)
+ @{
+ fprintf (stderr, "can't open database: %s\n",
+ gdbm_strerror (gdbm_errno));
+ @}
+
+ /*
+ * Prepare the lookup key. Notice, that the terminating \0 character
+ * is not counted in the dsize computation.
+ */
+ key.dptr = argv[2];
+ key.dsize = strlen (argv[2]);
+
+ /*
+ * Look up the key in the database.
+ */
+ content = gdbm_fetch (gdbf, key);
+
+ /*
+ * Analyze the return.
+ */
+ if (content.dptr != NULL)
+ @{
+ /*
+ * The key is found. Print the content on the stdout and
+ * indicate success.
+ */
+ fwrite (content.dptr, content.dsize, 1, stdout);
+ putchar ('\n');
+ status = 0;
+ @}
+ else if (gdbm_errno == GDBM_ITEM_NOT_FOUND)
+ @{
+ /*
+ * There is no such key in the database.
+ */
+ fprintf (stderr, "no such key\n");
+ status = 1;
+ @}
+ else
+ @{
+ /*
+ * An error occurred.
+ */
+ fprintf (stderr, "%s\n", gdbm_db_strerror (gdbf));
+ status = 2;
+ @}
+
+ /*
+ * Close the database and return.
+ */
+ gdbm_close (gdbf);
+ return status;
+@}
+@end example
+
+To compile this example, run
+
+@example
+cc -oexample example.c -lgdbm
@end example
-The @code{gdbm.h} include file is often in the @file{/usr/include}
-directory. (The actual location of @code{gdbm.h} depends on your local
-installation of @code{gdbm}.)
+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}):
+
+@example
+$ gdbmtool test.gdbm store foo bar
+@end example
+
+@noindent
+This creates database file @file{test.gdbm} and stores a single record
+in it. The record's key is @samp{foo}, and the value is @samp{bar}.
+Now you can run the example program to see how it works:
+
+@example
+$ ./example test.gdbm foo
+bar
+$ ./example test.gdbm baz
+no such key
+@end example
@node Open
@chapter Opening the database.
@@ -245,7 +344,7 @@ installation of @code{gdbm}.)
@cindex opening the database
@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 (*fatal_func)(const char *))
+ 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.
@@ -264,79 +363,109 @@ initialized. 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. However, if the
-@samp{GDBM_BSEXACT} flag is set and the size needs to be adjusted, the
-function will return with error status, setting the @samp{gdbm_errno}
-variable to @samp{GDBM_BLOCK_SIZE_ERROR}.
+@code{GDBM_BSEXACT} flag is set and the size needs to be adjusted, the
+function will return with error status, setting the @code{gdbm_errno}
+variable to @code{GDBM_BLOCK_SIZE_ERROR}.
@item flags
@kwindex GDBM_READER
@kwindex GDBM_WRITER
@kwindex GDBM_WRCREAT
@kwindex GDBM_NEWDB
-If @code{flags} is set to @samp{GDBM_READER}, the user wants to just read the
+If @code{flags} is set to @code{GDBM_READER}, the user wants to just read the
database and any call to @code{gdbm_store} or @code{gdbm_delete} will fail.
Many readers can access the database at the same time. If @code{flags} is
-set to @samp{GDBM_WRITER}, the user wants both read and write access
+set to @code{GDBM_WRITER}, the user wants both read and write access
to the database and requires exclusive access. If @code{flags} is set
-to @samp{GDBM_WRCREAT}, the user wants both read and write access to
+to @code{GDBM_WRCREAT}, the user wants both read and write access to
the database and wants it created if it does not already exist. If
-@code{flags} is set to @samp{GDBM_NEWDB}, the user want a new database
+@code{flags} is set to @code{GDBM_NEWDB}, the user want a new database
created, regardless of whether one existed, and wants read and write
access to the new database.
@kwindex GDBM_SYNC
@kwindex GDBM_NOLOCK
@kwindex GDBM_NOMMAP
-The following may also be logically or'd into the database flags:
-@samp{GDBM_SYNC}, which causes all database operations to be
-synchronized to the disk, @samp{GDBM_NOLOCK}, which prevents the library
-from performing any locking on the database file, and @samp{GDBM_NOMMAP},
-which disables the memory mapping mechanism. The option @samp{GDBM_FAST} is
-now obsolete, since @code{gdbm} defaults to no-sync mode.
+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. This
+provides for the best database consistency at the expense of severe
+performance degradation.
+
+@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_NOLOCK
+@item GDBM_NOLOCK
+Don't lock the database file. Use this flag if you intend to do
+locking separately.
+
+@kwindex GDBM_NOMMAP
+@item GDBM_NOMMAP
+Disable memory mapping mechanism. This degrades performance.
@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 @samp{gdbm_errno}
-variable to @samp{GDBM_BLOCK_SIZE_ERROR} and return @samp{NULL}.
+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
-If the host @samp{open} call
+@item GDBM_CLOEXEC
+Set the close-on-exec flag on the database file descriptor. The
+@code{libc} must support the @code{O_CLOEXEC} flag@footnote{
@ifhtml
(@uref{http://www.manpagez.com/man/2/open, open(2)})
@end ifhtml
@ifnothtml
-(@pxref{open,,,open(2),open(2) man page})
+@xref{open,,,open(2),open(2) man page}
@end ifnothtml
-supports the @samp{O_CLOEXEC} flag, the @samp{GDBM_CLOEXEC} can be
-or'd into the flags, to enable the close-on-exec flag for the
-database file descriptor.
+}
+
+@kwindex GDBM_XVERIFY
+@item 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
+
@item mode
-File mode (see
+File mode@footnote{See
@ifhtml
-@uref{http://www.manpagez.com/man/2/chmod},
+@uref{http://www.manpagez.com/man/2/chmod, chmod(2)},
@end ifhtml
@ifnothtml
-@ref{chmod,,change permissions of a file,chmod(2),
+@xref{chmod,,change permissions of a file,chmod(2),
chmod(2) man page},
@end ifnothtml
and
@ifhtml
-@uref{http://www.manpagez.com/man/2/open}),
+@uref{http://www.manpagez.com/man/2/open, open(2)}),
@end ifhtml
@ifnothtml
-@pxref{open,,open a file,open(2), open(2) man page}),
+@ref{open,,open a file,open(2), open(2) man page}.},
@end ifnothtml
-which is used if the file is created).
+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 @samp{NULL} is
+parameter of this function is a string. If the value of @code{NULL} is
provided, @code{gdbm} will use a default function.
@end table
The return value, is the pointer needed by all other functions to
-access that @code{gdbm} file. If the return is the @samp{NULL} pointer,
+access that @code{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}.
@@ -347,11 +476,11 @@ returned from @code{gdbm_open}.
@deftypefn {gdbm interface} GDBM_FILE gdbm_fd_open (int @var{fd},@
const char *@var{name}, int @var{block_size}, @
- int @var{flags}, int @var{mode}, void (*fatal_func)(const char *))
+ int @var{flags}, int @var{mode}, void (*@var{fatal_func})(const char *))
Alternative function for opening a 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 funcionss. The
+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.
@end deftypefn
@@ -389,6 +518,14 @@ describing the error and returns -1.
@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,
+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.
+@end deftypefn
+
+@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,
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.
@@ -416,8 +553,8 @@ 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
-@samp{GDBM_REPLACE} (defined in @file{gdbm.h}) asks that the old data
-be replaced by the new @var{content}. The value @samp{GDBM_INSERT}
+@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.
@end table
@@ -425,31 +562,31 @@ already exists.
This function can return the following values:
@table @asis
+@item 0
+Success. The value of @var{content} is keyed by @var{key} in the
+database.
@item -1
The item was not stored in the database because the caller was not an
official writer or either @var{key} or @var{content} have a
-@samp{NULL} @samp{dptr} field.
+@code{NULL} @code{dptr} field.
-Both @var{key} and @var{content} must have the @samp{dptr} field be a
-non-@samp{NULL} value. Since a @samp{NULL} @samp{dptr} field is used by
+Both @var{key} and @var{content} must have the @code{dptr} field be a
+non-@code{NULL} value. Since a @code{NULL} @code{dptr} field is used by
other functions to indicate an error, it cannot be valid data.
@item +1
The item was not stored because the argument @var{flag} was
-@samp{GDBM_INSERT} and the @var{key} was already in the database.
-@item 0
-No error. The value of @var{content} is keyed by @var{key}. The file
-on disk is updated to reflect the structure of the new database before
-returning from this function.
+@code{GDBM_INSERT} and the @var{key} was already in the database.
@end table
@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
-@samp{GDBM_REPLACE}. You do not get two data items for the same
+@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 in @code{gdbm} is not restricted like @code{dbm} or @code{ndbm}. Your
-data can be as large as you want.
+The size of datum in @code{gdbm} is restricted only by the maximum
+value for an object of type @code{int} (type of the @code{dsize} member of
+@code{datum}).
@node Fetch
@chapter Searching for records in the database.
@@ -459,13 +596,13 @@ data can be as large as you want.
@deftypefn {gdbm interface} datum gdbm_fetch (GDBM_FILE @var{dbf}, datum @var{key})
Looks up a given @var{key} and returns the information associated with it.
-The @samp{dptr} field in the structure that is returned points to a
+The @code{dptr} field in the structure that is returned points to a
memory block allocated by @code{malloc}. It is the caller's
responsibility to free it when no longer needed.
-If the @samp{dptr} is @samp{NULL}, inspect the value of the
+If the @code{dptr} is @code{NULL}, inspect the value of the
@code{gdbm_errno} variable (@pxref{Variables,gdbm_errno}). If it is
-@samp{GDBM_ITEM_NOT_FOUND}, no data was found. Any other value means an
+@code{GDBM_ITEM_NOT_FOUND}, no data was found. Any other value means an
error occurred. Use @code{gdbm_strerror} function to convert
@code{gdbm_errno} to a human-readable string.
@@ -499,12 +636,12 @@ You may also search for a particular key without retrieving it:
@deftypefn {gdbm interface} int gdbm_exists (GDBM_FILE @var{dbf}, datum @var{key})
Checks whether the @var{key} exists in the database @var{dbf}.
-If @var{key} is found, returns @samp{true} (@samp{1}). If it is not
-found, returns @samp{false} (@samp{0}) and sets @code{gdbm_errno} to
-@samp{GDBM_NO_ERROR} (@samp{0}).
+If @var{key} is found, returns @code{true} (@code{1}). If it is not
+found, returns @code{false} (@code{0}) and sets @code{gdbm_errno} to
+@code{GDBM_NO_ERROR} (@code{0}).
-On error, returns @samp{0} and sets @code{gdbm_errno} to a
-non-@samp{0} error code.
+On error, returns @code{0} and sets @code{gdbm_errno} to a
+non-@code{0} error code.
The parameters are:
@@ -526,8 +663,7 @@ function.
@deftypefn {gdbm interface} int gdbm_delete (GDBM_FILE @var{dbf}, datum @var{key})
Deletes the data associated with the given @var{key}, if it exists in
-the database @var{dbf}. The file on disk is updated to reflect the
-structure of the new database before returning from this function.
+the database @var{dbf}.
The parameters are:
@@ -538,8 +674,8 @@ The pointer returned by @code{gdbm_open}.
The search key.
@end table
-The function returns @samp{-1} if the item is not present or the
-requester is a reader. The return of @samp{0} marks a successful delete.
+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.
@end deftypefn
@node Sequential
@@ -557,36 +693,36 @@ access is not @code{key} sequential, but it is guaranteed to visit every
@deftypefn {gdbm interface} datum gdbm_firstkey (GDBM_FILE @var{dbf})
Initiate sequential access to the database @var{dbf}. The returned
-value is the first key accessed in the database. If the @samp{dptr}
-field in the returned datum is @samp{NULL}, inspect the
+value is the first key accessed in the database. If the @code{dptr}
+field in the returned datum is @code{NULL}, inspect the
@code{gdbm_errno} variable (@pxref{Variables, gdbm_errno}). The value
of @code{GDBM_ITEM_NOT_FOUND} means that the database contains no
data. Other value means an error occurred.
-Otherwise, @samp{dptr} points to a memory block obtained from
+On success, @code{dptr} points to a memory block obtained from
@code{malloc}, which holds the key value. The caller is responsible
for freeing this memory block when no longer needed.
@end deftypefn
@deftypefn {gdbm interface} datum gdbm_nextkey (GDBM_FILE @var{dbf}, datum @var{prev})
-This function continues the iteration over the keys in @var{dbf},
+This function continues iteration over the keys in @var{dbf},
initiated by @code{gdbm_firstkey}. The parameter @var{prev} holds the
value returned from a previous call to @code{gdbm_nextkey} or
@code{gdbm_firstkey}.
-The function returns next key from the database. If the @samp{dptr}
-field in the returned datum is @samp{NULL} inspect the
+The function returns next key from the database. If the @code{dptr}
+field in the returned datum is @code{NULL} inspect the
@code{gdbm_errno} variable (@pxref{Variables, gdbm_errno}). The value
of @code{GDBM_ITEM_NOT_FOUND} means that all keys in the database
has been visited. Any other value means an error occurred.
-Otherwise, @samp{dptr} points to a memory block obtained from
+Otherwise, @code{dptr} points to a memory block obtained from
@code{malloc}, which holds the key value. The caller is responsible
for freeing this memory block when no longer needed.
@end deftypefn
@cindex iteration loop
-These functions were intended to visit the database in read-only algorithms,
+These functions are intended to visit the database in read-only algorithms,
for instance, to validate the database or similar operations. The
usual algorithm for sequential access is:
@@ -613,7 +749,7 @@ usual algorithm for sequential access is:
@cindex iteration and @code{gdbm_delete}
@cindex deletion in iteration loops
@cindex @code{gdbm_delete} and sequential access
-Care should be taken when the @code{gdbm_delete} function is used in
+Don't use @code{gdbm_delete} or @code{gdbm_store} in
such a loop. File visiting is based on a @dfn{hash table}. The
@code{gdbm_delete} function re-arranges the hash table to make sure
that any collisions in the table do not leave some item
@@ -674,7 +810,7 @@ reorganization.
@cindex synchronization, database
@kwindex GDBM_SYNC
-Unless your database was opened with the @samp{GDBM_SYNC} flag,
+Unless your database was opened with the @code{GDBM_SYNC} flag,
@code{gdbm} does not wait for writes to be flushed to the disk before
continuing. This allows for faster writing of databases at the risk
of having a corrupted database if the application terminates in an
@@ -730,7 +866,7 @@ The GDBM version @value{VERSION} supports two flat file formats. The
information about the database file itself. As its name implies,
files in this format are binary files.
-The @dfn{ascii} flat file format encodes all data in base64 and stores
+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,
such as file name, mode and ownership. Files in this format can be
sent without additional encapsulation over transmission channels that
@@ -759,22 +895,22 @@ A pointer to the source database, returned by a prior call to
Name of the dump file.
@item format
-Output file format. Allowed values are: @samp{GDBM_DUMP_FMT_BINARY} to
-create a binary dump and @samp{GDBM_DUMP_FMT_ASCII} to create an ASCII
+Output file format. Allowed values are: @code{GDBM_DUMP_FMT_BINARY} to
+create a binary dump and @code{GDBM_DUMP_FMT_ASCII} to create an ASCII
dump file.
@item open_flags
-How to create the output file. If @var{flag} is @samp{GDBM_WRCREAT}
+How to create the output file. If @var{flag} is @code{GDBM_WRCREAT}
the file will be created if it does not exist. If it does exist,
the @code{gdbm_dump} will fail.
-If @var{flag} is @samp{GDBM_NEWDB}, the function will create a new
+If @var{flag} is @code{GDBM_NEWDB}, the function will create a new
output file, replacing it if it already exists.
@item mode
The permissions to use when creating the output file.
@ifhtml
-See @uref{http://www.manpagez.com/man/2/open},
+See @uref{http://www.manpagez.com/man/2/open, open(2)},
@end ifhtml
@ifnothtml
See @ref{open,,open a file,open(2), open(2) man page},
@@ -789,13 +925,13 @@ for a detailed discussion.
int @var{meta_mask}, @
unsigned long *@var{errline})
Loads data from the dump file @var{filename} into the database pointed
-to by @var{pdbf}. The latter can point to @samp{NULL}, in which case
+to by @var{pdbf}. The latter can point to @code{NULL}, in which case
the function will try to create a new database. If it succeeds, the
function will return, in the memory location pointed to by @var{pdbf},
a pointer to the newly created database. If the dump file carries no
information about the original database file name, the function will
-set @code{gdbm_errno} to @samp{GDBM_NO_DBNAME} and return
-@samp{-1}, indicating failure.
+set @code{gdbm_errno} to @code{GDBM_NO_DBNAME} and return
+@code{-1}, indicating failure.
The @var{flag} has the same meaning as the @var{flag} argument
to the @code{gdbm_store} function (@pxref{Store}).
@@ -837,7 +973,7 @@ Input contained some illegal data.
This error can occur only when the input file is in ASCII format. It
indicates that the data part of the record about to be read lacked
length specification. Application developers are advised to treat
-this error equally as @samp{GDBM_ILLEGAL_DATA}.
+this error equally as @code{GDBM_ILLEGAL_DATA}.
@end table
Mild errors mean that the function was able to successfully load and
@@ -858,10 +994,10 @@ The function was unable to restore database file mode (permission bits).
If an error occurs while loading data from an input file in ASCII
format, the number of line in which the error occurred will be stored
in the location pointed to by the @var{errline} parameter, unless it
-is @samp{NULL}.
+is @code{NULL}.
If the line information is not available or applicable, @var{errline}
-will be set to @samp{0}.
+will be set to @code{0}.
@end deftypefn
@deftypefn {gdbm interface} int gdbm_dump_to_file (GDBM_FILE @var{dbf}, @
@@ -899,8 +1035,7 @@ earlier. It dumps the database to a file in binary dump format and
is entirely equivalent to
@example
-gdbm_dump(@var{dbf}, @var{exportfile}, GDBM_DUMP_FMT_BINARY,
- @var{flag}, @var{mode})
+gdbm_dump(@var{dbf}, @var{exportfile}, GDBM_DUMP_FMT_BINARY, @var{flag}, @var{mode})
@end example
@end deftypefn
@@ -985,6 +1120,10 @@ code. The following are the ones that have:
@item GDBM_FILE_READ_ERROR
@item GDBM_FILE_STAT_ERROR
@item GDBM_BACKUP_FAILED
+@item GDBM_BACKUP_FAILED
+@item GDBM_FILE_CLOSE_ERROR
+@item GDBM_FILE_SYNC_ERROR
+@item GDBM_FILE_TRUNCATE_ERROR
@end itemize
For other errors, @code{gdbm_last_syserr} will return 0.
@@ -992,7 +1131,7 @@ 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 errno value should be checked to get more
+Returns @code{1}, if system @code{errno} value should be checked to get more
info on the error described by GDBM code @var{err}.
@end deftypefn
@@ -1003,7 +1142,7 @@ particular database file, use the @code{gdbm_db_strerror} function:
Returns textual description of the most recent error encountered when
operating on the database @var{dbf}. The resulting string is often
more informative than what would be returned by
-@samp{gdbm_strerror(gdbm_last_errno(@var{dbf}))}. In particular, if
+@code{gdbm_strerror(gdbm_last_errno(@var{dbf}))}. In particular, if
there is a system error associated with the recent failure, it will be
described as well.
@end deftypefn
@@ -1014,7 +1153,7 @@ function is called upon the entry to any GDBM function.
@end deftypefn
Certain errors (such as write error when saving stored key) can leave
-database file in inconistent state. When such a critical error
+database file in 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
@@ -1033,7 +1172,7 @@ call the @code{gdbm_recover} function (@pxref{Recovery}).
@chapter Recovery
Certain errors (such as write error when saving stored key) can leave
-database file in @dfn{inconistent state}. When such a critical error
+database file in @dfn{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
@@ -1047,12 +1186,12 @@ state, use the following function:
Check the database file @var{dbf} and fix eventual errors. The
@var{rcvr} argument points to a structure that has @dfn{input
members}, providing additional information to alter the behavior of
-@code{gdbm_recover}, and @dfn{output members}, used to return
+@code{gdbm_recover}, and @dfn{output members}, which are used to return
additional statistics about the recovery process (@var{rcvr} can be
@code{NULL} if no such information is needed).
Each input member has a corresponding flag bit, which must be set in
-the @var{flags} in order to instruct the function to use it.
+@var{flags}, in order to instruct the function to use it.
The @code{gdbm_recover} type is defined as:
@@ -1080,13 +1219,22 @@ typedef struct gdbm_recovery_s
The @dfn{input members} modify the behavior of @code{gdbm_recover}:
-@deftypeop {input member} gdbm_recovery void (*errfun) (void *@var{data},@
+@deftypecv {input member} gdbm_recovery void (*errfun) (void *@var{data},@
char const *@var{fmt}, ...)
@kwindex GDBM_RCVR_ERRFUN
If the @code{GDBM_RCVR_ERRFUN} flag bit is set, @code{errfun} points
to a function that will be called upon each recoverable or non-fatal
-error that occurred during the recovery.
-@end deftypeop
+error that occurred during the recovery. The @code{data} field of
+@code{gdbm_recovery} will be passed to it as its first argument. The
+@var{fmt} argument is a
+@ifhtml
+@uref{http://www.manpagez.com/man/3/printf, printf(3)}-like
+@end ifhtml
+@ifnothtml
+@code{printf}-like (@pxref{printf,,format output,printf(3), printf(2) man page}),
+@end ifnothtml
+format string. The rest of arguments supply parameters for that format.
+@end deftypecv
@deftypecv {input member} gdbm_recovery {void *} data
Supplies first argument for the @code{errfun} invocations.
@@ -1096,7 +1244,7 @@ Supplies first argument for the @code{errfun} invocations.
@kwindex GDBM_RCVR_MAX_FAILED_KEYS
If @code{GDBM_RCVR_MAX_FAILED_KEYS} is set, this member sets the limit
on the number of keys that cannot be retrieved. If the number of
-failed keys grows bigger than @code{max_failed_keys}, recovery is
+failed keys becomes equal to @code{max_failed_keys}, recovery is
aborted and error is returned.
@end deftypecv
@@ -1104,7 +1252,7 @@ aborted and error is returned.
@kwindex GDBM_RCVR_MAX_FAILED_BUCKETS
If @code{GDBM_RCVR_MAX_FAILED_BUCKETS} is set, this member sets the limit
on the number of buckets that cannot be retrieved or that contain
-bogus information. If the number of failed buckets grows bigger than
+bogus information. If the number of failed buckets becomes equal to
@code{max_failed_buckets}, recovery is aborted and error is returned.
@end deftypecv
@@ -1112,8 +1260,8 @@ bogus information. If the number of failed buckets grows bigger than
@kwindex GDBM_RCVR_MAX_FAILURES
If @code{GDBM_RCVR_MAX_FAILURES} is set, this member sets the limit
of failures that are tolerated during recovery. If the number of
-errors grows bigger than @code{max_failures}, recovery is aborted and
-error is returned.
+errors becomes equal to @code{max_failures}, recovery is aborted and
+error is returned.
@end deftypecv
The following members are filled on output, upon successful return
@@ -1145,10 +1293,10 @@ The caller is responsible for freeing that memory when no longer needed.
@end deftypefn
@kwindex GDBM_RCVR_FORCE
-By default, @code{gdbm_recovery} first checks the database fo
+By default, @code{gdbm_recovery} first checks the database for
inconsistencies and attempts recovery only if some were found.
The special flag bit @code{GDBM_RCVR_FORCE} instructs
-@code{gdbm_recovery} to omit this check and to force recovery
+@code{gdbm_recovery} to omit this check and to perform database recovery
unconditionally.
@node Options
@@ -1176,6 +1324,9 @@ place the option value (depending on the option).
@item size
The length of the data pointed to by @var{value}.
@end table
+
+The return value will be @code{-1} upon failure, or @code{0} upon
+success. The global variable @code{gdbm_errno} will be set upon failure.
@end deftypefn
The valid options are:
@@ -1185,13 +1336,34 @@ The valid options are:
@kwindex GDBM_SETCACHESIZE
@item GDBM_SETCACHESIZE
@itemx GDBM_CACHESIZE
-Set the size of the internal bucket cache. This option may only be
-set once on each GDBM_FILE descriptor, and is set automatically to 100
-upon the first access to the database. The @var{value} should point
-to a @code{size_t} holding the desired cache size.
+@kwindex GDBM_CACHE_AUTO
+Set the size of the internal bucket cache. The @var{value} should
+point to a @code{size_t} holding the desired cache size, or the
+constant @code{GDBM_CACHE_AUTO}, to set the best cache size
+automatically.
+
+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.
+
+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. For example:
-The @samp{GDBM_CACHESIZE} option is provided for compatibility with
-earlier versions.
+@example
+size_t bn;
+gdbm_bucket_count (dbf, &bn);
+ret = gdbm_setopt (dbf, GDBM_SETCACHESIZE, &bn, sizeof (bn));
+@end example
+
+To set the best cache size, use the constant @code{GDBM_CACHE_AUTO}:
+
+@example
+size_t bn = GDBM_CACHE_AUTO;
+ret = gdbm_setopt (dbf, GDBM_SETCACHESIZE, &bn, sizeof (bn));
+@end example
@kwindex GDBM_GETCACHESIZE
@item GDBM_GETCACHESIZE
@@ -1201,16 +1373,16 @@ point to a @code{size_t} variable, where the size will be stored.
@kwindex GDBM_GETFLAGS
@item GDBM_GETFLAGS
Return the flags describing the state of the database. The @var{value} should
-point to a @code{int} variable where to store the flags. The return
-is the same as the flags used when opening the database (@pxref{Open,
-gdbm_open}), except that it reflects the current state (which may have
-been altered by another calls to @code{gdbm_setopt}.
+point to an @code{int} variable where to store the flags. On success,
+its value will be similar to the flags used when opening the database
+(@pxref{Open, gdbm_open}), except that it will reflect the current state
+(which may have been altered by another calls to @code{gdbm_setopt}).
@kwindex GDBM_FASTMODE
@item GDBM_FASTMODE
Enable or disable the @dfn{fast writes mode}, i.e.@: writes without
subsequent synchronization. The @var{value} should point
-to an integer: @samp{TRUE} to enable fast mode, and @samp{FALSE} to
+to an integer: @code{TRUE} to enable fast mode, and @code{FALSE} to
disable