aboutsummaryrefslogtreecommitdiff
path: root/doc/gdbm.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/gdbm.texi')
-rw-r--r--doc/gdbm.texi190
1 files changed, 126 insertions, 64 deletions
diff --git a/doc/gdbm.texi b/doc/gdbm.texi
index a738c85..4888968 100644
--- a/doc/gdbm.texi
+++ b/doc/gdbm.texi
@@ -43,8 +43,7 @@ Published by the Free Software Foundation,
51 Franklin Street, Fifth Floor
Boston, MA 02110-1301, USA
-Copyright @copyright{} 1989-1999, 2007-2021 Free Software Foundation,
-Inc.
+Copyright @copyright{} 1989--2023 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -529,7 +528,7 @@ returned from @code{gdbm_open} (or @code{gdbm_fd_open}, described below).
@anchor{gdbm_fd_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 (*@var{fatal_func})(const char *))
+ int @var{flags}, void (*@var{fatal_func})(const char *))
Alternative function for opening a @command{GDBM} database. The @var{fd}
argument is the file descriptor of the database file obtained by a
@@ -1303,10 +1302,12 @@ 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
+@item GDBM_ERR_SNAPSHOT_CLONE
+@item GDBM_ERR_REALPATH
+@item GDBM_ERR_USAGE
@end itemize
For other errors, @code{gdbm_last_syserr} will return 0.
@@ -2083,20 +2084,19 @@ success. The global variable @code{gdbm_errno} will be set upon failure.
The valid options are:
-@table @asis
-@kwindex GDBM_CACHESIZE
-@kwindex GDBM_SETCACHESIZE
-@item GDBM_SETCACHESIZE
-@itemx GDBM_CACHESIZE
-@kwindex GDBM_CACHE_AUTO
+@defvr {Option} GDBM_SETCACHESIZE
+@defvrx {Option} GDBM_CACHESIZE
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
+constant @code{GDBM_CACHE_AUTO}, to adjust the 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.
+By default, a newly open database is configured to dynamically
+accommodate the cache size to the number of index buckets in the
+database file. This provides for the best performance.
+
+If another @var{value} is set, it is adjusted to the nearest larger
+power of two.
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
@@ -2110,41 +2110,84 @@ 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}:
+To request the automatically adjustable 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
+@end defvr
+
+@defvr {Option} GDBM_GETCACHESIZE
+Return the actual size of the internal bucket cache. The @var{value}
+should point to a @code{size_t} variable, where the size will be
+stored.
+@end defvr
+
+@defvr {Option} GDBM_SETCACHEAUTO
+Controls whether the cache size will be adjusted automatically as
+needed. The @var{value} should point to an integer: @code{TRUE} to
+enable automatic cache adjustment and @code{FALSE} to disable it.
+
+The following two calls are equivalent:
+
+@example
+int t = TRUE;
+gdbm_setopt (dbf, GDBM_SETCACHEAUTO, &t, sizeof (t));
+
+size_t n = GDBM_CACHE_AUTO;
+gdbm_setopt (dbf, GDBM_SETCACHESIZE, &n, sizeof (n));
+@end example
+@end defvr
-@kwindex GDBM_GETCACHESIZE
-@item GDBM_GETCACHESIZE
-Return the size of the internal bucket cache. The @var{value} should
-point to a @code{size_t} variable, where the size will be stored.
+@defvr {Option} GDBM_GETCACHEAUTO
+Return the state of the automatic cache size adjustment. The
+@var{value} should point to an integer which, upon successful return,
+will have the value @code{TRUE} if the automatic cache size adjustment
+is enabled and @code{FALSE} otherwise.
+@end defvr
-@kwindex GDBM_GETFLAGS
-@item GDBM_GETFLAGS
+@defvr {Option} GDBM_GETFLAGS
Return the flags describing the state of the database. The @var{value} should
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}).
+@end defvr
+
+@defvr {Option} GDBM_GETDBFORMAT
+Return the database format. The @var{value} should point to an
+@code{int} variable. Upon successful return, it will be set to
+@samp{0} if the database is in standard format and @code{GDBM_NUMSYNC}
+if it is in extended format. @xref{Database format}.
+@end defvr
+
+@defvr {Option} GDBM_GETDIRDEPTH
+Returns the @dfn{directory depth}: the number of initial (most significant)
+bits in hash value that are interpreted as index to the directory. The
+actual directory size can be computed as @code{1 << @var{value}}.
-@kwindex GDBM_FASTMODE
-@item GDBM_FASTMODE
+The @var{value} argument should point to an @code{int}.
+@end defvr
+
+@defvr {Option} GDBM_GETBUCKETSIZE
+Returns the @dfn{bucket capacity}: maximum number of keys per bucket
+(@code{int}).
+@end defvr
+
+@defvr {Option} GDBM_FASTMODE
Enable or disable the @dfn{fast writes mode}, i.e.@: writes without
subsequent synchronization. The @var{value} should point
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
-@command{GDBM}. Its effect is the reverse of @code{GDBM_SETSYNCMODE}
-(see below).
+@command{GDBM}. Its effect is the reverse of @code{GDBM_SETSYNCMODE}.
+@end defvr
-@kwindex GDBM_SETSYNCMODE
-@kwindex GDBM_SYNCMODE
-@item GDBM_SETSYNCMODE
-@itemx GDBM_SYNCMODE
+@defvr {Option} GDBM_SETSYNCMODE
+@defvrx {Option} GDBM_SYNCMODE
Turn on or off file system synchronization operations. This
setting defaults to off. The @var{value} should point
to an integer: @code{TRUE} to turn synchronization on, and @code{FALSE} to
@@ -2156,16 +2199,15 @@ as calling @code{GDBM_FASTMODE} with @code{FALSE}.
The @code{GDBM_SYNCMODE} option is provided for compatibility with
earlier versions.
+@end defvr
-@kwindex GDBM_GETSYNCMODE
-@item GDBM_GETSYNCMODE
+@defvr {Option} GDBM_GETSYNCMODE
Return the current synchronization status. The @var{value} should
point to an @code{int} where the status will be stored.
+@end defvr
-@kwindex GDBM_SETCENTFREE
-@kwindex GDBM_CENTFREE
-@item GDBM_SETCENTFREE
-@itemx GDBM_CENTFREE
+@defvr {Option} GDBM_SETCENTFREE
+@defvrx {Option} GDBM_CENTFREE
@emph{NOTICE: This feature is still under study.}
Set central free block pool to either on or off. The default is off,
@@ -2177,11 +2219,10 @@ turn central block pool on, and @code{FALSE} to turn it off.
The @code{GDBM_CENTFREE} option is provided for compatibility with
earlier versions.
+@end defvr
-@kwindex GDBM_SETCOALESCEBLKS
-@kwindex GDBM_COALESCEBLKS
-@item GDBM_SETCOALESCEBLKS
-@itemx GDBM_COALESCEBLKS
+@defvr {Option} GDBM_SETCOALESCEBLKS
+@defvrx {Option} GDBM_COALESCEBLKS
@emph{NOTICE: This feature is still under study.}
Set free block merging to either on or off. The default is off, which
@@ -2191,38 +2232,38 @@ a @acronym{CPU} expensive process with time, though, especially if
used in conjunction with GDBM_CENTFREE. The @var{value} should point
to an integer: @code{TRUE} to turn free block merging on, and @code{FALSE} to
turn it off.
+@end defvr
-@kwindex GDBM_GETCOALESCEBLKS
-@item GDBM_GETCOALESCEBLKS
+@defvr {Option} GDBM_GETCOALESCEBLKS
Return the current status of free block merging. The @var{value} should
point to an @code{int} where the status will be stored.
+@end defvr
-@kwindex GDBM_SETMAXMAPSIZE
-@item GDBM_SETMAXMAPSIZE
+@defvr {Option} GDBM_SETMAXMAPSIZE
Sets maximum size of a memory mapped region. The @var{value} should
point to a value of type @code{size_t}, @code{unsigned long} or
@code{unsigned}. The actual value is rounded to the nearest page
boundary (the page size is obtained from
@code{sysconf(_SC_PAGESIZE)}).
+@end defvr
-@kwindex GDBM_GETMAXMAPSIZE
-@item GDBM_GETMAXMAPSIZE
+@defvr {Option} GDBM_GETMAXMAPSIZE
Return the maximum size of a memory mapped region. The @var{value} should
point to a value of type @code{size_t} where to return the data.
+@end defvr
-@kwindex GDBM_SETMMAP
-@item GDBM_SETMMAP
+@defvr {Option} GDBM_SETMMAP
Enable or disable memory mapping mode. The @var{value} should point
to an integer: @code{TRUE} to enable memory mapping or @code{FALSE} to
disable it.
+@end defvr
-@kwindex GDBM_GETMMAP
-@item GDBM_GETMMAP
+@defvr {Option} GDBM_GETMMAP
Check whether memory mapping is enabled. The @var{value} should point
to an integer where to return the status.
+@end defvr
-@kwindex GDBM_GETDBNAME
-@item GDBM_GETDBNAME
+@defvr {Option} GDBM_GETDBNAME
Return the name of the database disk file. The @var{value} should
point to a variable of type @code{char**}. A pointer to the newly
allocated copy of the file name will be placed there. The caller is
@@ -2243,12 +2284,11 @@ else
free (name);
@}
@end example
+@end defvr
-@kwindex GDBM_GETBLOCKSIZE
-@item GDBM_GETBLOCKSIZE
+@defvr {Option} GDBM_GETBLOCKSIZE
Return the block size in bytes. The @var{value} should point to @code{int}.
-
-@end table
+@end defvr
@node Locking
@chapter File Locking
@@ -3210,6 +3250,8 @@ symmetry). A special code @samp{all} stands for all available error codes.
In boolean context, the @code{true} value is equivalent to @samp{all},
and @code{false} (i.e. variable unset) is equivalent to @samp{-all}.
+
+This variable cannot be set from interactive sessions.
@end deftypevr
@deftypevr {gdbmtool variable} string errormask
@@ -4029,9 +4071,17 @@ must be given as the second argument.
In general, if two arguments are given, the second one is treated as
the name of the database to create, overriding the file name specified
-in the flat file.
+in the flat file. All existing keys will be removed from this
+database prior to loading from the dump. Use the @option{--update}
+(@option{-U}) option if it is not what you wish.
-The utility understands the following command line arguments:
+When given the @option{--update} (@option{-U}) option,
+@command{gdbm_load} will update the existing database with the data
+from the dump. It will bail out if the dump contains a key that is
+already present in the database. To silently overwrite existing keys,
+use the @option{--replace} (@option{-r}) option.
+
+The utility understands the following command line options:
@table @option
@@ -4057,15 +4107,27 @@ Do not restore file meta-data (ownership and mode) from the flat file.
@item -r
@itemx --replace
-Replace existing keys.
-
-@item -u @var{user}[:@var{group}]
-@itemx --user=@var{user}[:@var{group}]
-Set file owner. The @var{user} can be either a valid user name or
+Replace existing keys. This option can be used only together with
+@option{--update} (@option{-U}).
+
+@item -U
+@itemx --update
+Update an existing database. The database name must be given in the
+second argument to @command{gdbm_load}. The key/value pairs from the
+dump file will be added to that database, without removing the
+existing keys. To overwrite the existing keys from the dump file, use
+@option{--update --replace}.
+
+@item -u @var{owner}[:[@var{group}]]
+@itemx --user=@var{owner}[:[@var{group}]]
+Set file owner. The @var{owner} can be either a valid user name or
UID. Similarly, the @var{group} is either a valid group name or GID.
-If @var{group} is not given, the main group of @var{user} is used.
+If @var{group} is not given, the main group of @var{owner} is implied, if
+@var{owner} is followed by a @samp{:}, otherwise the login group of the
+current user is implied.
-User and group parts can be separated by a dot, instead of the colon.
+User and group parts can be separated by a dot, instead of the colon,
+but such usage is discouraged.
@item -h
@itemx --help

Return to:

Send suggestions and report system problems to the System administrator.