gdbm-1.23/ 0000755 0001750 0001750 00000000000 14177231731 007357 5 0000000 0000000 gdbm-1.23/NOTE-WARNING 0000644 0001750 0001750 00000002015 14164261602 011064 0000000 0000000 ******************************************************************************
W A R N I N G
******************************************************************************
Gdbm files have never been `portable' between different operating systems,
system architectures, or potentially even different compilers. Differences
in byte order, the size of file offsets, and even structure packing make
gdbm files non-portable.
Therefore, if you intend to send your database to somebody over the wire,
please dump it into a portable format using gdbm_dump and send the resulting
file instead. The receiving party will be able to recreate the database from
the dump using the gdbm_load command.
Please refer to the documentation, chapters 25 and 26, for a detailed
discussion of these two tools. Run `info gdbm gdbm_dump', if gdbm is
already installed on your system, or `info -f doc/gdbm.info gdbm_dump'
to read the docs from the source tree.
The documentation is also available online at
http://www.gnu.org.ua/software/gdbm/manual.
gdbm-1.23/doc/ 0000755 0001750 0001750 00000000000 14177231731 010124 5 0000000 0000000 gdbm-1.23/doc/gdbm.3 0000644 0001750 0001750 00000124501 14164261602 011040 0000000 0000000 .\" This file is part of GDBM.
.\" Copyright (C) 2011-2022 Free Software Foundation, Inc.
.\"
.\" GDBM is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
.\" GDBM is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with GDBM. If not, see . */
.TH GDBM 3 "October 18, 2021" "GDBM" "GDBM User Reference"
.SH NAME
GDBM \- The GNU database manager. Includes \fBdbm\fR and \fBndbm\fR
compatibility.
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "extern gdbm_error" " gdbm_errno";
.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 ", "
.ti +21
.BI "void (*" fatal_func ")(const char *))";
.br
.BI "int gdbm_close (GDBM_FILE " dbf ");"
.br
.BI "int gdbm_store (GDBM_FILE " dbf ", datum " key ", datum " content ", int " flag ");"
.br
.BI "datum gdbm_fetch (GDBM_FILE " dbf ", datum " key ");"
.br
.BI "int gdbm_delete (GDBM_FILE " dbf ", datum " key ");"
.br
.BI "datum gdbm_firstkey (GDBM_FILE " dbf ");"
.br
.BI "datum gdbm_nextkey (GDBM_FILE " dbf ", datum " key ");"
.br
.BI "int gdbm_recover (GDBM_FILE " dbf ", gdbm_recovery *" rcvr ", int" flags ");"
.br
.BI "int gdbm_reorganize (GDBM_FILE " dbf ");"
.br
.BI "int gdbm_sync (GDBM_FILE " dbf ");"
.br
.BI "int gdbm_exists (GDBM_FILE " dbf ", datum " key ");"
.br
.BI "const char *gdbm_strerror (gdbm_error " errno ");"
.br
.BI "int gdbm_setopt (GDBM_FILE " dbf ", int " option ", int " value ", int " size );
.br
.BI "int gdbm_fdesc (GDBM_FILE " dbf );
.br
.BI "int gdbm_count (GDBM_FILE " dbf ", gdbm_count_t *" pcount ");"
.br
.BI "int gdbm_bucket_count (GDBM_FILE " dbf ", size_t *" pcount ");"
.br
.BI "int gdbm_avail_verify (GDBM_FILE " dbf ");"
.PP
.SS Crash Tolerance (see below):
.PP
.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 ");"
.SH NOTICE
This manpage is a short description of the \fBGDBM\fR library.
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,
\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
.TP
.B GDBM_WRITER
writer
.TP
.B GDBM_WRCREAT
writer - if database does not exist create new one
.TP
.B GDBM_NEWDB
writer - create new database regardless if one exists
.PP
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
Flags that are valid for any value of access mode are:
.TP
.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_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
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 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
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
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. 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 ");"
.SS Database lookups
.TP
.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
.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\fR does not automatically free this data.
It is the programmer's responsibility to free this storage when it is
no longer needed.
.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 ");"
Returns first key in the database.
.TP
.BI "datum gdbm_nextkey (GDBM_FILE " dbf ", datum " key );
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
key = gdbm_firstkey (dbf);
while (key.dptr)
{
nextkey = gdbm_nextkey (dbf, key);
if (some condition)
gdbm_delete ( dbf, key );
free (key.dptr);
key = nextkey;
}
.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
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.
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.
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.
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.
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.
.TP
.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
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 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
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 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 );
Returns the file descriptor of the database \fIdbf\fR.
.SH CRASH TOLERANCE
By default \fBGNU dbm\fR does not protect the integrity of its
databases from corruption or destruction due to failures such as
power outages, operating system kernel panics, or application process
crashes. Such failures could damage or destroy the underlying
database.
.PP
Starting with release 1.21 \fBGNU dbm\fR includes a mechanism that,
if used correctly, enables post-crash recovery to a consistent state
of the underlying database. This mechanism requires OS and
filesystem support and must be requested when \fBgdbm\fR is compiled.
The crash-tolerance mechanism is a "pure opt-in" feature, in the
sense that it has no effects whatsoever except on those applications
that explicitly request it. For details, see the chapter
.B "Crash Tolerance"
in the
.BR "GDBM manual" .
.SH GLOBAL VARIABLES
.TP
.B gdbm_error gdbm_errno
This variable contains code of the most recent error that occurred.
Note, that it is not C variable in the proper sense: you can use its
value, assign any value to it, but taking its address will result in
syntax error. It is a per-thread memory location.
.TP
.B const char *gdbm_version
A string containing the library version number and build date.
.TP
.B int const gdbm_version_number[3]
This variable contains library version numbers: major, minor, and
patchlevel.
.SH VERSIONING
The version information is kept in two places. The version of the
library is kept in the \fBgdbm_version_number\fR variable, described
above. Additionally, the header file \fBgdbm.h\fR defines the
following macros:
.TP
.B GDBM_VERSION_MAJOR
Major version number.
.TP
.B GDBM_VERSION_MINOR
Minor version number.
.TP
.B GDBM_VERSION_PATCH
Patchlevel number. \fB0\fR means no patchlevel.
.PP
You can use this to compare whether your header file corresponds to
the library the program is linked with.
.PP
The following function can be used to compare two version numbers:
.TP
.BI "int gdbm_version_cmp (int const " a "[3], int const " b "[3])"
Compare two version numbers formatted as \fBgdbm_version_number\fR.
Return negative number if \fBa\fR is older than \fBb\fR, positive
number if \fBa\fR is newer than \fBb\fR, and 0 if they are equal.
.SH ERROR CODES
.TP
.B GDBM_NO_ERROR
No error occurred.
.TP
.B GDBM_MALLOC_ERROR
Memory allocation failed.
.TP
.B GDBM_BLOCK_SIZE_ERROR
This error is set by the \fBgdbm_open\fR function, if
the value of its \fIblock_size\fR argument is incorrect and the
\fBGDBM_BSEXACT\fR flag is set.
.TP
.B GDBM_FILE_OPEN_ERROR
The library was not able to open a disk file. This can be set by
\fBgdbm_open\fR, \fBgdbm_fd_open\fR, \fBgdbm_dump\fR and
\fBgdbm_load\fR functions.
.sp
Inspect the value of the system \fBerrno\fR variable to get more
detailed diagnostics.
.TP
.B GDBM_FILE_WRITE_ERROR
Writing to a disk file failed. This can be set by
\fBgdbm_open\fR, \fBgdbm_fd_open\fR, \fBgdbm_dump\fR and
\fBgdbm_load\fR functions.
.sp
Inspect the value of the system \fBerrno\fR variable to get more
detailed diagnostics.
.TP
.B GDBM_FILE_SEEK_ERROR
Positioning in a disk file failed. This can be set by
\fBgdbm_open\fR function.
.sp
Inspect the value of the system \fBerrno\fR variable to get a more
detailed diagnostics.
.TP
.B GDBM_FILE_READ_ERROR
Reading from a disk file failed. This can be set by
\fBgdbm_open\fR, \fBgdbm_dump\fR and \fBgdbm_load\fR functions.
.sp
Inspect the value of the system \fBerrno\fR variable to get a more
detailed diagnostics.
.TP
.B GDBM_BAD_MAGIC_NUMBER
The file given as argument to \fBgdbm_open\fR function is not a valid
\fBgdbm\fR file: it has a wrong magic number.
.TP
.B GDBM_EMPTY_DATABASE
The file given as argument to \fBgdbm_open\fR function is not a valid
\fBgdbm\fR file: it has zero length. This error is returned unless
the \fIflags\fR argument has \fBGDBM_NEWDB\fR bit set.
.TP
.B GDBM_CANT_BE_READER
This error code is set by the \fBgdbm_open\fR function if it is not
able to lock file when called in \fBGDBM_READER\fR mode.
.TP
.B GDBM_CANT_BE_WRITER
This error code is set by the \fBgdbm_open\fR function if it is not
able to lock file when called in writer mode.
.TP
.B GDBM_READER_CANT_DELETE
Set by the \fBgdbm_delete\fR, if it attempted to operate on a database
that is open in read-only mode.
.TP
.B GDBM_READER_CANT_STORE
Set by the \fBgdbm_store\fR if it attempted to operate on a database
that is open in read-only mode.
.TP
.B GDBM_READER_CANT_REORGANIZE
Set by the \fBgdbm_reorganize\fR if it attempted to operate on a
database that is open in read-only mode.
.TP
.B GDBM_ITEM_NOT_FOUND
Requested item was not found. This error is set by \fBgdbm_delete\fR
and \fBgdbm_fetch\fR when the requested key value is not found in the
database.
.TP
.B GDBM_REORGANIZE_FAILED
The \fBgdbm_reorganize\fR function is not able to create a temporary
database.
.TP
.B GDBM_CANNOT_REPLACE
Cannot replace existing item. This error is set by the
\fBgdbm_store\fR if the requested key value is found in the
database and the \fIflag\fR parameter is not \fBGDBM_REPLACE\fR.
.TP
.B GDBM_MALFORMED_DATA
Input data was malformed in some way. When returned by
\fBgdbm_load\fR, this means that the input file was not a valid
\fBgdbm\fR dump file. When returned by \fBgdbm_store\fR, this means
that either \fIkey\fR or \fIcontent\fR parameter had its \fBdptr\fR
field set to \fBNULL\fR.
.sp
The \fBGDBM_ILLEGAL_DATA\fR is an alias for this error code,
maintained for backward compatibility.
.TP
.B GDBM_OPT_ALREADY_SET
Requested option can be set only once and was already set. As of
version 1.21, this error code is no longer used. In prior
versions it could have been returned by the \fBgdbm_setopt\fR
function when setting the \fBGDBM_CACHESIZE\fR value.
.TP
.B GDBM_OPT_BADVAL
The \fIoption\fR argument is not valid or the \fIvalue\fR argument
points to an invalid value in a call to \fBgdbm_setopt\fR function.
.sp
\fBGDBM_OPT_ILLEGAL\fR is an alias for this error code, maintained
for backward compatibility. Modern applications should not use it.
.TP
.B GDBM_BYTE_SWAPPED
The \fBgdbm_open\fR function attempts to open a database which is
created on a machine with different byte ordering.
.TP
.B GDBM_BAD_FILE_OFFSET
The \fBgdbm_open\fR function sets this error code if the file it tries
to open has a wrong magic number.
.TP
.B GDBM_BAD_OPEN_FLAGS
Set by the \fBgdbm_dump\fR function if supplied an invalid
\fIflags\fR argument.
.TP
.B GDBM_FILE_STAT_ERROR
Getting information about a disk file failed. The system \fBerrno\fR
will give more details about the error.
.sp
This error can be set by the following functions: \fBgdbm_open\fR,
\fBgdbm_reorganize\fR.
.TP
.B GDBM_FILE_EOF
End of file was encountered where more data was expected to be
present. This error can occur when fetching data from the database
and usually means that the database is truncated or otherwise corrupted.
.sp
This error can be set by any GDBM function that does I/O. Some of
these functions are: \fBgdbm_delete\fR, \fBgdbm_exists\fR,
\fBgdbm_fetch\fR, \fBgdbm_export\fR, \fBgdbm_import\fR,
\fBgdbm_reorganize\fR, \fBgdbm_firstkey\fR, \fBgdbm_nextkey\fR,
\fBgdbm_store\fR.
.TP
.B GDBM_NO_DBNAME
Output database name is not specified. This error code is set by
\fBgdbm_load\fR if the first argument points to \fBNULL\fR and the
input file does not specify the database name.
.TP
.B GDBM_ERR_FILE_OWNER
This error code is set by \fBgdbm_load\fR if it is unable to restore
the database file owner. It is a mild error condition, meaning that
the data have been restored successfully, only changing the target file
owner failed. Inspect the system \fBerrno\fR variable to get a more
detailed diagnostics.
.TP
.B GDBM_ERR_FILE_MODE
This error code is set by \fBgdbm_load\fR if it is unable to restore
database file mode. It is a mild error condition, meaning that the data
have been restored successfully, only changing the target file owner
failed. Inspect the system \fBerrno\fR variable to get a more
detailed diagnostics.
.TP
.B GDBM_NEED_RECOVERY
Database is in inconsistent state and needs recovery. Call
\fBgdbm_recover\fR if you get this error.
.TP
.B GDBM_BACKUP_FAILED
The GDBM engine is unable to create backup copy of the file.
.TP
.B GDBM_DIR_OVERFLOW
Bucket directory would overflow the size limit during an attempt to split
hash bucket. This error can occur while storing a new key.
.TP
.B GDBM_BAD_BUCKET
Invalid index bucket is encountered in the database. Database
recovery is needed.
.TP
.B GDBM_BAD_HEADER
This error is set by \fBgdbm_open\fR and \fBgdbm_fd_open\fR, if the
first block read from the database file does not contain a valid GDBM
header.
.TP
.B GDBM_BAD_AVAIL
The available space stack is invalid. This error can be set by
\fBgdbm_open\fR and \fBgdbm_fd_open\fR, if the extended database
verification was requested (\fBGDBM_XVERIFY\fR). It is also set
by the \fBgdbm_avail_verify\fR function.
.sp
The database needs recovery.
.TP
.B GDBM_BAD_HASH_TABLE
Hash table in a bucket is invalid. This error can be set by the
following functions: \fBgdbm_delete\fR, \fBgdbm_exists\fR,
\fBgdbm_fetch\fR, \fBgdbm_firstkey\fR, \fBgdbm_nextkey\fR, and
\fBgdbm_store\fR.
.sp
The database needs recovery.
.TP
.B GDBM_BAD_DIR_ENTRY
Bad directory entry found in the bucket. The database recovery is
needed.
.TP
.B GDBM_FILE_CLOSE_ERROR
The \fBgdbm_close\fR function was unable to close the database file
descriptor. The system \fBerrno\fR variable contains the
corresponding error code.
.TP
.B GDBM_FILE_SYNC_ERROR
Cached content couldn't be synchronized to disk. Examine the
\fBerrno\fR variable to get more info,
.sp
Database recovery is needed.
.TP
.B GDBM_FILE_TRUNCATE_ERROR
File cannot be truncated. Examine the \fBerrno\fR variable to get
more info.
.sp
This error is set by \fBgdbm_open\fR and \fBgdbm_fd_open\fR when
called with the \fBGDBM_NEWDB\fR flag.
.TP
.B GDBM_BUCKET_CACHE_CORRUPTED
The bucket cache structure is corrupted. Database recovery is needed.
.TP
.B GDBM_BAD_HASH_ENTRY
This error is set during sequential access (@pxref{Sequential}), if
the next hash table entry does not contain the expected key. This
means that the bucket is malformed or corrupted and the database needs
recovery.
.TP
.B GDBM_ERR_SNAPSHOT_CLONE
Set by the \fBgdbm_failure_atomic\fR function if it was unable to
clone the database file into a snapshot. Inspect the system
\fBerrno\fR variable for the underlying cause of the error. If
\fBerrno\fR is \fBEINVAL\fR or \fBENOSYS\fR, crash tolerance
settings will be removed from the database.
.TP
.B GDBM_ERR_REALPATH
Set by the \fBgdbm_failure_atomic\fR function if the call to
\fBrealpath\fR function failed. \fBrealpath\fR is used to
determine actual path names of the snapshot files. Examine the system
\fBerrno\fR variable for details.
.TP
.B GDBM_ERR_USAGE
Function usage error. That includes invalid argument values, and the
like.
.SH DBM COMPATIBILITY ROUTINES
\fBGDBM\fR includes a compatibility library \fBlibgdbm_compat\fR, for
use with programs that expect traditional UNIX \fBdbm\fR or
\fBndbm\fR interfaces, such as, e.g. \fBSendmail\fR. The library is
optional and thus may be absent in some binary distributions.
.PP
As the detailed discussion of the compatibility API is beyond the scope
of this document, below we provide only a short reference. For
details, see the \fBGDBM Manual\fR, chapter \fBCompatibility with
standard dbm and ndbm\fR.
.SS DBM compatibility routines
In \fBdbm\fR compatibility mode only one file may be opened at a time.
All users are assumed to be writers. If the database file is read
only, it will fail as a writer, but will be opened as a reader. All
returned pointers in datum structures point to data that the
compatibility library \fBwill free\fR. They should be
treated as static pointers (as standard UNIX \fBdbm\fR does).
.PP
The following interfaces are provided:
.PP
.B #include
.sp
.BI "int dbminit (const char *" name ");"
.br
.BI "int store (datum " key ", datum " content );
.br
.BI "datum fetch (datum " key );
.br
.BI "int delete (datum " key );
.br
.BI "datum firstkey (void);"
.br
.BI "datum nextkey (datum " key );
.br
.BI "int dbmclose (void);"
.SS NDBM Compatibility routines:
In this mode, multiple databases can be opened. Each database is
identified by a handle of type \fBDBM *\fR. As in the original
\fBNDBM\fR, all returned pointers in datum structures point to data
that will be freed by the compatibility library. They should be
treated as static pointers.
.PP
The following interfaces are provided:
.PP
.B #include
.sp
.BI "DBM *dbm_open (const char *" name ", int " flags ", int " mode );
.br
.BI "void dbm_close (DBM *" file );
.br
.BI "datum dbm_fetch (DBM *" file ", datum " key );
.br
.BI "int dbm_store (DBM *" file ", datum " key ", datum " content ", int " flags );
.br
.BI "int dbm_delete (DBM *" file ", datum " key );
.br
.BI "datum dbm_firstkey (DBM *" file );
.br
.BI "datum dbm_nextkey (DBM *" file ", datum " key );
.br
.BI "int dbm_error (DBM *" file );
.br
.BI "int dbm_clearerr (DBM *" file );
.br
.BI "int dbm_pagfno (DBM *" file );
.br
.BI "int dbm_dirfno (DBM *" file );
.br
.BI "int dbm_rdonly (DBM *" file );
.SH LINKING
This library is accessed by specifying \fI\-lgdbm\fR as the last
parameter to the compile line, e.g.:
.sp
.nf
.in +5
gcc \-o prog prog.c \-lgdbm
.in
.fi
.PP
If you wish to use the \fBdbm\fR or \fBndbm\fR compatibility routines,
you must link in the \fIgdbm_compat\fR library as well. For example:
.sp
.nf
.in +5
gcc \-o prog proc.c \-lgdbm \-lgdbm_compat
.in
.fi
.\" .SH BUGS
.SH "BUG REPORTS"
Send bug reports to .
.SH "SEE ALSO"
.BR gdbm_dump (1),
.BR gdbm_load (1),
.BR gdbmtool (1).
.SH AUTHORS
by Philip A. Nelson, Jason Downs and Sergey Poznyakoff;
crash tolerance by Terence Kelly.
.SH COPYRIGHT
Copyright \(co 1990 - 2021 Free Software Foundation, Inc.
GDBM is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 1, or (at your option)
any later version.
GDBM is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with GDBM. If not, see
.SH CONTACTS
You may contact the original author by:
.br
e-mail: phil@cs.wwu.edu
.br
us-mail: Philip A. Nelson
.br
Computer Science Department
.br
Western Washington University
.br
Bellingham, WA 98226
You may contact the current maintainers by:
.br
e-mail: downsj@downsj.com
.br
and
e-mail: gray@gnu.org
For questions and feedback regarding crash tolerance, you may contact
Terence Kelly at:
.br
e-mail: tpkelly @ { acm.org, cs.princeton.edu, eecs.umich.edu }
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH GDBM 3 \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end:
gdbm-1.23/doc/fdl.texi 0000644 0001750 0001750 00000056031 14164261602 011505 0000000 0000000 @c The GNU Free Documentation License.
@center Version 1.3, 3 November 2008
@c This file is intended to be included within another document,
@c hence no sectioning command or @node.
@display
Copyright @copyright{} 2000--2002, 2007--2008, 2011, 2017--2022 Free
Software Foundation, Inc.
@uref{http://fsf.org/}
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@end display
@enumerate 0
@item
PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document @dfn{free} in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.
This License is a kind of ``copyleft'', which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
@item
APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License. Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein. The ``Document'', below,
refers to any such manual or work. Any member of the public is a
licensee, and is addressed as ``you''. You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.
A ``Modified Version'' of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A ``Secondary Section'' is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall
subject (or to related matters) and contains nothing that could fall
directly within that overall subject. (Thus, if the Document is in
part a textbook of mathematics, a Secondary Section may not explain
any mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
The ``Invariant Sections'' are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License. If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant
Sections then there are none.
The ``Cover Texts'' are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License. A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.
A ``Transparent'' copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text. A copy that is not ``Transparent'' is called ``Opaque''.
Examples of suitable formats for Transparent copies include plain
@sc{ascii} without markup, Texinfo input format, La@TeX{} input
format, @acronym{SGML} or @acronym{XML} using a publicly available
@acronym{DTD}, and standard-conforming simple @acronym{HTML},
PostScript or @acronym{PDF} designed for human modification. Examples
of transparent image formats include @acronym{PNG}, @acronym{XCF} and
@acronym{JPG}. Opaque formats include proprietary formats that can be
read and edited only by proprietary word processors, @acronym{SGML} or
@acronym{XML} for which the @acronym{DTD} and/or processing tools are
not generally available, and the machine-generated @acronym{HTML},
PostScript or @acronym{PDF} produced by some word processors for
output purposes only.
The ``Title Page'' means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
formats which do not have any title page as such, ``Title Page'' means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
The ``publisher'' means any person or entity that distributes copies
of the Document to the public.
A section ``Entitled XYZ'' means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language. (Here XYZ stands for a
specific section name mentioned below, such as ``Acknowledgements'',
``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
of such a section when you modify the Document means that it remains a
section ``Entitled XYZ'' according to this definition.
The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document. These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.
@item
VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
@item
COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent and
visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.
It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
@item
MODIFICATIONS
You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it. In addition, you must do these things in the Modified Version:
@enumerate A
@item
Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.
@item
List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has fewer than five),
unless they release you from this requirement.
@item
State on the Title page the name of the publisher of the
Modified Version, as the publisher.
@item
Preserve all the copyright notices of the Document.
@item
Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
@item
Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.
@item
Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice.
@item
Include an unaltered copy of this License.
@item
Preserve the section Entitled ``History'', Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
there is no section Entitled ``History'' in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
@item
Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the ``History'' section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
@item
For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
the Title of the section, and preserve in the section all the
substance and tone of each of the contributor acknowledgements and/or
dedications given therein.
@item
Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.
@item
Delete any section Entitled ``Endorsements''. Such a section
may not be included in the Modified Version.
@item
Do not retitle any existing section to be Entitled ``Endorsements'' or
to conflict in title with any Invariant Section.
@item
Preserve any Warranty Disclaimers.
@end enumerate
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
You may add a section Entitled ``Endorsements'', provided it contains
nothing but endorsements of your Modified Version by various
parties---for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
@item
COMBINING DOCUMENTS
You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled ``History''
in the various original documents, forming one section Entitled
``History''; likewise combine any sections Entitled ``Acknowledgements'',
and any sections Entitled ``Dedications''. You must delete all
sections Entitled ``Endorsements.''
@item
COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
@item
AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an ``aggregate'' if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation's users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.
@item
TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers. In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.
If a section in the Document is Entitled ``Acknowledgements'',
``Dedications'', or ``History'', the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.
@item
TERMINATION
You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense, or distribute it is void, and
will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license
from a particular copyright holder is reinstated (a) provisionally,
unless and until the copyright holder explicitly and finally
terminates your license, and (b) permanently, if the copyright holder
fails to notify you of the violation by some reasonable means prior to
60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, receipt of a copy of some or all of the same material does
not give you any rights to use it.
@item
FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
@uref{http://www.gnu.org/copyleft/}.
Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License ``or any later version'' applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation. If the Document
specifies that a proxy can decide which future versions of this
License can be used, that proxy's public statement of acceptance of a
version permanently authorizes you to choose that version for the
Document.
@item
RELICENSING
``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works. A
public wiki that anybody can edit is an example of such a server. A
``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
site means any set of copyrightable works thus published on the MMC
site.
``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
license published by Creative Commons Corporation, a not-for-profit
corporation with a principal place of business in San Francisco,
California, as well as future copyleft versions of that license
published by that same organization.
``Incorporate'' means to publish or republish a Document, in whole or
in part, as part of another Document.
An MMC is ``eligible for relicensing'' if it is licensed under this
License, and if all works that were first published under this License
somewhere other than this MMC, and subsequently incorporated in whole
or in part into the MMC, (1) had no cover texts or invariant sections,
and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site
under CC-BY-SA on the same site at any time before August 1, 2009,
provided the MMC is eligible for relicensing.
@end enumerate
@page
@heading ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
@smallexample
@group
Copyright (C) @var{year} @var{your name}.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
@end group
@end smallexample
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the ``with@dots{}Texts.'' line with this:
@smallexample
@group
with the Invariant Sections being @var{list their titles}, with
the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
being @var{list}.
@end group
@end smallexample
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
@c Local Variables:
@c ispell-local-pdict: "ispell-dict"
@c End:
gdbm-1.23/doc/stamp-vti 0000644 0001750 0001750 00000000140 14177231122 011700 0000000 0000000 @set UPDATED 2 January 2022
@set UPDATED-MONTH January 2022
@set EDITION 1.23
@set VERSION 1.23
gdbm-1.23/doc/Makefile.in 0000644 0001750 0001750 00000076705 14177231041 012122 0000000 0000000 # Makefile.in generated by automake 1.15 from Makefile.am.
# @configure_input@
# Copyright (C) 1994-2014 Free Software Foundation, Inc.
# This Makefile.in is free software; the Free Software Foundation
# gives unlimited permission to copy and/or distribute it,
# with or without modifications, as long as this notice is preserved.
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
# PARTICULAR PURPOSE.
@SET_MAKE@
# This file is part of GDBM. -*- Makefile -*-
# Copyright (C) 2007-2022 Free Software Foundation, Inc.
#
# GDBM is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3, or (at your option)
# any later version.
#
# GDBM is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with GDBM. If not, see . */
# Documentation
VPATH = @srcdir@
am__is_gnu_make = { \
if test -z '$(MAKELEVEL)'; then \
false; \
elif test -n '$(MAKE_HOST)'; then \
true; \
elif test -n '$(MAKE_VERSION)' && test -n '$(CURDIR)'; then \
true; \
else \
false; \
fi; \
}
am__make_running_with_option = \
case $${target_option-} in \
?) ;; \
*) echo "am__make_running_with_option: internal error: invalid" \
"target option '$${target_option-}' specified" >&2; \
exit 1;; \
esac; \
has_opt=no; \
sane_makeflags=$$MAKEFLAGS; \
if $(am__is_gnu_make); then \
sane_makeflags=$$MFLAGS; \
else \
case $$MAKEFLAGS in \
*\\[\ \ ]*) \
bs=\\; \
sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \
| sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \
esac; \
fi; \
skip_next=no; \
strip_trailopt () \
{ \
flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \
}; \
for flg in $$sane_makeflags; do \
test $$skip_next = yes && { skip_next=no; continue; }; \
case $$flg in \
*=*|--*) continue;; \
-*I) strip_trailopt 'I'; skip_next=yes;; \
-*I?*) strip_trailopt 'I';; \
-*O) strip_trailopt 'O'; skip_next=yes;; \
-*O?*) strip_trailopt 'O';; \
-*l) strip_trailopt 'l'; skip_next=yes;; \
-*l?*) strip_trailopt 'l';; \
-[dEDm]) skip_next=yes;; \
-[JT]) skip_next=yes;; \
esac; \
case $$flg in \
*$$target_option*) has_opt=yes; break;; \
esac; \
done; \
test $$has_opt = yes
am__make_dryrun = (target_option=n; $(am__make_running_with_option))
am__make_keepgoing = (target_option=k; $(am__make_running_with_option))
pkgdatadir = $(datadir)/@PACKAGE@
pkgincludedir = $(includedir)/@PACKAGE@
pkglibdir = $(libdir)/@PACKAGE@
pkglibexecdir = $(libexecdir)/@PACKAGE@
am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
install_sh_DATA = $(install_sh) -c -m 644
install_sh_PROGRAM = $(install_sh) -c
install_sh_SCRIPT = $(install_sh) -c
INSTALL_HEADER = $(INSTALL_DATA)
transform = $(program_transform_name)
NORMAL_INSTALL = :
PRE_INSTALL = :
POST_INSTALL = :
NORMAL_UNINSTALL = :
PRE_UNINSTALL = :
POST_UNINSTALL = :
build_triplet = @build@
host_triplet = @host@
subdir = doc
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
am__aclocal_m4_deps = $(top_srcdir)/m4/gettext.m4 \
$(top_srcdir)/m4/iconv.m4 $(top_srcdir)/m4/intlmacosx.m4 \
$(top_srcdir)/m4/lib-ld.m4 $(top_srcdir)/m4/lib-link.m4 \
$(top_srcdir)/m4/lib-prefix.m4 $(top_srcdir)/m4/libtool.m4 \
$(top_srcdir)/m4/longlong.m4 $(top_srcdir)/m4/ltoptions.m4 \
$(top_srcdir)/m4/ltsugar.m4 $(top_srcdir)/m4/ltversion.m4 \
$(top_srcdir)/m4/lt~obsolete.m4 $(top_srcdir)/m4/nls.m4 \
$(top_srcdir)/m4/po.m4 $(top_srcdir)/m4/progtest.m4 \
$(top_srcdir)/configure.ac
am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \
$(ACLOCAL_M4)
DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/version.texi \
$(srcdir)/stamp-vti $(am__DIST_COMMON)
mkinstalldirs = $(install_sh) -d
CONFIG_HEADER = $(top_builddir)/autoconf.h
CONFIG_CLEAN_FILES =
CONFIG_CLEAN_VPATH_FILES =
AM_V_P = $(am__v_P_@AM_V@)
am__v_P_ = $(am__v_P_@AM_DEFAULT_V@)
am__v_P_0 = false
am__v_P_1 = :
AM_V_GEN = $(am__v_GEN_@AM_V@)
am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@)
am__v_GEN_0 = @echo " GEN " $@;
am__v_GEN_1 =
AM_V_at = $(am__v_at_@AM_V@)
am__v_at_ = $(am__v_at_@AM_DEFAULT_V@)
am__v_at_0 = @
am__v_at_1 =
SOURCES =
DIST_SOURCES =
AM_V_DVIPS = $(am__v_DVIPS_@AM_V@)
am__v_DVIPS_ = $(am__v_DVIPS_@AM_DEFAULT_V@)
am__v_DVIPS_0 = @echo " DVIPS " $@;
am__v_DVIPS_1 =
AM_V_MAKEINFO = $(am__v_MAKEINFO_@AM_V@)
am__v_MAKEINFO_ = $(am__v_MAKEINFO_@AM_DEFAULT_V@)
am__v_MAKEINFO_0 = @echo " MAKEINFO" $@;
am__v_MAKEINFO_1 =
AM_V_INFOHTML = $(am__v_INFOHTML_@AM_V@)
am__v_INFOHTML_ = $(am__v_INFOHTML_@AM_DEFAULT_V@)
am__v_INFOHTML_0 = @echo " INFOHTML" $@;
am__v_INFOHTML_1 =
AM_V_TEXI2DVI = $(am__v_TEXI2DVI_@AM_V@)
am__v_TEXI2DVI_ = $(am__v_TEXI2DVI_@AM_DEFAULT_V@)
am__v_TEXI2DVI_0 = @echo " TEXI2DVI" $@;
am__v_TEXI2DVI_1 =
AM_V_TEXI2PDF = $(am__v_TEXI2PDF_@AM_V@)
am__v_TEXI2PDF_ = $(am__v_TEXI2PDF_@AM_DEFAULT_V@)
am__v_TEXI2PDF_0 = @echo " TEXI2PDF" $@;
am__v_TEXI2PDF_1 =
AM_V_texinfo = $(am__v_texinfo_@AM_V@)
am__v_texinfo_ = $(am__v_texinfo_@AM_DEFAULT_V@)
am__v_texinfo_0 = -q
am__v_texinfo_1 =
AM_V_texidevnull = $(am__v_texidevnull_@AM_V@)
am__v_texidevnull_ = $(am__v_texidevnull_@AM_DEFAULT_V@)
am__v_texidevnull_0 = > /dev/null
am__v_texidevnull_1 =
INFO_DEPS = $(srcdir)/gdbm.info
TEXINFO_TEX = $(top_srcdir)/build-aux/texinfo.tex
am__TEXINFO_TEX_DIR = $(top_srcdir)/build-aux
DVIS = gdbm.dvi
PDFS = gdbm.pdf
PSS = gdbm.ps
HTMLS = gdbm.html
TEXINFOS = gdbm.texi
TEXI2PDF = $(TEXI2DVI) --pdf --batch
MAKEINFOHTML = $(MAKEINFO) --html
AM_MAKEINFOHTMLFLAGS = $(AM_MAKEINFOFLAGS)
DVIPS = dvips
am__can_run_installinfo = \
case $$AM_UPDATE_INFO_DIR in \
n|no|NO) false;; \
*) (install-info --version) >/dev/null 2>&1;; \
esac
am__installdirs = "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)" \
"$(DESTDIR)$(man3dir)"
am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`;
am__vpath_adj = case $$p in \
$(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \
*) f=$$p;; \
esac;
am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`;
am__install_max = 40
am__nobase_strip_setup = \
srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'`
am__nobase_strip = \
for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||"
am__nobase_list = $(am__nobase_strip_setup); \
for p in $$list; do echo "$$p $$p"; done | \
sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \
$(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \
if (++n[$$2] == $(am__install_max)) \
{ print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \
END { for (dir in files) print dir, files[dir] }'
am__base_list = \
sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \
sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g'
am__uninstall_files_from_dir = { \
test -z "$$files" \
|| { test ! -d "$$dir" && test ! -f "$$dir" && test ! -r "$$dir"; } \
|| { echo " ( cd '$$dir' && rm -f" $$files ")"; \
$(am__cd) "$$dir" && rm -f $$files; }; \
}
man1dir = $(mandir)/man1
man3dir = $(mandir)/man3
NROFF = nroff
MANS = $(dist_man_MANS)
am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
am__DIST_COMMON = $(dist_man_MANS) $(gdbm_TEXINFOS) \
$(srcdir)/Makefile.in $(top_srcdir)/build-aux/mdate-sh \
$(top_srcdir)/build-aux/texinfo.tex
DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
ACLOCAL = @ACLOCAL@
AMTAR = @AMTAR@
AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@
AR = @AR@
AUTOCONF = @AUTOCONF@
AUTOHEADER = @AUTOHEADER@
AUTOM4TE = @AUTOM4TE@
AUTOMAKE = @AUTOMAKE@
AWK = @AWK@
BASE64_BIN = @BASE64_BIN@
BISON = @BISON@
CC = @CC@
CCDEPMODE = @CCDEPMODE@
CFLAGS = @CFLAGS@
COMPATINCLUDEDIR = @COMPATINCLUDEDIR@
CPP = @CPP@
CPPFLAGS = @CPPFLAGS@
CURSES_LIBS = @CURSES_LIBS@
CYGPATH_W = @CYGPATH_W@
DEFS = @DEFS@
DEPDIR = @DEPDIR@
DLLTOOL = @DLLTOOL@
DSYMUTIL = @DSYMUTIL@
DUMPBIN = @DUMPBIN@
ECHO_C = @ECHO_C@
ECHO_N = @ECHO_N@
ECHO_T = @ECHO_T@
EGREP = @EGREP@
EXEEXT = @EXEEXT@
FGREP = @FGREP@
FLEX = @FLEX@
GDBM_COUNT_T = @GDBM_COUNT_T@
GDBM_DEBUG_ENABLE = @GDBM_DEBUG_ENABLE@
GDBM_VERSION_MAJOR = @GDBM_VERSION_MAJOR@
GDBM_VERSION_MINOR = @GDBM_VERSION_MINOR@
GDBM_VERSION_PATCH = @GDBM_VERSION_PATCH@
GETTEXT_MACRO_VERSION = @GETTEXT_MACRO_VERSION@
GMSGFMT = @GMSGFMT@
GMSGFMT_015 = @GMSGFMT_015@
GREP = @GREP@
GZIP_BIN = @GZIP_BIN@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
INSTALL_SCRIPT = @INSTALL_SCRIPT@
INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
INTLLIBS = @INTLLIBS@
INTL_MACOSX_LIBS = @INTL_MACOSX_LIBS@
LD = @LD@
LDFLAGS = @LDFLAGS@
LFLAGS_DEBUG = @LFLAGS_DEBUG@
LIBICONV = @LIBICONV@
LIBINTL = @LIBINTL@
LIBOBJS = @LIBOBJS@
LIBS = @LIBS@
LIBTOOL = @LIBTOOL@
LIPO = @LIPO@
LN_S = @LN_S@
LTLIBICONV = @LTLIBICONV@
LTLIBINTL = @LTLIBINTL@
LTLIBOBJS = @LTLIBOBJS@
LT_SYS_LIBRARY_PATH = @LT_SYS_LIBRARY_PATH@
MAKEINFO = @MAKEINFO@
MANIFEST_TOOL = @MANIFEST_TOOL@
MKDIR_P = @MKDIR_P@
MSGFMT = @MSGFMT@
MSGFMT_015 = @MSGFMT_015@
MSGMERGE = @MSGMERGE@
NM = @NM@
NMEDIT = @NMEDIT@
OBJDUMP = @OBJDUMP@
OBJEXT = @OBJEXT@
OTOOL = @OTOOL@
OTOOL64 = @OTOOL64@
PACKAGE = @PACKAGE@
PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@
PACKAGE_NAME = @PACKAGE_NAME@
PACKAGE_STRING = @PACKAGE_STRING@
PACKAGE_TARNAME = @PACKAGE_TARNAME@
PACKAGE_URL = @PACKAGE_URL@
PACKAGE_VERSION = @PACKAGE_VERSION@
PATH_SEPARATOR = @PATH_SEPARATOR@
POSUB = @POSUB@
RANLIB = @RANLIB@
READLINE_LIBS = @READLINE_LIBS@
SED = @SED@
SET_MAKE = @SET_MAKE@
SHELL = @SHELL@
STRIP = @STRIP@
USE_NLS = @USE_NLS@
VERSION = @VERSION@
XGETTEXT = @XGETTEXT@
XGETTEXT_015 = @XGETTEXT_015@
XGETTEXT_EXTRA_OPTIONS = @XGETTEXT_EXTRA_OPTIONS@
YFLAGS_DEBUG = @YFLAGS_DEBUG@
abs_builddir = @abs_builddir@
abs_srcdir = @abs_srcdir@
abs_top_builddir = @abs_top_builddir@
abs_top_srcdir = @abs_top_srcdir@
ac_ct_AR = @ac_ct_AR@
ac_ct_CC = @ac_ct_CC@
ac_ct_DUMPBIN = @ac_ct_DUMPBIN@
am__include = @am__include@
am__leading_dot = @am__leading_dot@
am__quote = @am__quote@
am__tar = @am__tar@
am__untar = @am__untar@
bindir = @bindir@
build = @build@
build_alias = @build_alias@
build_cpu = @build_cpu@
build_os = @build_os@
build_vendor = @build_vendor@
builddir = @builddir@
datadir = @datadir@
datarootdir = @datarootdir@
docdir = @docdir@
dvidir = @dvidir@
exec_prefix = @exec_prefix@
host = @host@
host_alias = @host_alias@
host_cpu = @host_cpu@
host_os = @host_os@
host_vendor = @host_vendor@
htmldir = @htmldir@
includedir = @includedir@
infodir = @infodir@
install_sh = @install_sh@
libdir = @libdir@
libexecdir = @libexecdir@
localedir = @localedir@
localstatedir = @localstatedir@
mandir = @mandir@
mkdir_p = @mkdir_p@
oldincludedir = @oldincludedir@
pdfdir = @pdfdir@
prefix = @prefix@
program_transform_name = @program_transform_name@
psdir = @psdir@
sbindir = @sbindir@
sharedstatedir = @sharedstatedir@
srcdir = @srcdir@
sysconfdir = @sysconfdir@
target_alias = @target_alias@
top_build_prefix = @top_build_prefix@
top_builddir = @top_builddir@
top_srcdir = @top_srcdir@
info_TEXINFOS = gdbm.texi
gdbm_TEXINFOS = \
fdl.texi
dist_man_MANS = gdbm.3 gdbm_dump.1 gdbm_load.1 gdbmtool.1
GENDOCS = perl gendocs.pl
EXTRA_DIST = gendocs.pl webdoc.init htmlxref.cnf
TEXI2DVI = texi2dvi -t '@set $(RENDITION)'
all: all-am
.SUFFIXES:
.SUFFIXES: .dvi .html .info .pdf .ps .texi
$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps)
@for dep in $?; do \
case '$(am__configure_deps)' in \
*$$dep*) \
( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \
&& { if test -f $@; then exit 0; else break; fi; }; \
exit 1;; \
esac; \
done; \
echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnits doc/Makefile'; \
$(am__cd) $(top_srcdir) && \
$(AUTOMAKE) --gnits doc/Makefile
Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
@case '$?' in \
*config.status*) \
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \
*) \
echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \
cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \
esac;
$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(top_srcdir)/configure: $(am__configure_deps)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(ACLOCAL_M4): $(am__aclocal_m4_deps)
cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh
$(am__aclocal_m4_deps):
mostlyclean-libtool:
-rm -f *.lo
clean-libtool:
-rm -rf .libs _libs
.texi.info:
$(AM_V_MAKEINFO)restore=: && backupdir="$(am__leading_dot)am$$$$" && \
am__cwd=`pwd` && $(am__cd) $(srcdir) && \
rm -rf $$backupdir && mkdir $$backupdir && \
if ($(MAKEINFO) --version) >/dev/null 2>&1; then \
for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \
if test -f $$f; then mv $$f $$backupdir; restore=mv; else :; fi; \
done; \
else :; fi && \
cd "$$am__cwd"; \
if $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \
-o $@ $<; \
then \
rc=0; \
$(am__cd) $(srcdir); \
else \
rc=$$?; \
$(am__cd) $(srcdir) && \
$$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \
fi; \
rm -rf $$backupdir; exit $$rc
.texi.dvi:
$(AM_V_TEXI2DVI)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
$(TEXI2DVI) $(AM_V_texinfo) --build-dir=$(@:.dvi=.t2d) -o $@ $(AM_V_texidevnull) \
$<
.texi.pdf:
$(AM_V_TEXI2PDF)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
$(TEXI2PDF) $(AM_V_texinfo) --build-dir=$(@:.pdf=.t2p) -o $@ $(AM_V_texidevnull) \
$<
.texi.html:
$(AM_V_MAKEINFO)rm -rf $(@:.html=.htp)
$(AM_V_at)if $(MAKEINFOHTML) $(AM_MAKEINFOHTMLFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) \
-o $(@:.html=.htp) $<; \
then \
rm -rf $@ && mv $(@:.html=.htp) $@; \
else \
rm -rf $(@:.html=.htp); exit 1; \
fi
$(srcdir)/gdbm.info: gdbm.texi $(srcdir)/version.texi $(gdbm_TEXINFOS)
gdbm.dvi: gdbm.texi $(srcdir)/version.texi $(gdbm_TEXINFOS)
gdbm.pdf: gdbm.texi $(srcdir)/version.texi $(gdbm_TEXINFOS)
gdbm.html: gdbm.texi $(srcdir)/version.texi $(gdbm_TEXINFOS)
$(srcdir)/version.texi: $(srcdir)/stamp-vti
$(srcdir)/stamp-vti: gdbm.texi $(top_srcdir)/configure
@(dir=.; test -f ./gdbm.texi || dir=$(srcdir); \
set `$(SHELL) $(top_srcdir)/build-aux/mdate-sh $$dir/gdbm.texi`; \
echo "@set UPDATED $$1 $$2 $$3"; \
echo "@set UPDATED-MONTH $$2 $$3"; \
echo "@set EDITION $(VERSION)"; \
echo "@set VERSION $(VERSION)") > vti.tmp$$$$ && \
(cmp -s vti.tmp$$$$ $(srcdir)/version.texi \
|| (echo "Updating $(srcdir)/version.texi" && \
cp vti.tmp$$$$ $(srcdir)/version.texi.tmp$$$$ && \
mv $(srcdir)/version.texi.tmp$$$$ $(srcdir)/version.texi)) && \
rm -f vti.tmp$$$$ $(srcdir)/version.texi.$$$$
@cp $(srcdir)/version.texi $@
mostlyclean-vti:
-rm -f vti.tmp* $(srcdir)/version.texi.tmp*
maintainer-clean-vti:
-rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi
.dvi.ps:
$(AM_V_DVIPS)TEXINPUTS="$(am__TEXINFO_TEX_DIR)$(PATH_SEPARATOR)$$TEXINPUTS" \
$(DVIPS) $(AM_V_texinfo) -o $@ $<
uninstall-dvi-am:
@$(NORMAL_UNINSTALL)
@list='$(DVIS)'; test -n "$(dvidir)" || list=; \
for p in $$list; do \
$(am__strip_dir) \
echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \
rm -f "$(DESTDIR)$(dvidir)/$$f"; \
done
uninstall-html-am:
@$(NORMAL_UNINSTALL)
@list='$(HTMLS)'; test -n "$(htmldir)" || list=; \
for p in $$list; do \
$(am__strip_dir) \
echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \
rm -rf "$(DESTDIR)$(htmldir)/$$f"; \
done
uninstall-info-am:
@$(PRE_UNINSTALL)
@if test -d '$(DESTDIR)$(infodir)' && $(am__can_run_installinfo); then \
list='$(INFO_DEPS)'; \
for file in $$list; do \
relfile=`echo "$$file" | sed 's|^.*/||'`; \
echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \
if install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \
then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi; \
done; \
else :; fi
@$(NORMAL_UNINSTALL)
@list='$(INFO_DEPS)'; \
for file in $$list; do \
relfile=`echo "$$file" | sed 's|^.*/||'`; \
relfile_i=`echo "$$relfile" | sed 's|\.info$$||;s|$$|.i|'`; \
(if test -d "$(DESTDIR)$(infodir)" && cd "$(DESTDIR)$(infodir)"; then \
echo " cd '$(DESTDIR)$(infodir)' && rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]"; \
rm -f $$relfile $$relfile-[0-9] $$relfile-[0-9][0-9] $$relfile_i[0-9] $$relfile_i[0-9][0-9]; \
else :; fi); \
done
uninstall-pdf-am:
@$(NORMAL_UNINSTALL)
@list='$(PDFS)'; test -n "$(pdfdir)" || list=; \
for p in $$list; do \
$(am__strip_dir) \
echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \
rm -f "$(DESTDIR)$(pdfdir)/$$f"; \
done
uninstall-ps-am:
@$(NORMAL_UNINSTALL)
@list='$(PSS)'; test -n "$(psdir)" || list=; \
for p in $$list; do \
$(am__strip_dir) \
echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \
rm -f "$(DESTDIR)$(psdir)/$$f"; \
done
dist-info: $(INFO_DEPS)
@srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
list='$(INFO_DEPS)'; \
for base in $$list; do \
case $$base in \
$(srcdir)/*) base=`echo "$$base" | sed "s|^$$srcdirstrip/||"`;; \
esac; \
if test -f $$base; then d=.; else d=$(srcdir); fi; \
base_i=`echo "$$base" | sed 's|\.info$$||;s|$$|.i|'`; \
for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \
if test -f $$file; then \
relfile=`expr "$$file" : "$$d/\(.*\)"`; \
test -f "$(distdir)/$$relfile" || \
cp -p $$file "$(distdir)/$$relfile"; \
else :; fi; \
done; \
done
mostlyclean-aminfo:
-rm -rf gdbm.t2d gdbm.t2p
clean-aminfo:
-test -z "gdbm.dvi gdbm.pdf gdbm.ps gdbm.html" \
|| rm -rf gdbm.dvi gdbm.pdf gdbm.ps gdbm.html
maintainer-clean-aminfo:
@list='$(INFO_DEPS)'; for i in $$list; do \
i_i=`echo "$$i" | sed 's|\.info$$||;s|$$|.i|'`; \
echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \
rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \
done
install-man1: $(dist_man_MANS)
@$(NORMAL_INSTALL)
@list1=''; \
list2='$(dist_man_MANS)'; \
test -n "$(man1dir)" \
&& test -n "`echo $$list1$$list2`" \
|| exit 0; \
echo " $(MKDIR_P) '$(DESTDIR)$(man1dir)'"; \
$(MKDIR_P) "$(DESTDIR)$(man1dir)" || exit 1; \
{ for i in $$list1; do echo "$$i"; done; \
if test -n "$$list2"; then \
for i in $$list2; do echo "$$i"; done \
| sed -n '/\.1[a-z]*$$/p'; \
fi; \
} | while read p; do \
if test -f $$p; then d=; else d="$(srcdir)/"; fi; \
echo "$$d$$p"; echo "$$p"; \
done | \
sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
-e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \
sed 'N;N;s,\n, ,g' | { \
list=; while read file base inst; do \
if test "$$base" = "$$inst"; then list="$$list $$file"; else \
echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \
$(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst" || exit $$?; \
fi; \
done; \
for i in $$list; do echo "$$i"; done | $(am__base_list) | \
while read files; do \
test -z "$$files" || { \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man1dir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(man1dir)" || exit $$?; }; \
done; }
uninstall-man1:
@$(NORMAL_UNINSTALL)
@list=''; test -n "$(man1dir)" || exit 0; \
files=`{ for i in $$list; do echo "$$i"; done; \
l2='$(dist_man_MANS)'; for i in $$l2; do echo "$$i"; done | \
sed -n '/\.1[a-z]*$$/p'; \
} | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
-e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \
dir='$(DESTDIR)$(man1dir)'; $(am__uninstall_files_from_dir)
install-man3: $(dist_man_MANS)
@$(NORMAL_INSTALL)
@list1=''; \
list2='$(dist_man_MANS)'; \
test -n "$(man3dir)" \
&& test -n "`echo $$list1$$list2`" \
|| exit 0; \
echo " $(MKDIR_P) '$(DESTDIR)$(man3dir)'"; \
$(MKDIR_P) "$(DESTDIR)$(man3dir)" || exit 1; \
{ for i in $$list1; do echo "$$i"; done; \
if test -n "$$list2"; then \
for i in $$list2; do echo "$$i"; done \
| sed -n '/\.3[a-z]*$$/p'; \
fi; \
} | while read p; do \
if test -f $$p; then d=; else d="$(srcdir)/"; fi; \
echo "$$d$$p"; echo "$$p"; \
done | \
sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^3][0-9a-z]*$$,3,;x' \
-e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \
sed 'N;N;s,\n, ,g' | { \
list=; while read file base inst; do \
if test "$$base" = "$$inst"; then list="$$list $$file"; else \
echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man3dir)/$$inst'"; \
$(INSTALL_DATA) "$$file" "$(DESTDIR)$(man3dir)/$$inst" || exit $$?; \
fi; \
done; \
for i in $$list; do echo "$$i"; done | $(am__base_list) | \
while read files; do \
test -z "$$files" || { \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man3dir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(man3dir)" || exit $$?; }; \
done; }
uninstall-man3:
@$(NORMAL_UNINSTALL)
@list=''; test -n "$(man3dir)" || exit 0; \
files=`{ for i in $$list; do echo "$$i"; done; \
l2='$(dist_man_MANS)'; for i in $$l2; do echo "$$i"; done | \
sed -n '/\.3[a-z]*$$/p'; \
} | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^3][0-9a-z]*$$,3,;x' \
-e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \
dir='$(DESTDIR)$(man3dir)'; $(am__uninstall_files_from_dir)
tags TAGS:
ctags CTAGS:
cscope cscopelist:
distdir: $(DISTFILES)
@srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
list='$(DISTFILES)'; \
dist_files=`for file in $$list; do echo $$file; done | \
sed -e "s|^$$srcdirstrip/||;t" \
-e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \
case $$dist_files in \
*/*) $(MKDIR_P) `echo "$$dist_files" | \
sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \
sort -u` ;; \
esac; \
for file in $$dist_files; do \
if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
if test -d $$d/$$file; then \
dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \
if test -d "$(distdir)/$$file"; then \
find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
fi; \
if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \
find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \
fi; \
cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \
else \
test -f "$(distdir)/$$file" \
|| cp -p $$d/$$file "$(distdir)/$$file" \
|| exit 1; \
fi; \
done
$(MAKE) $(AM_MAKEFLAGS) \
top_distdir="$(top_distdir)" distdir="$(distdir)" \
dist-info
check-am: all-am
check: check-am
all-am: Makefile $(INFO_DEPS) $(MANS)
installdirs:
for dir in "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)" "$(DESTDIR)$(man3dir)"; do \
test -z "$$dir" || $(MKDIR_P) "$$dir"; \
done
install: install-am
install-exec: install-exec-am
install-data: install-data-am
uninstall: uninstall-am
install-am: all-am
@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
installcheck: installcheck-am
install-strip:
if test -z '$(STRIP)'; then \
$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
install; \
else \
$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
"INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \
fi
mostlyclean-generic:
clean-generic:
distclean-generic:
-test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES)
-test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES)
maintainer-clean-generic:
@echo "This command is intended for maintainers to use"
@echo "it deletes files that may require special tools to rebuild."
clean: clean-am
clean-am: clean-aminfo clean-generic clean-libtool mostlyclean-am
distclean: distclean-am
-rm -f Makefile
distclean-am: clean-am distclean-generic
dvi: dvi-am
dvi-am: $(DVIS)
html: html-am
html-am: $(HTMLS)
info: info-am
info-am: $(INFO_DEPS)
install-data-am: install-info-am install-man
install-dvi: install-dvi-am
install-dvi-am: $(DVIS)
@$(NORMAL_INSTALL)
@list='$(DVIS)'; test -n "$(dvidir)" || list=; \
if test -n "$$list"; then \
echo " $(MKDIR_P) '$(DESTDIR)$(dvidir)'"; \
$(MKDIR_P) "$(DESTDIR)$(dvidir)" || exit 1; \
fi; \
for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
echo "$$d$$p"; \
done | $(am__base_list) | \
while read files; do \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(dvidir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(dvidir)" || exit $$?; \
done
install-exec-am:
install-html: install-html-am
install-html-am: $(HTMLS)
@$(NORMAL_INSTALL)
@list='$(HTMLS)'; list2=; test -n "$(htmldir)" || list=; \
if test -n "$$list"; then \
echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)'"; \
$(MKDIR_P) "$(DESTDIR)$(htmldir)" || exit 1; \
fi; \
for p in $$list; do \
if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \
$(am__strip_dir) \
d2=$$d$$p; \
if test -d "$$d2"; then \
echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \
$(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \
echo " $(INSTALL_DATA) '$$d2'/* '$(DESTDIR)$(htmldir)/$$f'"; \
$(INSTALL_DATA) "$$d2"/* "$(DESTDIR)$(htmldir)/$$f" || exit $$?; \
else \
list2="$$list2 $$d2"; \
fi; \
done; \
test -z "$$list2" || { echo "$$list2" | $(am__base_list) | \
while read files; do \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \
done; }
install-info: install-info-am
install-info-am: $(INFO_DEPS)
@$(NORMAL_INSTALL)
@srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \
list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \
if test -n "$$list"; then \
echo " $(MKDIR_P) '$(DESTDIR)$(infodir)'"; \
$(MKDIR_P) "$(DESTDIR)$(infodir)" || exit 1; \
fi; \
for file in $$list; do \
case $$file in \
$(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \
esac; \
if test -f $$file; then d=.; else d=$(srcdir); fi; \
file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \
for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \
$$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \
if test -f $$ifile; then \
echo "$$ifile"; \
else : ; fi; \
done; \
done | $(am__base_list) | \
while read files; do \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(infodir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(infodir)" || exit $$?; done
@$(POST_INSTALL)
@if $(am__can_run_installinfo); then \
list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \
for file in $$list; do \
relfile=`echo "$$file" | sed 's|^.*/||'`; \
echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\
install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\
done; \
else : ; fi
install-man: install-man1 install-man3
install-pdf: install-pdf-am
install-pdf-am: $(PDFS)
@$(NORMAL_INSTALL)
@list='$(PDFS)'; test -n "$(pdfdir)" || list=; \
if test -n "$$list"; then \
echo " $(MKDIR_P) '$(DESTDIR)$(pdfdir)'"; \
$(MKDIR_P) "$(DESTDIR)$(pdfdir)" || exit 1; \
fi; \
for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
echo "$$d$$p"; \
done | $(am__base_list) | \
while read files; do \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pdfdir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(pdfdir)" || exit $$?; done
install-ps: install-ps-am
install-ps-am: $(PSS)
@$(NORMAL_INSTALL)
@list='$(PSS)'; test -n "$(psdir)" || list=; \
if test -n "$$list"; then \
echo " $(MKDIR_P) '$(DESTDIR)$(psdir)'"; \
$(MKDIR_P) "$(DESTDIR)$(psdir)" || exit 1; \
fi; \
for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
echo "$$d$$p"; \
done | $(am__base_list) | \
while read files; do \
echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(psdir)'"; \
$(INSTALL_DATA) $$files "$(DESTDIR)$(psdir)" || exit $$?; done
installcheck-am:
maintainer-clean: maintainer-clean-am
-rm -f Makefile
maintainer-clean-am: distclean-am maintainer-clean-aminfo \
maintainer-clean-generic maintainer-clean-vti
mostlyclean: mostlyclean-am
mostlyclean-am: mostlyclean-aminfo mostlyclean-generic \
mostlyclean-libtool mostlyclean-vti
pdf: pdf-am
pdf-am: $(PDFS)
ps: ps-am
ps-am: $(PSS)
uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \
uninstall-man uninstall-pdf-am uninstall-ps-am
uninstall-man: uninstall-man1 uninstall-man3
.MAKE: install-am install-strip
.PHONY: all all-am check check-am clean clean-aminfo clean-generic \
clean-libtool cscopelist-am ctags-am dist-info distclean \
distclean-generic distclean-libtool distdir dvi dvi-am html \
html-am info info-am install install-am install-data \
install-data-am install-dvi install-dvi-am install-exec \
install-exec-am install-html install-html-am install-info \
install-info-am install-man install-man1 install-man3 \
install-pdf install-pdf-am install-ps install-ps-am \
install-strip installcheck installcheck-am installdirs \
maintainer-clean maintainer-clean-aminfo \
maintainer-clean-generic maintainer-clean-vti mostlyclean \
mostlyclean-aminfo mostlyclean-generic mostlyclean-libtool \
mostlyclean-vti pdf pdf-am ps ps-am tags-am uninstall \
uninstall-am uninstall-dvi-am uninstall-html-am \
uninstall-info-am uninstall-man uninstall-man1 uninstall-man3 \
uninstall-pdf-am uninstall-ps-am
.PRECIOUS: Makefile
# Make sure you set TEXINPUTS.
# TEXINPUTS=/usr/share/texmf/pdftex/plain/misc/ is ok for most distributions
.PHONY: manual
manual:
rm -rf manual
TEXINPUTS=$(srcdir):$(top_srcdir)/build-aux:$(TEXINPUTS) \
MAKEINFO="$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS)" \
TEXI2DVI="$(TEXI2DVI) -t @finalout" \
$(GENDOCS) -C manual -o otherdoc.texi $(PACKAGE) otherdoc.texi.in
$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -DWEBDOC \
--html --init-file=webdoc.init $(info_TEXINFOS) -o manual
# Checking
check-tabs:
@if test -n "`cat $(info_TEXINFOS) $(gdbm_TEXINFOS) | tr -d -c '\t'`"; then \
echo "Sources contain tabs; run make untabify"; \
false; \
fi
check-sentence-spacing:
@if grep -q '\. [@A-Z]' $(info_TEXINFOS) $(gdbm_TEXINFOS); then \
echo >&2 "Sources contain single-space sentence separators"; \
echo >&2 "Run make fix-sentence-spacing to fix"; \
fi
check-fixmes:
@for file in $(info_TEXINFOS) $(gdbm_TEXINFOS); \
do \
sed -e = $$file | \
sed -n 'N;/@c *FIXME:/{s/\(^[0-9][0-9]*\).*@c *FIXME:\(.*\)/'$$file':\1: \2/gp}'; \
done > $@-t; \
if [ -s $@-t ]; then \
echo "Unresolved FIXMEs:"; \
cat $@-t; \
rm $@-t; \
false; \
else \
rm -f $@-t; \
fi
check-format: check-tabs check-sentence-spacing
check-docs: check-format check-fixmes
untabify:
emacs -batch -l untabify.el $(info_TEXINFOS) $(gdbm_TEXINFOS)
fix-sentence-spacing:
for file in $(info_TEXINFOS) $(gdbm_TEXINFOS); \
do \
if grep -q '\. [@A-Z]' $$file; then \
mv $$file $${file}~; \
sed -r 's/\. ([@A-Z])/. \1/g' $${file}~ > $$file; \
fi; \
done
final: untabify fix-sentence-spacing
# Tell versions [3.59,3.63) of GNU make to not export all variables.
# Otherwise a system limit (for SysV at least) may be exceeded.
.NOEXPORT:
gdbm-1.23/doc/gdbm.texi 0000644 0001750 0001750 00000446004 14164261602 011654 0000000 0000000 \input texinfo @c -*- Texinfo -*-
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename gdbm.info
@include version.texi
@settitle GDBM manual
@ifinfo
@dircategory Programming & development tools
@direntry
* GDBM: (gdbm). The GNU database manager.
* gdbm_dump: (gdbm) gdbm_dump. Dump the GDBM database into a flat file.
* gdbm_load: (gdbm) gdbm_load. Load the database from a flat file.
* gdbmtool: (gdbm) gdbmtool. Examine and modify a GDBM database.
@end direntry
@end ifinfo
@c @setchapternewpage odd
@comment %**end of header (This is for running Texinfo on a region.)
@c Use @kwindex for keywords
@defcodeindex kw
@syncodeindex kw cp
@c Use @flindex for files
@defcodeindex fl
@syncodeindex fl cp
@c Use @prindex for programs
@defcodeindex pr
@syncodeindex pr cp
@c Merge all indices into a single one
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp
@iftex
@finalout
@end iftex
@copying
Published by the Free Software Foundation,
51 Franklin Street, Fifth Floor
Boston, MA 02110-1301, USA
Copyright @copyright{} 1989--1999, 2007--2022 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
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover, and no Back-Cover texts.
A copy of the license is included in the section entitled ``GNU Free
Documentation License.''
@end copying
@titlepage
@sp 6
@center @titlefont{GNU dbm}
@sp 2
@center A Database Manager
@sp 2
@center by Philip A. Nelson, Jason Downs and Sergey Poznyakoff
@sp 4
@center Manual by Pierre Gaumond, Philip A. Nelson, Jason Downs,
@center Sergey Poznyakoff, and Terence Kelly
@sp 1
@center Edition @value{EDITION}
@sp 1
@center for GNU @command{dbm}, Version @value{VERSION}
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@ifnothtml
@page
@summarycontents
@page
@end ifnothtml
@contents
@ifnottex
@node Top
@top The GNU database manager
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
* Copying:: Your rights.
* Intro:: Introduction to GNU dbm.
Functions:
* Open:: Opening the database.
* Close:: Closing the database.
* Count:: Counting records in the database.
* Store:: Inserting and replacing records in the database.
* Fetch:: Searching records in the database.
* Delete:: Removing records from the database.
* Sequential:: Sequential access to records.
* Reorganization:: Database reorganization.
* Sync:: Insure all writes to disk have competed.
* Database format:: GDBM database formats.
* Flat files:: Export and import to Flat file format.
* Errors:: Error handling.
* Database consistency:: Structural and logical consistency.
* Recovery:: Recovery from fatal errors.
* Crash Tolerance:: Ensuring recovery to a consistent state.
* Options:: Setting internal options.
* Locking:: File locking.
* Variables:: Useful global variables.
* Additional functions:: Functions for verifying internal structures.
* Error codes:: Error codes returned by GDBM calls.
* Compatibility:: Compatibility with UNIX dbm and ndbm.
Programs
* gdbmtool:: Examine and modify a GDBM database.
* gdbm_dump:: Dump the database into a flat file.
* gdbm_load:: Load the database from a flat file.
* Exit codes:: Exit codes returned by GDBM utilities.
Other topics:
* Bugs:: Problems and bugs.
* Resources:: Additional resources,
* GNU Free Documentation License:: Document license.
* Index:: Index
@ifset WEBDOC
@ifhtml
* This Manual in Other Formats::
@end ifhtml
@end ifset
@detailmenu
--- The Detailed Node Listing ---
Compatibility with standard @command{dbm} and @command{ndbm}
* ndbm:: NDBM interface functions.
* dbm:: DBM interface functions.
Examine and modify a GDBM database
* invocation::
* shell::
gdbmtool interactive mode
* variables:: shell variables.
* commands:: shell commands.
* definitions:: how to define structured data.
* startup files::
@end detailmenu
@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 @command{dbm}
(@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 @command{GDBM} that they might get from
you.
Specifically, we want to make sure that you have the right to give
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 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 @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.
@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 @command{GDBM}.
@node Intro
@chapter Introduction to GNU @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. (@command{GDBM} is @emph{NOT} a
complete database package for an end user.)
@tpindex datum
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 @command{GDBM} is the structure:
@example
typedef struct
@{
char *dptr;
int dsize;
@} datum;
@end example
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. 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 @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 @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 @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 @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
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 @command{GDBM}
to look up a key in the database.
@example
#include
#include
#include
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
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 @command{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
@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 (*@var{fatal_func})(const char *))
Opens or creates a @command{GDBM} database file.
The arguments are:
@table @var
@item name
The name of the file (the complete name, @command{GDBM} does not append any
characters to this name).
@item block_size
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
@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 @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 @code{GDBM_WRITER}, the user wants both read and write access
to the database and requires exclusive access. If @code{flags} is set
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 @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. If an existing database file is opened with
the @code{GDBM_NEWDB} flag, the existing data are destroyed, and an
empty database structure is created in its place.
The following constants may also be logically or'd into the database
flags:
@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
@defvr {gdbm_open flag} GDBM_NOLOCK
Don't lock the database file. Use this flag if you intend to do
locking separately. @xref{Locking}.
@end defvr
@defvr {gdbm_open flag} GDBM_NOMMAP
Disable memory mapping mechanism. Note, that this degrades performance.
@end defvr
@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
pre-read and look-ups will operate on an in-memory copy. In
contrast, @code{GDBM_PREREAD} should not be used if you open a
database (even in read-only mode) only to do a couple of look-ups.
Finally, never use @code{GDBM_PREREAD} when opening a database for
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
@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 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
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 @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} (or @code{gdbm_fd_open}, described below).
@end deftypefn
@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 *))
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
@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},@
GDBM_FILE @var{src})
Copy file ownership and mode from @var{src} to @var{dst}.
@end deftypefn
@node Close
@chapter Closing the database
@cindex closing database
@cindex database, closing
It is important that every file opened is also closed. This is needed
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 @command{GDBM} file and frees all memory
associated with it. The parameter is:
@table @var
@item dbf
The pointer returned by @code{gdbm_open}.
@end table
@code{Gdbm_close} returns 0 on success. On error, it sets
@code{gdbm_errno} and system @code{errno} variables to the codes
describing the error and returns -1.
@end deftypefn
@node Count
@chapter Number of Records
@cindex number of records
@deftypefn {gdbm interface} int gdbm_count (GDBM_FILE @var{dbf}, @
gdbm_count_t *@var{pcount})
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.
@end deftypefn
@deftypefn {gdbm interface} int gdbm_bucket_count (GDBM_FILE @var{dbf}, @
size_t *@var{pcount})
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.
@end deftypefn
@node Store
@chapter Inserting and replacing records in the database
@cindex storing records
@cindex records, storing
@deftypefn {gdbm interface} int gdbm_store (GDBM_FILE @var{dbf}, datum @var{key}, @
datum @var{content}, int @var{flag})
The function @code{gdbm_store} inserts or replaces records in the database.
The parameters are:
@table @var
@item dbf
The pointer returned by @code{gdbm_open}.
@item key
The search key.
@item content
The data to be associated with the key.
@item flag
@kwindex GDBM_REPLACE
@kwindex GDBM_INSERT
Defines the action to take when the key is already in the database. The value
@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:
@table @asis
@item 0
Success. The value of @var{content} is keyed by @var{key} in the
database.
@item -1
An error occurred which prevented the item from being stored in the
database. Examine the @code{gdbm_errno} variable to determine the
actual cause of the error.
@item +1
The item was not stored because the argument @var{flag} was
@code{GDBM_INSERT} and the @var{key} was already in the database.
The @code{gdbm_errno} variable is set to @code{GDBM_CANNOT_REPLACE}.
@end table
If the function returns -1, @code{gdbm_errno} can have the following
values:
@table @code
@item GDBM_READER_CANT_STORE
Database was open in read-only mode, i.e. with the @code{GDBM_READER}
flag. @xref{Open}.
@item GDBM_MALFORMED_DATA
Either @var{key} or @var{content} had their @code{dptr} field set to
@code{NULL}.
It is OK to have a @dfn{zero-length} key or content, i.e. a datum with
@code{dsize} set to 0, but the @code{dptr} field must always be a
non-NULL value.
@item GDBM_BAD_HASH_TABLE
Database hash table is malformed. This usually means that some error
in the application or the library caused memory overrun. The database
is marked as needing recovery. All further calls on this database
will return with @code{gdbm_error} set to @code{GDBM_NEED_RECOVERY}.
@xref{Recovery}, for a discussion of database recovery process.
@item GDBM_BAD_DIR_ENTRY
Database directory entry is corrupted. The database is marked as
needing recovery. @xref{Recovery}.
@item GDBM_BAD_BUCKET
Database bucket is corrupted. The database is marked as
needing recovery. @xref{Recovery}.
@item GDBM_BAD_AVAIL
Database available storage index is corrupted. The database is marked as
needing recovery. @xref{Recovery}.
@item GDBM_FILE_SEEK_ERROR
A seek error occurred on the underlying disk file. Examine the system
@code{errno} variable for more detail.
@end table
@end deftypefn
If you store data for a @var{key} that is already in the data base,
@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 @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}).
@node Fetch
@chapter Searching for records in the database
@cindex fetching records
@cindex looking up records
@cindex record, fetching
@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 @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 @code{dptr} is @code{NULL}, inspect the value of the
@code{gdbm_errno} variable (@pxref{Variables,gdbm_errno}). If it is
@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.
The parameters are:
@table @var
@item dbf
The pointer returned by @code{gdbm_open}.
@item key
The search key.
@end table
@end deftypefn
An example of using this function:
@example
content = gdbm_fetch (dbf, key);
if (content.dptr == NULL)
@{
if (gdbm_errno == GDBM_ITEM_NOT_FOUND)
fprintf(stderr, "key not found\n");
else
fprintf(stderr, "error: %s\n", gdbm_db_strerror (dbf));
@}
else
@{
/* do something with content.dptr */
@}
@end example
@cindex records, testing existence
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 @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 @code{0} and sets @code{gdbm_errno} to a
non-@code{0} error code.
The parameters are:
@table @var
@item dbf
The pointer returned by @code{gdbm_open}.
@item key
The search key.
@end table
@end deftypefn
@node Delete
@chapter Removing records from the database
@cindex deleting records
@cindex record, deleting
To remove some data from the database, use the @code{gdbm_delete}
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 parameters are:
@table @var
@item dbf
The pointer returned by @code{gdbm_open}.
@item datum key
The search key.
@end table
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
@chapter Sequential access to records
@cindex sequential access
@cindex iterating over records
@cindex records, iterating over
The next two functions allow for accessing all items in the database. This
access is not @code{key} sequential, but it is guaranteed to visit every
@code{key} in the database once. The order has to do with the hash values.
@code{gdbm_firstkey} starts the visit of all keys in the database.
@code{gdbm_nextkey} finds and reads the next entry in the hash structure for
@code{dbf}.
@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 @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.
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 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 @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, @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 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:
@example
@group
key = gdbm_firstkey (dbf);
while (key.dptr)
@{
datum nextkey;
/* do something with the key */
...
/* Obtain the next key */
nextkey = gdbm_nextkey (dbf, key);
/* Reclaim the memory used by the key */
free (key.dptr);
/* Use nextkey in the next iteration. */
key = nextkey;
@}
@end group
@end example
@cindex iteration and @code{gdbm_delete}
@cindex deletion in iteration loops
@cindex @code{gdbm_delete} and sequential access
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
@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 or will be visited twice, if a loop like the
following is executed:
@example
@group
key = gdbm_firstkey (dbf);
while (key.dptr)
@{
datum nextkey;
if (some condition)
@{
gdbm_delete (dbf, key);
@}
nextkey = gdbm_nextkey (dbf, key);
free (key.dptr);
key = nextkey;
@}
@end group
@end example
@node Reorganization
@chapter Database reorganization
@cindex database reorganization
@cindex reorganization, database
The following function should be used very seldom.
@deftypefn {gdbm interface} int gdbm_reorganize (GDBM_FILE @var{dbf})
Reorganizes the database.
The parameter is:
@table @var
@item dbf
The pointer returned by @code{gdbm_open}.
@end table
@end deftypefn
If you have had a lot of deletions and would like to shrink the space
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
in the old file @var{dbf} into the new file. The new file is then renamed to
the same name as the old file and @var{dbf} is updated to contain all the
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.
@node Sync
@chapter Database Synchronization
@cindex database synchronization
@cindex synchronization, database
Normally, @command{GDBM} functions don't flush changed data to the
disk immediately after a change. This allows for faster writing of
databases at the risk of having a corrupted database if the
application terminates in an abnormal fashion. The following function
allows the programmer to make sure the disk version of the database
has been completely updated with all changes to the current time.
@deftypefn {gdbm interface} int gdbm_sync (GDBM_FILE @var{dbf})
Synchronizes the changes in @var{dbf} with its disk file. The
parameter is a pointer returned by @code{gdbm_open}.
This function would usually be called after a complete set of changes
have been made to the database and before some long waiting time.
This set of changes should preserve application-level invariants. In
other words, call @code{gdbm_sync} only when the database is in a
consistent state with regard to the application logic, a state from
which you are willing and able to recover. You can think about all
database operations between two consecutive @code{gdbm_sync} calls as
constituting a single @dfn{transaction}. @xref{Synchronizing the
Database}, for a detailed discussion about how to properly select
the synchronization points.
The @code{gdbm_close} function automatically calls the equivalent of
@code{gdbm_sync} so no call is needed if the database is to be closed
immediately after the set of changes have been made.
@code{Gdbm_sync} returns 0 on success. On error, it sets
@code{gdbm_errno} and system @code{errno} variables to the codes
describing the error and returns -1.
@end deftypefn
@kwindex GDBM_SYNC
Opening the database with @code{GDBM_SYNC} flag ensures that
@code{gdbm_sync} function will be called after each change, thereby
flushing the changes to disk immediately. You are advised against
using this flag, however, because it incurs a severe performance
penalty, while giving only a moderate guarantee that the
@emph{structural} consistency of the database will be preserved in case
of failure, and that only unless the failure occurs while being in the
@code{fsync} call. For the ways to ensure proper @emph{logical} consistency
of the database, see @ref{Crash Tolerance}.
@node Database format
@chapter Changing database format
As of version @value{VERSION}, @command{GDBM} supports databases in
two formats: @dfn{standard} and @dfn{extended}. The standard format
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, 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:
@deftypefn {gdbm interface} int gdbm_convert (GDBM_FILE @var{dbf}, @
int @var{flag})
Changes the format of the database file @var{dbf}. Allowed values for
@var{flag} are:
@table @code
@item 0
Convert database to the standard format.
@kwindex GDBM_NUMSYNC
@item GDBM_NUMSYNC
Convert database to the extended @dfn{numsync} format (@pxref{Numsync}).
@end table
On success, the function returns 0. In this case, it should be
followed by a call to @code{gdbm_sync} (@pxref{Sync}) or
@code{gdbm_close} (@pxref{Close}) to ensure the changes are written to
the disk.
On error, returns -1 and sets the @code{gdbm_errno} variable
(@pxref{Variables, gdbm_errno}).
If the database is already in the requested format, the function
returns success (0) without doing anything.
@end deftypefn
@node Flat files
@chapter Export and Import
@cindex Flat file format
@cindex export
@cindex import
@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 @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
key/value pairs as the database from which the flat file was created.
However, it will not constitute a byte-to-byte equivalent of the latter.
Various internal structures in the database can differ. In
particular, ordering of key/value pairs can be different and the table
of available file space will most probably differ, too. For databases
in extended format, the @code{numsync} counter will be reset to 0
(@pxref{Numsync}). These details are not visible to the application
programmer, and are mentioned here only for completeness sake.
The fact that the restored database contains the same set of key/value
pairs does not necessarily mean, however, that it can be used in the
same way as the original one. For example, if the original database
contained non-@acronym{ASCII} data (e.g.@: @acronym{C} structures,
integers etc.), the recreated database can be of any use only if the
target machine has the same integer size and byte ordering as the
source one and if its @acronym{C} compiler uses the same packing
conventions as the one which generated @acronym{C} which populated the
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.
@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. 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,
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.
We call a process of creating a flat file from a database
@dfn{exporting} or @dfn{dumping} this database. The reverse process,
creating the database from a flat file is called @dfn{importing} or
@dfn{loading} the database.
@deftypefn {gdbm interface} int gdbm_dump (GDBM_FILE @var{dbf}, @
const char *@var{filename}, int @var{format}, @
int @var{open_flags}, int @var{mode})
Dumps the database file to the named file in requested format.
Arguments are:
@table @var
@item dbf
A pointer to the source database, returned by a prior call to
@code{gdbm_open}.
@item filename
Name of the dump file.
@item format
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 @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 @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 (@pxref{open,,open a file,open(2), open(2) man page}).
@end table
@end deftypefn
@anchor{gdbm_load function}
@deftypefn {gdbm interface} int gdbm_load (GDBM_FILE *@var{pdbf}, @
const char *@var{filename}, int @var{flag}, @
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 @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 @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}).
The @var{meta_mask} argument 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:
@table @asis
@item GDBM_META_MASK_MODE
Do not restore file mode.
@item GDBM_META_MASK_OWNER
Do not restore file owner.
@end table
The function returns 0 upon successful completion or -1 on fatal
errors and 1 on mild (non-fatal) errors.
If a fatal error occurs, @code{gdbm_errno} will be set to one of the
following values:
@table @asis
@item GDBM_FILE_OPEN_ERROR
Input file (@var{filename}) cannot be opened. The @code{errno}
variable can be used to get more detail about the failure.
@item GDBM_MALLOC_ERROR
Not enough memory to load data.
@item GDBM_FILE_READ_ERROR
Reading from @var{filename} failed. The @code{errno} variable can be
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 @command{GDBM}
dump file. This often means that the dump file got corrupted
during the transfer.
The @code{GDBM_ILLEGAL_DATA} is an alias for this error code,
maintained for backward compatibility.
@item GDBM_ITEM_NOT_FOUND
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 @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 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
@kwindex GDBM_ERR_FILE_OWNER
@item GDBM_ERR_FILE_OWNER
The function was unable to restore database file owner.
@kwindex GDBM_ERR_FILE_MODE
@item GDBM_ERR_FILE_MODE
The function was unable to restore database file mode (permission bits).
@end table
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 @code{NULL}.
If the line information is not available or applicable, @var{errline}
will be set to @code{0}.
@end deftypefn
@deftypefn {gdbm interface} int gdbm_dump_to_file (GDBM_FILE @var{dbf}, @
FILE *@var{fp}, int @var{format})
This is an alternative entry point to @code{gdbm_dump} (which see).
Arguments are:
@table @var
@item dbf
A pointer to the source database, returned by a call to
@code{gdbm_open}.
@item fp
File to write the data to.
@item format
Format of the dump file. See the @var{format} argument to the
@code{gdbm_dump} function.
@end table
@end deftypefn
@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_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).
@end deftypefn
@deftypefn {gdbm interface} int gdbm_export (GDBM_FILE @var{dbf}, @
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 equivalent to
@example
gdbm_dump(@var{dbf}, @var{exportfile}, GDBM_DUMP_FMT_BINARY, @var{flag}, @var{mode})
@end example
@end deftypefn
@deftypefn {gdbm interface} int gdbm_export_to_file (GDBM_FILE @var{dbf}, FILE *@var{fp})
This is an alternative entry point to @code{gdbm_export}. This
function writes to file @var{fp} a binary dump of the database @var{dbf}.
@end deftypefn
@deftypefn {gdbm interface} int gdbm_import (GDBM_FILE @var{dbf}, @
const char *@var{importfile}, int @var{flag})
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:
@example
@var{dbf} = gdbm_open (@var{importfile}, 0,
@var{flag} == GDBM_REPLACE ?
GDBM_WRCREAT : GDBM_NEWDB,
0600, NULL);
gdbm_load (&@var{dbf}, @var{exportfile}, 0, @var{flag}, NULL)
@end example
@end deftypefn
@deftypefn {gdbm interface} int gdbm_import_from_file (GDBM_FILE @var{dbf}, @
FILE *@var{fp}, int @var{flag})
An alternative entry point to @code{gdbm_import}. Reads the binary
dump from the file @var{fp} and stores the key/value pairs to
@var{dbf}. @xref{Store}, for a description of @var{flag}.
This function is equivalent to:
@example
@var{dbf} = gdbm_open (@var{importfile}, 0,
@var{flag} == GDBM_REPLACE ?
GDBM_WRCREAT : GDBM_NEWDB,
0600, NULL);
gdbm_load_from_file (@var{dbf}, @var{fp}, @var{flag}, 0, NULL);
@end example
@end deftypefn
@node Errors
@chapter Error handling
@cindex gdbm_errno
@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 @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} (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 @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
@cindex most recent error code
@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 @command{GDBM} errors have an associated system error
code. The following are the ones that have:
@itemize @bullet
@item GDBM_FILE_OPEN_ERROR
@item GDBM_FILE_WRITE_ERROR
@item GDBM_FILE_SEEK_ERROR
@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.
@end deftypefn
@anchor{gdbm_check_syserr}
@deftypefn {gdbm interface} {int} gdbm_check_syserr (gdbm_errno @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
particular database file, use the @code{gdbm_db_strerror} function:
@deftypefn {gdbm interface} {const char *} gdbm_db_strerror (GDBM_FILE @var{dbf})
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
@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
@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 @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 @command{GDBM} functions for that
database file (except @code{gdbm_recover}), will return immediately
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})
Returns @code{1} if the database file @var{dbf} is in inconsistent
state and needs recovery.
@end deftypefn
To restore structural consistency of the database, use the
@code{gdbm_recover} function (@pxref{Recovery}).
Crash tolerance provides a better way of recovery, because it restores
both structural and logical consistency. @xref{Crash Tolerance}, for
a detailed discussion,
@node Database consistency
@chapter Database consistency
@cindex consistency, database
In the chapters that follow we will cover different aspects of
@dfn{database consistency} and ways to maintain it. Speaking
about consistency, it is important to distinguish between two different
aspects of it: structural and logical consistency.
@cindex structural consistency
@dfn{Structural consistency} means that all internal structures of the
database are in good order, contain valid data and are coherent with
one another. Structural consistency means that the database is in
good shape @dfn{technically}, but it does not imply that the data it
contains are in any way meaningful.
@cindex logical consistency
@dfn{Logical consistency} means that the data stored in the
database are coherent with respect to the application logic.
Usually this implies that structural consistency is observed as well.
For as long as the program is free from memory management errors and
each opened database is properly closed before the program terminates,
structural consistency is maintained. Maintaining logical consistency
is more complex task and its maintenance is entirely the
responsibility of the application programmer. @xref{Crash Tolerance},
for a detailed discussion.
Both consistency aspects can suffer as a result of both application
errors that cause the program to terminate prematurely without properly
saving the database, and hardware errors, such as disk failures or
power outages. When such situations occur, it becomes necessary to
@dfn{recover the database}.
In the next chapter we will discuss how to recover structural
consistency of a database.
@node Recovery
@chapter Recovering structural consistency
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
@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:
@deftypefn {gdbm interface} int gdbm_recover (GDBM_FILE @var{dbf},@
gdbm_recovery *@var{rcvr}, int @var{flags})
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}, 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
@var{flags}, in order to instruct the function to use it.
The @code{gdbm_recover} type is defined as:
@example
typedef struct gdbm_recovery_s
@{
/* Input members.
These are initialized before call to gdbm_recover.
The flags argument specifies which of them are initialized. */
void (*errfun) (void *data, char const *fmt, ...);
void *data;
size_t max_failed_keys;
size_t max_failed_buckets;
size_t max_failures;
/* Output members.
The gdbm_recover function fills these before returning. */
size_t recovered_keys;
size_t recovered_buckets;
size_t failed_keys;
size_t failed_buckets;
char *backup_name;
@} gdbm_recovery;
@end example
The @dfn{input members} modify the behavior of @code{gdbm_recover}:
@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. The @code{data} field of
@code{gdbm_recovery} will be passed to it as its first argument. The
@var{fmt} argument is a @code{printf}-like (@pxref{Format of the format string,,,printf(3), printf(3) man page}), 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.
@end deftypecv
@deftypecv {input member} gdbm_recovery size_t max_failed_keys
@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 becomes equal to @code{max_failed_keys}, recovery is
aborted and error is returned.
@end deftypecv
@deftypecv {input member} gdbm_recovery size_t max_failed_buckets
@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 becomes equal to
@code{max_failed_buckets}, recovery is aborted and error is returned.
@end deftypecv
@deftypecv {output member} gdbm_recovery size_t max_failures
@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 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
from the function:
@deftypecv {output member} gdbm_recovery size_t recovered_keys
Number of recovered keys.
@end deftypecv
@deftypecv {output member} gdbm_recovery size_t recovered_buckets
Number of recovered buckets.
@end deftypecv
@deftypecv {output member} gdbm_recovery size_t failed_keys
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 could not be retrieved.
@end deftypecv
@deftypecv {output member} gdbm_recovery {char *} backup_name
@kwindex GDBM_RCVR_BACKUP
Name of the file keeping the copy of the original database, in the
state prior to recovery. It is filled if the @var{GDBM_RCVR_BACKUP}
flag is set. The string is allocated using the @code{malloc} call.
The caller is responsible for freeing that memory when no longer needed.
@end deftypecv
@end deftypefn
@kwindex GDBM_RCVR_FORCE
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 perform database recovery
unconditionally.
@node Crash Tolerance
@chapter Crash Tolerance
Crash tolerance is a new (as of release 1.21) feature that can be
enabled at compile time, and used in environments with appropriate
support from the OS and the filesystem. As of version
@value{VERSION}, this means a Linux kernel 5.12.12 or later and
a filesystem that supports reflink copying, such as XFS, BtrFS, or
OCFS2. If these prerequisites are met, crash tolerance code will
be enabled automatically by the @command{configure} script when
building the package.
The crash-tolerance mechanism, when used correctly, guarantees that a
logically consistent (@pxref{Database consistency}) recent state of
application data can be recovered following a crash. Specifically, it
guarantees that the state of the database file corresponding to the
most recent successful @code{gdbm_sync} call can be recovered.
If the new mechanism is used correctly, crashes such as power
outages, OS kernel panics, and (some) application process crashes
will be tolerated. Non-tolerated failures include physical
destruction of storage devices and corruption due to bugs in
application logic. For example, the new mechanism won't help if a
pointer bug in your application corrupts @command{GDBM}'s private in-memory
data which in turn corrupts the database file.
In the following sections we will describe how to enable crash
tolerance in your application and what to do if a crash occurs.
The design rationale of the crash tolerance mechanism is described in
detail in the article, @cite{Crashproofing the Original NoSQL Key-Value
Store}, by Terence Kelly, @cite{ACM Queue magazine}, July/August 2021,
available from the @uref{https://queue.acm.org/DrillBits5/, ACM Digital Library}.
If you have difficulty retrieving this paper, please contact the
author at @email{tpkelly@@acm.org}, @email{tpkelly@@cs.princeton.edu},
or @email{tpkelly@@eecs.umich.edu}.
@node Filesystems supporting crash tolerance
@section Using Proper Filesystem
Use a filesystem that supports reflink copying. Currently XFS, BtrFS,
and OCFS2 support reflink. You can create such a filesystem if you
don't have one already. (Note that reflink support may require that
special options be specified at the time of filesystem creation; this
is true of XFS.) The most conventional way to create a filesystem is
on a dedicated storage device. However it is also possible to create
a filesystem @emph{within an ordinary file} on some other filesystem.
For example, the following commands, executed as root, will create a
smallish XFS filesystem inside a file on another filesystem:
@example
mkdir XFS
cd XFS
truncate --size 512m XFSfile
mkfs -t xfs -m crc=1 -m reflink=1 XFSfile
mkdir XFSmountpoint
mount -o loop XFSfile XFSmountpoint
@end example
The XFS filesystem is now available in directory
@file{XFSmountpoint}. Now, create a directory where your
unprivileged user account may create and delete files:
@example
cd XFSmountpoint
mkdir test
chown @var{user}:@var{group} test
@end example
@noindent
(where @var{user} and @var{group} are the user and group names of the
unprivileged account the application uses).
Reflink copying via @code{ioctl(FICLONE)} should work for files in and
below this directory. You can test reflink copying using the GNU
@command{cp} program:
@example
cp --reflink=always file1 file2
@end example
@xref{cp invocation, reflink, reflink, coreutils, @sc{gnu} Coreutils}.
Your GNU dbm database file and two @dfn{snapshot} files described below must
all reside on the same reflink-capable filesystem.
@node Enabling crash tolerance
@section Enabling crash tolerance
Open a GNU dbm database with @code{gdbm_open}. Whenever possible, use
the extended @command{GDBM} format (@pxref{Numsync}). Generally
speaking, this means using the @code{GDBM_NUMSYNC} flag when creating
the database. Unless you know what you are doing, do not specify
the @code{GDBM_SYNC} flag when opening the database. The reason is that
you want your application to explicitly control when @code{gdbm_sync}
is called; you don't want an implicit sync on every database
operation (@pxref{Sync}).
Request crash tolerance by invoking the following interface:
@example
int gdbm_failure_atomic (GDBM_FILE @var{dbf}, const char *@var{even},
const char *@var{odd});
@end example
The @var{even} and @var{odd} arguments are the pathnames of two files that
will be created and filled with @dfn{snapshots} of the database file.
These two files must not exist when @code{gdbm_failure_atomic} is
called and must reside on the same reflink-capable filesystem as the
database file.
After you call @code{gdbm_failure_atomic}, every call to
@code{gdbm_sync} will make an efficient reflink snapshot of the
database file in either the @var{even} or the @var{odd} snapshot file;
consecutive @code{gdbm_sync} calls alternate between the two, hence
the names. The permission bits and @code{mtime} timestamps on the
snapshot files determine which one contains the state of the database
file corresponding to the most recent successful @code{gdbm_sync}.
@xref{Crash recovery}, for discussion of crash recovery.
@node Synchronizing the Database
@section Synchronizing the Database
When your application knows that the state of the database is
consistent (i.e., all relevant application-level invariants hold),
you may call @code{gdbm_sync}. For example, if your application
manages bank accounts, transferring money from one account to another
should maintain the invariant that the sum of the two accounts is the
same before and after the transfer: It is correct to decrement account
@samp{A} by $7, increment account @samp{B} by $7, and then call
@code{gdbm_sync}. However it is @emph{not} correct to call
@code{gdbm_sync} @emph{between} the decrement of @samp{A} and the
increment of @samp{B}, because a crash immediately after that call
would destroy money. The general rule is simple, sensible, and
memorable: Call @code{gdbm_sync} only when the database is in a state
from which you are willing and able to recover following a crash. (If
you think about it you'll realize that there's never any other moment
when you'd really want to call @code{gdbm_sync}, regardless of whether
crash-tolerance is enabled. Why on earth would you push the state of
an inconsistent unrecoverable database down to durable media?).
@node Crash recovery
@section Crash recovery
If a crash occurs, the snapshot file (@var{even} or @var{odd})
containing the database state reflecting the most recent successful
@code{gdbm_sync} call is the snapshot file whose permission bits are
read-only and whose last-modification timestamp is greatest. If both
snapshot files are readable, we choose the one with the most recent
last-modification timestamp. Modern operating systems record
timestamps in nanoseconds, which gives sufficient confidence that the
timestamps of the two snapshots will differ. However, one can't rule
out the possibility that the two snapshot files will both be readable
and have identical timestamps@footnote{This can happen, for example,
if the storage is very fast and the system clock is low-resolution, or
if the system administrator sets the system clock backwards. In the
latter case one can end up with the most recent snapshot file having
modification time earlier than that of the obsolete snapshot.}. To
cope with this, @command{GDBM} version 1.21 introduced the new
@dfn{extended database format}, which stores in the database file
header the number of synchronizations performed so far. This number
can reliably be used to select the most recent snapshot, independently
of its timestamp. We strongly suggest using this new format when
writing crash-tolerant applications. @xref{Numsync}, for a detailed
discussion.
The @code{gdbm_latest_snapshot} function is provided, that selects the
right snapshot among the two. Invoke it as:
@example
@group
const char *recovery_file = NULL;
result = gdbm_latest_snapshot (even, odd, &recovery_file);
@end group
@end example
@noindent
where @var{even} and @var{odd} are names of the snapshot files. On
success, it stores the pointer to the most recent snapshot file name
in @var{recovery_file} and returns @code{GDBM_SNAPSHOT_OK}. To
finalize the recovery, rename this file to the name of your database
file and re-open it using @code{gdbm_open}. You should discard the
remaining snapshot.
If an error occurs, @code{gdbm_latest_snapshot} returns one of the
following error codes.
@defvr {gdbm_latest_snapshot} GDBM_SNAPSHOT_BAD
Neither snapshot file is readable. This means that the crash has occurred
before @code{gdbm_failure_atomic} completed. In this case, it is best
to fall back on a safe backup copy of the data file.
@end defvr
@defvr {gdbm_latest_snapshot} GDBM_SNAPSHOT_ERR
System error occurred in @code{gdbm_latest_snapshot}. Examine the
system @code{errno} variable for details. Its possible values are:
@table @code
@item EACCES
The file mode of one of the snapshot files was incorrect. Each snapshot
file can be either readable (0400) or writable (0200), but not both.
This probably means that someone touched one or both snapshot files
after the crash and before your attempt to recover from it. This case
needs additional investigation. If you're sure that the only change
someone made to the files is altering their modes, and your database
is in @dfn{numsync} format (@pxref{Numsync}), you can reset the modes
to 0400 and retry the recovery.
This error can also be returned by underlying @code{stat} call,
meaning that search permission was denied for one of the directories
in the path prefix of a snapshot file name. That again means that
someone has messed with permissions after the crash.
@item EINVAL
Some arguments passed to @code{gdbm_latest_snapshot} were not valid.
It is a programmer's error which means that your application needs to be
fixed.
@item ENOSYS
Function is not implemented. This means @command{GDBM} was built without
crash-tolerance support.
@item Other value (@code{EBADF}, @code{EFAULT}, etc)
An error occurred when trying to @code{stat} the snapshot file.
@xref{ERRORS,,,stat(2),stat(2) man page}, for a discussion of
possible @code{errno} values.
@end table
@end defvr
@defvr {gdbm_latest_snapshot} GDBM_SNAPSHOT_SAME
File modes and modification dates of both snapshot files are exactly
the same. This can happen only if numsync is not available
(@pxref{Numsync}).
@end defvr
@defvr {gdbm_latest_snapshot} GDBM_SNAPSHOT_SUSPICIOUS
For the database in extended @dfn{numsync} format (@pxref{Numsync}):
the @code{numsync} values of the two snapshot differ by more than
one. Check the arguments to the @code{gdbm_latest_snapshot} function.
The most probably reason of such an error is that the @var{even} and
@var{odd} parameters point to snapshot files belonging to different
database files.
@end defvr
If you get any of these errors, we strongly suggest to undertake
@dfn{manual recovery}.
@node Manual crash recovery
@section Manual crash recovery
@dfn{Manual recovery} is usually performed with the help of the
@command{gdbmtool} utility. Start @command{gdbmtool} in read-only
mode (the @option{-r}) option. Once in the command shell, issue the
following command:
@example
snapshot @var{a} @var{b}
@end example
@noindent
where @var{a} and @var{b} are names of the two snapshot files you
configured using the @code{gdbm_failure_atomic} function. This
command investigates both files and prints out detailed
diagnostics.
Its output begins with a line listing one of the error codes above,
followed by a colon and a textual description of the error. The lines
that follow show details for each snapshot file.
Each snapshot description begins with the snapshot file name followed
by a colon and four fields, in this order:
@enumerate 1
@item File permission bits in octal.
@item File permission bits in @command{ls -l} notation.
@item Modification timestamp.
@item Numsync counter.
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
Any errors or inconsistencies discovered are reported in the lines
that follow, one error per line. Here's an example of the
@command{snapshot} command output, describing the
@code{GDBM_SNAPSHOT_ERR} condition:
@example
@group
gdbmtool> snapshot even.dbf odd.dbf
GDBM_SNAPSHOT_ERR: Error selecting snapshot.
even.dbf: 200 -w------- 1627820627.485681330 ?
odd.dbf: 600 rw------- 1627820627.689503918 301
odd.dbf: ERROR: bad file mode
@end group
@end example
Line 2 lists the meta-data of the snapshot @file{even.dbf}. The
@code{numsync} field contains question mark because the file
permissions (write-only) prevented @command{gdbmtool} from opening it.
The lines for @file{odd.dbf} show the actual reason for the error: bad
file mode (read-write). Apparently, the file mode has been changed
manually after the crash. The timestamp of the file, which is more
recent than that of @file{even.dbf}, suggests that it might be used for
recovery. To confirm this guess, change the mode of the
@file{even.dbf} to read-only and repeat the @command{snapshot} command:
@example
@group
gdbmtool> ! chmod 400 even.dbf
gdbmtool> snapshot even.dbf odd.dbf
GDBM_SNAPSHOT_ERR: Error selecting snapshot.
even.dbf: 400 r-------- 1627820627.485681330 300
odd.dbf: 600 rw------- 1627820627.689503918 301
odd.dbf: ERROR: bad file mode
@end group
@end example
This shows the numsync value of the @file{even.dbf} file, which is
exactly one less than that of @file{odd.dbf}. This means that the
latter should be selected for recovery.
For completeness sake, you can change the mode of @file{odd.dbf} to
read-only as well and repeat the @command{snapshot} command. In this
case you will see:
@example
@group
gdbmtool> ! chmod 400 odd.dbf
gdbmtool> snapshot even.dbf odd.dbf
GDBM_SNAPSHOT_OK: Selected the most recent snapshot.
odd.dbf: 400 r-------- 1627820627.689503918 301
@end group
@end example
@node Performance Impact
@section Performance Impact
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 @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
between consecutive calls to @code{gdbm_sync}.
@node Availability
@section Availability
To ensure that application data can survive the failure of one or
more storage devices, replicated storage (e.g., RAID) may be used
beneath the reflink-capable filesystem. Some cloud providers offer
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 @command{GDBM}.
@node Numsync
@section Numsync Extension
In @ref{Crash recovery}, we have shown that for database recovery,
one should select the snapshot whose permission bits are read-only and
whose last-modification timestamp is greatest. However, there may be
cases when a crash occurs at such a time that both snapshot files
remain readable. It may also happen, that their permissions had
been reset to read-only and/or modification times inadvertently
changed before recovery. To make it possible to select the right
snapshot in such cases, a new @dfn{extended database format} was
introduced in @command{GDBM} version 1.21. This format adds to the
database header the @code{numsync} field, which holds the number of
synchronizations the database underwent before being closed or
abandoned due to a crash.
A readable snapshot is a consistent copy of the database at a given point of
time. Thus, if both snapshots of a database in extended format are
readable, it will suffice to examine their @code{numsync} counters
and select the one whose @code{numsync} is greater. That's what
the @code{gdbm_latest_snapshot} function does in this case.
It is worth noticing, that the two counters should differ exactly by
one. If the difference is greater than that, @code{gdbm_latest_snapshot}
will return a special status code, @code{GDBM_SNAPSHOT_SUSPICIOUS}.
If, during a recovery attempt, you get this status code, we recommend
to proceed with the manual recovery (@pxref{Manual crash recovery}).
To create a database in extended format, call @code{gdbm_open} with
both @code{GDBM_NEWDB} and @code{GDBM_NUMSYNC} flags:
@example
dbf = gdbm_open(dbfile, 0, GDBM_NEWDB|GDBM_NUMSYNC, 0600, NULL);
@end example
@noindent
Notice, that this flag must always be used together with
@code{GDBM_NEWDB} (@pxref{Open}). It is silently ignored when used
together with another opening flag.
A standard @command{GDBM} database can be converted to the extended
format and vice versa. To convert an existing database to the
extended format, use the @code{gdbm_convert} function (@pxref{Database
format}):
@example
rc = gdbm_convert(dbf, GDBM_NUMSYNC);
@end example
You can do the same using the @command{gdbmtool} utility
(@pxref{commands, upgrade}):
@example
gdbmtool @var{dbname} upgrade
@end example
To convert a database from extended format back to the standard
@command{GDBM} format, do:
@example
rc = gdbm_convert(dbf, 0);
@end example
To do the same from the command line, run:
@example
gdbmtool @var{dbname} downgrade
@end example
@node Crash Tolerance API
@section Crash Tolerance API
@deftypefn {gdbm interface} int gdbm_failure_atomic (GDBM_FILE @var{dbf}, @
const char *@var{even}, const char *@var{odd})
Enables crash tolerance for the database file @var{dbf}. The
@var{even} and @var{odd} arguments are the pathnames of two files that
will be created and filled with snapshots of the database file.
These two files must not exist when @code{gdbm_failure_atomic} is
called and must reside on the same reflink-capable filesystem as the
database file.
Returns 0 on success. On failure, returns -1 and sets
@code{gdbm_errno} to one of the following values:
@table @code
@item GDBM_ERR_USAGE
Improper function usage. Either @var{even} or @var{odd} is
@code{NULL}, or they point to the same string.
@item GDBM_NEED_RECOVERY
The database needs recovery. @xref{Recovery}.
@item GDBM_ERR_SNAPSHOT_CLONE
Failed to clone the database file into a snapshot. Examine the system
@code{errno} variable for details.
@end table
If one of the following error codes is returned, examine the system
@code{errno} variable for details:
@table @code
@item GDBM_ERR_REALPATH
Call to @code{realpath} function failed. @code{realpath} is used to
determine actual path names of the snapshot files.
@item GDBM_FILE_OPEN_ERROR
Unable to create snapshot file.
@item GDBM_FILE_SYNC_ERROR
Failed to sync a snapshot file or one of directories in its pathname,
during initial synchronization.
@item GDBM_FILE_CLOSE_ERROR
Failed to close a snapshot file or one of directories in its pathname,
during initial synchronization.
@item GDBM_ERR_FILE_MODE
The @code{fchmod} call on one of the snapshot files failed.
@end table
Notes:
@itemize @bullet
@item It is not an error to call @code{gdbm_failure_atomic} several times.
Each subsequent call closes the previously configured snapshot files
and installs new ones instead.
@item Crash tolerance settings are cleared by functions
@code{gdbm_recover} (@pxref{Recovery}) and @code{gdbm_reorganize}
(@pxref{Reorganization}). In case of @code{gdbm_recover}, it should
not be a problem, because if you enabled crash tolerance, the
procedure described in @ref{Crash recovery} is the preferred way of
recovering the database. If, however, you decided to call either
function even though you had enabled crash tolerance previously, be
sure to call @code{gdbm_failure_atomic} again with the same arguments
as before (provided that the call returns successfully).
@end itemize
@end deftypefn
@deftypefn {gdbm interface} int gdbm_latest_snapshot (const char *@var{even}, @
const char *@var{odd}, const char **@var{retval})
@kwindex GDBM_SNAPSHOT_OK
@kwindex GDBM_SNAPSHOT_BAD
@kwindex GDBM_SNAPSHOT_ERR
@kwindex GDBM_SNAPSHOT_SAME
Selects between two snapshots, @var{even} and @var{odd}, the one to be
used for crash recovery. On success, stores a pointer to the selected
filename in the memory location pointed to by @var{retval} and returns
@code{GDBM_SNAPSHOT_OK}. If neither snapshot file is usable, the
function returns @code{GDBM_SNAPSHOT_BAD}. If a system error occurs, it
returns @code{GDBM_SNAPSHOT_ERR} and sets @code{errno} to the error code
describing the problem. Finally, in the unlikely case that it cannot
select between the two snapshots (this means they are both readable
and have exactly the same @code{mtime} timestamp), the function returns
@code{GDBM_SNAPSHOT_SAME}.
@kwindex GDBM_SNAPSHOT_SUSPICIOUS
If the @samp{numsync} extension is enabled (@pxref{Numsync}), the
function can also return the @code{GDBM_SNAPSHOT_SUSPICIOUS} status
code. This happens when the @code{numsync} counters in the two
snapshots differ by more than one.
@xref{Crash recovery}, for a detailed description of possible return
codes and their interpretation.
If any value other than @code{GDBM_SNAPSHOT_OK} is returned, it is
guaranteed that the function did not touch @var{retval}. In this case
it is recommended to switch to manual recovery procedure, letting the
user examine the snapshots and take the appropriate action.
@pxref{Manual crash recovery}, for details.
@end deftypefn
@node Options
@chapter Setting options
@cindex database options
@cindex options, database
@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}, @
void *@var{value}, int @var{size})
Sets an option on the database or returns the value of an option.
The parameters are:
@table @var
@item dbf
The pointer returned by @code{gdbm_open}.
@item option
The option to be set or retrieved.
@item value
A pointer to the value to which @var{option} will be set or where to
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:
@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 adjust the cache size
automatically.
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
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:
@example
size_t bn;
gdbm_bucket_count (dbf, &bn);
ret = gdbm_setopt (dbf, GDBM_SETCACHESIZE, &bn, sizeof (bn));
@end example
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
@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
@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}}.
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}.
@end defvr
@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
turn it off.
Note, that this option is a reverse of @code{GDBM_FASTMODE},
i.e.@: calling @code{GDBM_SETSYNCMODE} with @code{TRUE} has the same effect
as calling @code{GDBM_FASTMODE} with @code{FALSE}.
The @code{GDBM_SYNCMODE} option is provided for compatibility with
earlier versions.
@end defvr
@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
@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,
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
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
@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
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
to an integer: @code{TRUE} to turn free block merging on, and @code{FALSE} to
turn it off.
@end defvr
@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
@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
@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
@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
@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
@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
responsible for freeing this memory when no longer needed. For
example:
@example
char *name;
if (gdbm_setopt (dbf, GDBM_GETDBNAME, &name, sizeof (name)))
@{
fprintf (stderr, "gdbm_setopt failed: %s\n",
gdbm_strerror (gdbm_errno));
@}
else
@{
printf ("database name: %s\n", name);
free (name);
@}
@end example
@end defvr
@defvr {Option} GDBM_GETBLOCKSIZE
Return the block size in bytes. The @var{value} should point to @code{int}.
@end defvr
@node Locking
@chapter File Locking
@cindex locking
@kwindex GDBM_NOLOCK
With locking disabled (if @code{gdbm_open} was called with @code{GDBM_NOLOCK}),
the user may want 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 @code{gdbm_fdesc} routine is provided.
@deftypefn {gdbm interface} int gdbm_fdesc (GDBM_FILE @var{dbf})
Returns the file descriptor of the database @var{dbf}. This value
can be used as an argument to @code{flock}, @code{lockf} or similar
calls.
@end deftypefn
@node Variables
@chapter Useful global variables
The following global variables and constants are available:
@deftypevar gdbm_error gdbm_errno
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.
Use @code{gdbm_strerror} (@pxref{Errors}) to convert it to a
descriptive text.
@end deftypevar
@deftypevar {const char *} gdbm_errlist[]
This variable is an array of error descriptions, which is used by
@code{gdbm_strerror} to convert error codes to human-readable text
(@pxref{Errors}). You can access it directly, if you wish so. It
contains @code{_GDBM_MAX_ERRNO + 1} elements and can be directly
indexed by the error code to obtain a corresponding descriptive
text.
@end deftypevar
@deftypevar {int const} gdbm_syserr[]
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 @command{GDBM}.
@end defvr
@defvr {Constant} _GDBM_MAX_ERRNO
The maximum error code used by @command{GDBM}.
@end defvr
@cindex version number
@deftypevar {const char *} gdbm_version
A string containing the version information.
@end deftypevar
@deftypevar {int const} gdbm_version_number[3]
This variable contains the @command{GDBM} version numbers:
@multitable @columnfractions 0.4 0.5
@headitem Index @tab Meaning
@item 0 @tab Major number
@item 1 @tab Minor number
@item 2 @tab Patchlevel number
@end multitable
Additionally, the following constants are defined in the @file{gdbm.h}
file:
@table @asis
@kwindex GDBM_VERSION_MAJOR
@item GDBM_VERSION_MAJOR
Major number.
@kwindex GDBM_VERSION_MINOR
@item GDBM_VERSION_MINOR
Minor number.
@kwindex GDBM_VERSION_PATCH
@item GDBM_VERSION_PATCH
Patchlevel number.
@end table
These can be used to verify whether the header file matches the library.
@end deftypevar
To compare two split-out version numbers, use the following function:
@deftypefn {gdbm interface} int gdbm_version_cmp (int const @var{a}[3], @
int const @var{b}[3])
Compare two version numbers. Return @code{-1} if @var{a} is less than
@var{b}, @code{1} if @var{a} is greater than @var{b} and @code{0} if
they are equal.
Comparison is done from left to right, so that:
@example
a = @{ 1, 8, 3 @};
b = @{ 1, 8, 3 @};
gdbm_version_cmp (a, b) @result{} 0
a = @{ 1, 8, 3 @};
b = @{ 1, 8, 2 @};
gdbm_version_cmp (a, b) @result{} 1
a = @{ 1, 8, 3 @};
b = @{ 1, 9. 0 @};
gdbm_version_cmp (a, b) @result{} -1
@end example
@end deftypefn
@node Additional functions
@chapter Additional functions
@deftypefn {gdbm interface} int gdbm_avail_verify (GDBM_FILE @var{dbf})
Verify if the available block stack is in consistent state. On
success, returns 0. If any errors are encountered, sets the
@code{gdbm_errno} to @code{GDBM_BAD_AVAIL}, marks the database as
needing recovery (@pxref{Recovery}) and return -1.
@end deftypefn
@node Error codes
@chapter Error codes
@cindex error codes
This chapter summarizes error codes which can be set by the
functions in @command{GDBM} library.
@defvr {Error Code} GDBM_NO_ERROR
No error occurred.
@end defvr
@defvr {Error Code} GDBM_MALLOC_ERROR
Memory allocation failed. Not enough memory.
@end defvr
@defvr {Error Code} GDBM_BLOCK_SIZE_ERROR
@kwindex GDBM_BSEXACT
This error is set by the @code{gdbm_open} function (@pxref{Open}), if
the value of its @var{block_size} argument is incorrect and the
@code{GDBM_BSEXACT} flag is set.
@end defvr
@defvr {Error Code} GDBM_FILE_OPEN_ERROR
The library was not able to open a disk file. This can be set by
@code{gdbm_open} (@pxref{Open}), @code{gdbm_dump} (@code{gdbm_export}) and
@code{gdbm_load} (@code{gdbm_import}) functions (@pxref{Flat files}).
Inspect the value of the system @code{errno} variable to get more
detailed diagnostics.
@end defvr
@defvr {Error Code} GDBM_FILE_WRITE_ERROR
Writing to a disk file failed. This can be set by
@code{gdbm_open} (@pxref{Open}), @code{gdbm_dump} (@code{gdbm_export}) and
@code{gdbm_load} (@code{gdbm_import}) functions.
Inspect the value of the system @code{errno} variable to get more
detailed diagnostics.
@end defvr
@defvr {Error Code} GDBM_FILE_SEEK_ERROR
Positioning in a disk file failed. This can be set by
@code{gdbm_open} (@pxref{Open}) function.
Inspect the value of the system @code{errno} variable to get a more
detailed diagnostics.
@end defvr
@defvr {Error Code} GDBM_FILE_READ_ERROR
Reading from a disk file failed. This can be set by
@code{gdbm_open} (@pxref{Open}), @code{gdbm_dump} (@code{gdbm_export}) and
@code{gdbm_load} (@code{gdbm_import}) functions.
Inspect the value of the system @code{errno} variable to get a more
detailed diagnostics.
@end defvr
@defvr {Error Code} GDBM_BAD_MAGIC_NUMBER
The file given as argument to @code{gdbm_open} function is not a valid
@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
@command{GDBM} file: it has zero length.
@end defvr
@defvr {Error Code} GDBM_CANT_BE_READER
This error code is set by the @code{gdbm_open} function if it is not
able to lock file when called in @code{GDBM_READER} mode (@pxref{Open,
GDBM_READER}).
@end defvr
@defvr {Error Code} GDBM_CANT_BE_WRITER
This error code is set by the @code{gdbm_open} function if it is not
able to lock file when called in writer mode (@pxref{Open}).
@end defvr
@defvr {Error Code} GDBM_READER_CANT_DELETE
Set by the @code{gdbm_delete} (@pxref{Delete}) if it attempted to
operate on a database that is open in read-only mode (@pxref{Open,
GDBM_READER}).
@end defvr
@defvr {Error Code} GDBM_READER_CANT_STORE
Set by the @code{gdbm_store} (@pxref{Store}) if it attempted to
operate on a database that is open in read-only mode (@pxref{Open,
GDBM_READER}).
@end defvr
@defvr {Error Code} GDBM_READER_CANT_REORGANIZE
Set by the @code{gdbm_reorganize} (@pxref{Reorganization}) if it attempted to
operate on a database that is open in read-only mode (@pxref{Open,
GDBM_READER}).
@end defvr
@defvr {Error Code} GDBM_ITEM_NOT_FOUND
Requested item was not found. This error is set by @code{gdbm_delete}
(@pxref{Delete}) and @code{gdbm_fetch} (@pxref{Fetch}) when the requested
@var{key} value is not found in the database.
@end defvr
@defvr {Error Code} GDBM_REORGANIZE_FAILED
The @code{gdbm_reorganize} function is not
able to create a temporary database. @xref{Reorganization}.
@end defvr
@defvr {Error Code} GDBM_CANNOT_REPLACE
Cannot replace existing item. This error is set by the
@code{gdbm_store} if the requested @var{key} value is found in the
database and the @var{flag} parameter is not @code{GDBM_REPLACE}.
@xref{Store}, for a detailed discussion.
@end defvr
@defvr {Error Code} GDBM_MALFORMED_DATA
@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
@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}).
The @code{GDBM_ILLEGAL_DATA} is an alias for this error code,
maintained for backward compatibility. Its use in modern applications
is discouraged.
@end defvr
@defvr {Error Code} GDBM_OPT_ALREADY_SET
Requested option can be set only once and was already set. As of
version @value{VERSION}, this error code is no longer used. In prior
versions it could have been returned by the @code{gdbm_setopt}
function when setting the @code{GDBM_CACHESIZE} value.
@end defvr
@defvr {Error Code} GDBM_OPT_BADVAL
@defvrx {Error Code} GDBM_OPT_ILLEGAL
The @var{option} argument is not valid or the @var{value} argument
points to an invalid value in a call to @code{gdbm_setopt} function.
@xref{Options}.
@code{GDBM_OPT_ILLEGAL} is an alias for this error code, maintained
for backward compatibility. Modern applications should not use it.
@end defvr
@defvr {Error Code} GDBM_BYTE_SWAPPED
The @code{gdbm_open} function (@pxref{Open}) attempts to open a
database which is created on a machine with different byte ordering.
@end defvr
@defvr {Error Code} GDBM_BAD_FILE_OFFSET
The @code{gdbm_open} function (@pxref{Open}) sets this error code if
the file it tries to open has a wrong magic number.
@end defvr
@defvr {Error Code} GDBM_BAD_OPEN_FLAGS
Set by the @code{gdbm_dump} (@code{gdbm_export}) function if supplied
an invalid @var{flags} argument. @xref{Flat files}.
@end defvr
@defvr {Error Code} GDBM_FILE_STAT_ERROR
Getting information about a disk file failed. The system @code{errno}
will give more details about the error.
This error can be set by the following functions: @code{gdbm_open},
@code{gdbm_reorganize}.
@end defvr
@defvr {Error Code} GDBM_FILE_EOF
End of file was encountered where more data was expected to be
present. This error can occur when fetching data from the database
and usually means that the database is truncated or otherwise corrupted.
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},
@code{gdbm_firstkey}, @code{gdbm_nextkey}, @code{gdbm_store}.
@end defvr
@defvr {Error Code} GDBM_NO_DBNAME
Output database name is not specified. This error code is set by
@code{gdbm_load} (@pxref{gdbm_load function,,gdbm_load}) if the first
argument points to @code{NULL} and the input file does not specify the
database name.
@end defvr
@defvr {Error Code} GDBM_ERR_FILE_OWNER
This error code is set by @code{gdbm_load} if it is unable to restore
database file owner. It is a mild error condition, meaning that the
data have been restored successfully, only changing the target file
owner failed. Inspect the system @code{errno} variable to get a more
detailed diagnostics.
@end defvr
@defvr {Error Code} GDBM_ERR_FILE_MODE
This error code is set by @code{gdbm_load} if it is unable to restore
database file mode. It is a mild error condition, meaning that the data
have been restored successfully, only changing the target file owner
failed. Inspect the system @code{errno} variable to get a more
detailed diagnostics.
@end defvr
@defvr {Error Code} GDBM_NEED_RECOVERY
Database is in inconsistent state and needs recovery. Call
@code{gdbm_recover} if you get this error. @xref{Recovery}, for a
detailed description of recovery functions.
@end defvr
@defvr {Error Code} GDBM_BACKUP_FAILED
The GDBM engine is unable to create backup copy of the file.
@end defvr
@defvr {Error Code} GDBM_DIR_OVERFLOW
Bucket directory would overflow the size limit during an attempt to split
hash bucket. This error can occur while storing a new key.
@end defvr
@defvr {Error Code} GDBM_BAD_BUCKET
Invalid index bucket is encountered in the database. Database
recovery is needed (@pxref{Recovery}).
@end defvr
@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
@command{GDBM} header.
@end defvr
@defvr {Error Code} GDBM_BAD_AVAIL
The available space stack is invalid. This error can be set by
@code{gdbm_open} and @code{gdbm_fd_open}, if the extended database
verification was requested (@code{GDBM_XVERIFY}). It is also set
by the @code{gdbm_avail_verify} function (@pxref{Additional
functions}).
Database recovery is needed (@pxref{Recovery}).
@end defvr
@defvr {Error Code} GDBM_BAD_HASH_TABLE
Hash table in a bucket is invalid. This error can be set by the
following functions: @code{gdbm_delete}, @code{gdbm_exists},
@code{gdbm_fetch}, @code{gdbm_firstkey}, @code{gdbm_nextkey}, and
@code{gdbm_store}.
Database recovery is needed (@pxref{Recovery}).
@end defvr
@defvr {Error Code} GDBM_BAD_DIR_ENTRY
Bad directory entry found in the bucket. The database recovery is
needed (@pxref{Recovery}).
@end defvr
@defvr {Error Code} GDBM_FILE_CLOSE_ERROR
The @code{gdbm_close} function was unable to close the database file
descriptor. The system @code{errno} variable contains the
corresponding error code.
@end defvr
@defvr {Error Code} GDBM_FILE_SYNC_ERROR
Cached content couldn't be synchronized to disk. Examine the
@code{errno} variable to get more info,
Database recovery is needed (@pxref{Recovery}).
@end defvr
@defvr {Error Code} GDBM_FILE_TRUNCATE_ERROR
File cannot be truncated. Examine the @code{errno} variable to get
more info.
This error is set by @code{gdbm_open} and @code{gdbm_fd_open} when
called with the @code{GDBM_NEWDB} flag.
@end defvr
@defvr {Error Code} GDBM_BUCKET_CACHE_CORRUPTED
The bucket cache structure is corrupted. Database recovery is needed
(@pxref{Recovery}).
@end defvr
@defvr {Error Code} GDBM_BAD_HASH_ENTRY
This error is set during sequential access (@pxref{Sequential}), if
the next hash table entry does not contain the expected key. This
means that the bucket is malformed or corrupted and the database needs
recovery (@pxref{Recovery}).
@end defvr
@defvr {Error Code} GDBM_ERR_SNAPSHOT_CLONE
Set by the @code{gdbm_failure_atomic} function if it was unable to
clone the database file into a snapshot. Inspect the system
@code{errno} variable for the underlying cause of the error. If
@code{errno} is @code{EINVAL} or @code{ENOSYS}, crash tolerance
settings will be removed from the database.
@xref{Crash Tolerance API}.
@end defvr
@defvr {Error Code} GDBM_ERR_REALPATH
Set by the @code{gdbm_failure_atomic} function if the call to
@code{realpath} function failed. @code{realpath} is used to
determine actual path names of the snapshot files. Examine the system
@code{errno} variable for details.
@xref{Crash Tolerance API}.
@end defvr
@defvr {Error Code} GDBM_ERR_USAGE
Function usage error. That includes invalid argument values, and the like.
@end defvr
@node Compatibility
@chapter Compatibility with standard @command{dbm} and @command{ndbm}
@cindex compatibility layer
@command{Gdbm} includes a compatibility layer, which provides traditional
@command{ndbm} and older @command{dbm} functions. The layer is compiled and
installed if the @option{--enable-libgdbm-compat} option is used when
configuring the package.
@findex ndbm.h
@findex dbm.h
@findex libgdbm_compat
The compatibility layer consists of two header files: @file{ndbm.h}
and @file{dbm.h} and the @file{libgdbm_compat} library.
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 @command{GDBM} is
installed, e.g.:
@example
cc ... -lgdbm -lgdbm_compat
@end example
@cindex @samp{dir} file
@cindex @samp{pag} file
Databases created and manipulated by the compatibility interfaces
consist of two different files: @file{@var{file}.dir} and
@file{@var{file}.pag}. This is required by the @acronym{POSIX}
specification and corresponds to the traditional usage. Note,
however, that despite the similarity of the naming convention,
actual data stored in these files has not the same format as
in the databases created by other @command{dbm} or @command{ndbm}
libraries. In other words, you cannot access a standard UNIX
@command{dbm} file with GNU @command{dbm}!
Compatibility interface includes only functions required by
@acronym{POSIX} (@pxref{ndbm}) or present in the traditional DBM
implementation (@pxref{dbm}). Advanced @command{GDBM} features, such
as crash tolerance, cannot be used with such databases.
GNU @command{dbm} files are not @code{sparse}. You can copy them with
the usual @code{cp} command and they will not expand in the copying
process.
@menu
* ndbm:: NDBM interface functions.
* dbm:: DBM interface functions.
@end menu
@node ndbm
@section NDBM interface functions
@cindex NDBM functions
The functions below implement the @acronym{POSIX} @command{ndbm} interface:
@deftypefn {ndbm} {DBM *} dbm_open (char *@var{file}, int @var{flags}, int @var{mode})
Opens a database. The @var{file} argument is the full name of the
database file to be opened. The function opens two files:
@file{@var{file}.pag} and @file{@var{file}.dir}. The @var{flags} and
@var{mode} arguments have the same meaning as the second and third
arguments of @code{open} (@pxref{open,,,open(2), open(2) man page}),
except that a database opened for write-only access opens the files
for read and write access and the behavior of the @code{O_APPEND} flag is
unspecified.
The function returns a pointer to the @code{DBM} structure describing
the database. This pointer is used to refer to this database in all
operations described below.
Any error detected will cause a return value of @code{NULL} and an
appropriate value will be stored in @code{gdbm_errno}
(@pxref{Variables}).
@end deftypefn
@deftypefn {ndbm} void dbm_close (DBM *@var{dbf})
Closes the database. The @var{dbf} argument must be a pointer
returned by an earlier call to @code{dbm_open}.
@end deftypefn
@deftypefn {ndbm} datum dbm_fetch (DBM *@var{dbf}, datum @var{key})
Reads a record from the database with the matching key. The @var{key}
argument supplies the key that is being looked for.
If no matching record is found, the @code{dptr} member of the returned
datum is @code{NULL}. Otherwise, the @code{dptr} member of the
returned datum points to the memory managed by the compatibility
library. The application should never free it.
@end deftypefn
@deftypefn {ndbm} int dbm_store (DBM *@var{dbf}, datum @var{key}, @
datum @var{content}, int @var{mode})
Writes a key/value pair to the database. The argument @var{dbf} is a
pointer to the @code{DBM} structure returned from a call to
@code{dbm_open}. The @var{key} and @var{content} provide the values
for the record key and content. The @var{mode} argument controls
the behavior of @code{dbm_store} in case a matching record already
exists in the database. It can have one of the following two values:
@table @code
@kwindex DBM_REPLACE
@item DBM_REPLACE
Replace existing record with the new one.
@kwindex DBM_INSERT
@item DBM_INSERT
The existing record is left unchanged, and the function returns
@code{1}.
@end table
If no matching record exists in the database, new record will be
inserted no matter what the value of the @var{mode} is.
@end deftypefn
@deftypefn {ndbm} int dbm_delete (DBM *@var{dbf}, datum @var{key})
Deletes the record with the matching key from the database. If the
function succeeds, @code{0} is returned. Otherwise, if no matching
record is found or if an error occurs, @code{-1} is returned.
@end deftypefn
@deftypefn {ndbm} datum dbm_firstkey (DBM *@var{dbf})
Initializes iteration over the keys from the database and returns
the first key. Note, that the word @samp{first} does not imply any
specific ordering of the keys.
If there are no records in the database, the @code{dptr} member of the
returned datum is @code{NULL}. Otherwise, the @code{dptr} member of
the returned datum points to the memory managed by the compatibility
library. The application should never free it.
@end deftypefn
@deftypefn {ndbm} datum dbm_nextkey (DBM *@var{dbf})
Continues the iteration started by @code{dbm_firstkey}. Returns the
next key in the database. If the iteration covered all keys in the
database, the @code{dptr} member of the returned datum is @code{NULL}.
Otherwise, the @code{dptr} member of the returned datum points to the
memory managed by the compatibility library. The application should
never free it.
@cindex sequential access, using @samp{NDBM}
@cindex iteration loop, using @samp{NDBM}
The usual way of iterating over all the records in the database is:
@example
for (key = dbm_firstkey (dbf); key.ptr; key = dbm_nextkey (dbf))
@{
/* do something with the key */
@}
@end example
The loop above should not try to delete any records from the database,
otherwise the iteration is not guaranteed to cover all the keys.
@xref{Sequential}, for a detailed discussion of this.
@end deftypefn
@deftypefn {ndbm} int dbm_error (DBM *@var{dbf})
Returns the error condition of the database: @code{0} if no errors
occurred so far while manipulating the database, and a non-zero value
otherwise.
@end deftypefn
@deftypefn {ndbm} void dbm_clearerr (DBM *@var{dbf})
Clears the error condition of the database.
@end deftypefn
@deftypefn {ndbm} int dbm_dirfno (DBM *@var{dbf})
Returns the file descriptor of the @samp{dir} file of the database.
It is guaranteed to be different from the descriptor returned by
the @code{dbm_pagfno} function (see below).
The application can lock this descriptor to serialize accesses to the
database.
@end deftypefn
@deftypefn {ndbm} int dbm_pagfno (DBM *@var{dbf})
Returns the file descriptor of the @samp{pag} file of the database.
See also @code{dbm_dirfno}.
@end deftypefn
@deftypefn {ndbm} int dbm_rdonly (DBM *@var{dbf})
Returns @code{1} if the database @var{dbf} is open in a read-only mode
and @code{0} otherwise.
@end deftypefn
@node dbm
@section DBM interface functions
@cindex DBM functions
The functions below are provided for compatibility with the old
UNIX @samp{DBM} interface. Only one database at a time can be
manipulated using them.
@deftypefn {dbm} int dbminit (char *@var{file})
Opens a database. The @var{file} argument is the full name of the
database file to be opened. The function opens two files:
@file{@var{file}.pag} and @file{@var{file}.dir}. If any of
them does not exist, the function fails. It never attempts to create
the files.
The database is opened in the read-write mode, if its disk permissions
permit.
The application must ensure that the functions described below in
this section are called only after a successful call to @code{dbminit}.
@end deftypefn
@deftypefn {dbm} int dbmclose (void)
Closes the database opened by an earlier call to @code{dbminit}.
@end deftypefn
@deftypefn {dbm} datum fetch (datum @var{key})
Reads a record from the database with the matching key. The @var{key}
argument supplies the key that is being looked for.
If no matching record is found, the @code{dptr} member of the returned
datum is @code{NULL}. Otherwise, the @code{dptr} member of the
returned datum points to the memory managed by the compatibility
library. The application should never free it.
@end deftypefn
@deftypefn {dbm} int store (datum @var{key}, datum @var{content})
Stores the key/value pair in the database. If a record with the
matching key already exists, its content will be replaced with the new
one.
Returns @code{0} on success and @code{-1} on error.
@end deftypefn
@deftypefn {dbm} int delete (datum @var{key})
Deletes a record with the matching key.
If the function succeeds, @code{0} is returned. Otherwise, if no
matching record is found or if an error occurs, @code{-1} is
returned.
@end deftypefn
@deftypefn {dbm} datum firstkey (void)
Initializes iteration over the keys from the database and returns
the first key. Note, that the word @samp{first} does not imply any
specific ordering of the keys.
If there are no records in the database, the @code{dptr} member of the
returned datum is @code{NULL}. Otherwise, the @code{dptr} member of
the returned datum points to the memory managed by the compatibility
library. The application should never free it.
@end deftypefn
@deftypefn {dbm} datum nextkey (datum @var{key})
Continues the iteration started by a call to @code{firstkey}. Returns
the next key in the database. If the iteration covered all keys in the
database, the @code{dptr} member of the returned datum is @code{NULL}.
Otherwise, the @code{dptr} member of the returned datum points to the
memory managed by the compatibility library. The application should
never free it.
@end deftypefn
@node gdbmtool
@chapter Examine and modify a GDBM database
@prindex gdbmtool
The @command{gdbmtool} utility allows you to view and modify an
existing @command{GDBM} database or to create a new one.
@cindex default database, @command{gdbmtool}
@flindex junk.gdbm
When invoked without arguments, it tries to open a database file called
@file{junk.gdbm}, located in the current working directory. You can
change this default by supplying the name of the database as
argument to the program, e.g.:
@example
$ gdbmtool file.db
@end example
@cindex read-only mode, @command{gdbmtool}
@cindex @option{-r}, @command{gdbmtool} option
@cindex @option{--read-only}, @command{gdbmtool} option
The database will be opened in read-write mode, unless the
@option{-r} (@option{--read-only}) option is specified, in which case
it will be opened only for reading.
@cindex creating a database, @command{gdbmtool}
@cindex @option{-n}, @command{gdbmtool} option
@cindex @option{--newdb}, @command{gdbmtool} option
If the database does not exist, @command{gdbmtool} will create it.
There is a special option @option{-n} (@option{--newdb}), which
instructs the utility to create a new database. If it is used and if
the database already exists, it will be deleted, so use it sparingly.
@menu
* invocation::
* shell::
@end menu
@node invocation
@section gdbmtool invocation
@cindex command line options, @command{gdbmtool}
When started without additional arguments, @command{gdbmtool} operates
on the default database @file{junk.gdbm}. Otherwise, the first
argument supplies the name of the database to operate upon. If neither
any additional arguments nor the @option{-f} (@option{--file}) option
are given, @command{gdbmtool} opens starts interactive shell and
receives commands directly from the human operator.
If more than one argument is given, all arguments past the database
name are parsed as @command{gdbmtool} commands (@pxref{shell}, for a
description of available commands) and executed in turn. All commands,
except the last one, should be terminated with semicolons. Semicolon
after the last command is optional. Note, that semicolons should be
escaped in order to prevent them from being interpreted by the shell.
Finally, if the @option{-f} (@option{--file}) option is supplied, its
argument specifies the name of the disk file with @command{gdbmtool}
script. The program will open that file and read commands from it.
The following table summarizes all @command{gdbmtool} command line
options:
@table @option
@item -b @var{size}
@itemx --block-size=@var{size}
Set block size.
@item -c @var{size}
@itemx --cache-size=@var{size}
Set cache size.
@item -d @var{fd}
@itemx --db-descriptor=@var{fd}
Use the database referred to by the file descriptor @var{fd}. This
must be a valid open file descriptor, obtained by a call to
@code{open} (@pxref{open,,open a file,open(2), open(2) man page}),
@code{creat} or a similar function. The database will be opened using
@code{gdbm_fd_open} (@pxref{gdbm_fd_open}).
This option is intended for use by automatic test suites.
@item -f @var{file}
@item --file @var{file}
Read commands from @var{file}, instead of the standard input.
@item -h
@itemx --help
Print a concise help summary.
@item -N
@itemx --norc
Don't read startup files (@pxref{startup files}).
@item -n
@itemx --newdb
Create the database.
@item -l
@itemx --no-lock
Disable file locking.
@item -m
@itemx --no-mmap
Disable memory mapping.
@item -T
@itemx --timing
Print time spent in each command. This is equivalent to setting the
@code{timing} variable. @xref{variables, timing}.
@item -t
@itemx --trace
Enable command tracing. This is equivalent to setting the
@code{trace} variable. @xref{variables, trace}.
@anchor{-q option}
@item -q
@itemx --quiet
Don't print the usual welcome banner at startup. This is the same as
setting the variable @code{quiet} in the startup file. @xref{quiet}.
@item -r
@itemx --read-only
Open the database in read-only mode.
@item -s
@itemx --synchronize
Synchronize to the disk after each write.
@item -V
@itemx --version
Print program version and licensing information and exit.
@item --usage
Print a terse invocation syntax summary along with a list of available
command line options.
@item -x
@itemx --extended
@itemx --numsync
Create new database in extended (numsync) format (@pxref{Numsync}).
This option sets the @code{format} variable to @samp{numsync}.
@xref{format variable}.
@end table
@node shell
@section gdbmtool interactive mode
@cindex interactive mode, @command{gdbmtool}
After successful startup, @command{gdbmtool} starts a loop, in which
it reads commands from the standard input, executes them and prints
results on the standard output. If the standard input is attached
to a console, @command{gdbmtool} runs in interactive mode, which is
indicated by its @dfn{prompt}:
@example
gdbmtool> _
@end example
The utility finishes when it reads the @code{quit} command (see below) or
detects end-of-file on its standard input, whichever occurs first.
A @command{gdbmtool} command consists of a @dfn{command verb},
optionally followed by @dfn{arguments}, separated by any
amount of white space and terminated with a newline or semicolon.
A command verb can be entered either in full or in an abbreviated
form, as long as that abbreviation does not match any other verb. For
example, @code{co} can be used instead of @code{count} and @code{ca}
instead of @code{cache}.
Any sequence of non-whitespace characters appearing after the command
verb forms an argument. If the argument contains whitespace or
unprintable characters it must be enclosed in double quotes. Within
double quotes the usual @dfn{escape sequences} are understood, as
shown in the table below:
@float Table, backslash-interpretation
@caption{Backslash escapes}
@multitable @columnfractions 0.30 .5
@item Sequence @tab Replaced with
@item \a @tab Audible bell character (@acronym{ASCII} 7)
@item \b @tab Backspace character (@acronym{ASCII} 8)
@item \f @tab Form-feed character (@acronym{ASCII} 12)
@item \n @tab Newline character (@acronym{ASCII} 10)
@item \r @tab Carriage return character (@acronym{ASCII} 13)
@item \t @tab Horizontal tabulation character (@acronym{ASCII} 9)
@item \v @tab Vertical tabulation character (@acronym{ASCII} 11)
@item \\ @tab Single slash
@item \" @tab Double quote
@end multitable
@end float
In addition, a backslash immediately followed by the end-of-line
character effectively removes that character, allowing to split long
arguments over several input lines.
Command parameters may be optional or mandatory. If the number of
actual arguments is less than the number of mandatory parameters,
@command{gdbmtool} will prompt you to supply missing arguments. For
example, the @code{store} command takes two mandatory parameters, so
if you invoked it with no arguments, you would be prompted twice to
supply the necessary data, as shown in example below:
@example
gdbmtool> @kbd{store}
key? @kbd{three}
data? @kbd{3}
@end example
However, such prompting is possible only in interactive mode. In
non-interactive mode (e.g.@: when running a script), all arguments must
be supplied with each command, otherwise @command{gdbmtool} will report an
error and exit immediately.
@cindex readline
@cindex GNU Readline
If the package is compiled with GNU Readline, the input line can be
edited (@pxref{Command Line Editing, ,
Command Line Editing, readline, GNU Readline Library}).
@menu
* variables:: shell variables.
* commands:: shell commands.
* definitions:: how to define structured data.
* startup files::
@end menu
@node variables
@subsection Shell Variables
@cindex variables, gdbmtool
A number of @command{gdbmtool} parameters is kept in its internal
variables. To examine or modify variables, use the @code{set} command
(@pxref{set}).
@deftypevr {gdbmtool variable} bool confirm
Whether to ask for confirmation before certain destructive operations,
such as truncating the existing database.
Default is @code{true}.
@end deftypevr
@deftypevr {gdbmtool variable} string delim1
A string used to delimit fields of a structured datum on output
(@pxref{definitions}).
Default is @samp{,} (a comma). This variable cannot be unset.
@end deftypevr
@deftypevr {gdbmtool variable} string delim2
A string used to delimit array items when printing a structured datum
(@pxref{definitions}).
Default is @samp{,} (a comma). This variable cannot be unset.
@end deftypevr
@deftypevr {gdbmtool variable} string errorexit
@deftypevrx {gdbmtool variable} bool errorexit
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
be prefixed with minus sign, to indicate that it should be removed
from the resulting list, or with plus sign (which is allowed for
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}.
@end deftypevr
@deftypevr {gdbmtool variable} string errormask
@deftypevrx {gdbmtool variable} bool errormask
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
@deftypevr {gdbmtool variable} string pager
The name and command line of the pager program to pipe output to.
This program is used in interactive mode when the estimated number of
output lines is greater then the number of lines on your screen.
The default value is inherited from the environment variable
@env{PAGER}. Unsetting this variable disables paging.
@end deftypevr
@deftypevr {gdbmtool variable} string ps1
Primary prompt string. Its value can contain @dfn{conversion
specifiers}, consisting of the @samp{%} character followed by another
character. These specifiers are expanded in the resulting prompt as
follows:
@multitable @columnfractions 0.4 0.5
@headitem Sequence @tab Expansion
@item %f @tab name of the current database file
@item %p @tab program invocation name
@item %P @tab package name (@samp{GDBM})
@item %v @tab program version
@item %_ @tab single space character
@item %% @tab %
@end multitable
The default value is @samp{%p>%_}, i.e. the program name, followed by
a ``greater than'' sign, followed by a single space.
@end deftypevr
@deftypevr {gdbmtool variable} string ps2
Secondary prompt. See @code{ps1} for a description of its value.
This prompt is displayed before reading the second and subsequent
lines of a multi-line command.
The default value is @samp{%_>%_}.
@end deftypevr
@deftypevr {gdbmtool variable} bool timing
When each command terminates, print an additional line listing times
spent in that command. The line is formatted as follows:
@example
[reorganize r=0.070481 u=0.000200 s=0.000033]
@end example
@noindent
Here, @samp{reorganize} is the name of the command that finished, the
number after @samp{r=} is real time spent executing the command, the
number after @samp{u=} is the user CPU time used and the number after
@samp{s=} is the system CPU time used.
@end deftypevr
@deftypevr {gdbmtool variable} bool trace
Enable command tracing. This is similar to the shell @option{-t}
option: before executing each command, @command{gdbmtool} will print
on standard error a line starting with a plus sign and followed by the
command name and its arguments.
@end deftypevr
@anchor{quiet}
@deftypevr {gdbmtool variable} bool quiet
Whether to display a welcome banner at startup. To affect
@command{gdbmtool}, this variable should be set in a startup script
file (@pxref{startup files}). @xref{-q option}.
@end deftypevr
@anchor{open parameters}
The following variables control how the database is opened:
@deftypevr {gdbmtool variable} numeric blocksize
Sets the block size. @xref{Open, block_size}. Unset by default.
@end deftypevr
@deftypevr {gdbmtool variable} numeric cachesize
Sets the cache size. @xref{Options, GDBM_SETCACHESIZE}.
This variable affects the currently opened database immediately. It
is also used by @command{open} command.
To enable automatic cache size selection, unset this variable. This
is the default.
@end deftypevr
@deftypevr {gdbmtool variable} string filename
Name of the database file. If the @code{open} command is called
without argument (e.g. called implicitly), this variable names the
database file to open. If @code{open} is called with file name
argument, upon successful opening of the database the @code{filename}
variable is initialized with its file name.
This variable cannot be unset.
@end deftypevr
@deftypevr {gdbmtool variable} number fd
File descriptor of the database file to open. If this variable is
set, its value must be an open file descriptor referring to a
@command{GDBM} database file. The @code{open} command will use
@code{gdbm_fd_open} function to use this file (@pxref{gdbm_fd_open}).
When this database is closed, the descriptor will be closed as well
and the @code{fd} variable will be unset.
See also the @option{-d} (@option{--db-descriptor}) command line
option in @ref{invocation}.
@end deftypevr
@anchor{format variable}
@deftypevr {gdbmtool variable} string format
Defines the format in which new databases will be created. Allowed
values are:
@table @samp
@item standard
Databases will be created in standard format. This is the format used
by all @command{GDBM} versions prior to 1.21. This value is the
default.
@item numsync
Extended format, best for crash-tolerant applications.
@xref{Numsync}, for a discussion of this format.
@end table
@end deftypevr
@anchor{openvar}
@deftypevr {gdbmtool variable} string open
Open mode. The following values are allowed:
@table @asis
@item newdb
Truncate the database if it exists or create a new one. Open it in
read-write mode.
Technically, this sets the @code{GDBM_NEWDB} flag in call to @code{gdbm_open}.
@xref{Open, GDBM_NEWDB}.
@item wrcreat
@itemx rw
Open the database in read-write mode. Create it if it does not
exist. This is the default.
Technically speaking, it sets the @code{GDBM_WRCREAT} flag in call to
@code{gdbm_open}. @xref{Open, GDBM_WRCREAT}.
@item reader
@itemx readonly
Open the database in read-only mode. Signal an error if it does not
exist.
This sets the @code{GDBM_READER} flag (@pxref{Open, GDBM_READER}).
@end table
Attempting to set any other value or to unset this variable results
in error.
@end deftypevr
@anchor{filemode}
@deftypevr {gdbmtool variable} number filemode
File mode (in octal) for creating new database files and database
dumps.
@end deftypevr
@deftypevr {gdbmtool variable} bool lock
Lock the database. This is the default.
Setting this variable to false or unsetting it results in passing
@code{GDBM_NOLOCK} flag to @code{gdbm_open} (@pxref{Open, GDBM_NOLOCK}).
@end deftypevr
@deftypevr {gdbmtool variable} bool mmap
Use memory mapping. This is the default.
Setting this variable to false or unsetting it results in passing
@code{GDBM_NOMMAP} flag to @code{gdbm_open} (@pxref{Open, GDBM_NOMMAP}).
@end deftypevr
@deftypevr {gdbmtool variable} bool sync
Flush all database writes on disk immediately. Default is false.
@xref{Open, GDBM_SYNC}.
@end deftypevr
@deftypevr {gdbmtool variable} bool coalesce
Enables the @emph{coalesce} mode, i.e. merging of the freed blocks of
@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.
@end deftypevr
@deftypevr {gdbmtool variable} bool centfree
Set to @code{true}, enables the use of central free block pool in
newly opened databases. @xref{Options, GDBM_SETCENTFREE}.
This variable affects the currently opened database immediately and
will be used by @command{open} command, when it is invoked.
@end deftypevr
The following commands are used to list or modify the variables:
@anchor{set}
@deffn {command verb} set [@var{assignments}]
When used without arguments, lists all variables and their values.
Unset variables are shown after a comment sign (@samp{#}). For string
and numeric variables, values are shown after an equals sign. For
boolean variables, only the variable name is displayed if the variable
is @code{true}. If it is @code{false}, its name is prefixed with
@samp{no}.
For example:
@example
@group
# blocksize is unset
# cachesize is unset
nocentfree
nocoalesce
confirm
delim1=","
delim2=","
# fd is unset
filemode=644
filename="junk.gdbm"
format="standard"
lock
mmap
open="wrcreat"
pager="less"
ps1="%p>%_"
ps2="%_>%_"
# quiet is unset
nosync
@end group
@end example
If used with arguments, the @code{set} command alters the specified
variables. In this case, arguments are variable assignments in the
form @samp{@var{name}=@var{value}}. For boolean variables, the
@var{value} is interpreted as follows: if it is numeric, @code{0}
stands for @code{false}, any non-zero value stands for @code{true}.
Otherwise, the values @code{on}, @code{true}, and @code{yes} denote
@code{true}, and @code{off}, @code{false}, @code{no} stand for
@code{false}. Alternatively, only the name of a boolean variable can be
supplied to set it to @code{true}, and its name prefixed with
@code{no} can be used to set it to false. For example, the following
command sets the @code{delim2} variable to @samp{;} and the
@code{confirm} variable to @code{false}:
@example
set delim2=";" noconfirm
@end example
@end deffn
@deffn {command verb} unset @var{variables}
Unsets the listed variables. The effect of unsetting depends on the
variable. Unless explicitly described in the discussion of the
variables above, unsetting a boolean variable is equivalent to setting it to
@code{false}. Unsetting a string variable is equivalent to assigning it
an empty string.
@end deffn
@node commands
@subsection Gdbmtool Commands
@deffn {command verb} avail
Print the @dfn{avail list}.
@end deffn
@deffn {command verb} bucket @var{num}
Print the bucket number @var{num} and set it as the current one.
@end deffn
@deffn {command verb} cache
Print the bucket cache.
@end deffn
@deffn {command verb} close
Close the currently open database.
@end deffn
@deffn {command verb} count
Print the number of entries in the database.
@end deffn
@deffn {command verb} current
Print the current bucket.
@end deffn
@deffn {command verb} debug [[+-]@var{token}...]
If @command{GDBM} is configured with additional debugging, this
statement queries or sets @command{GDBM} internal debugging level.
This is intended for debugging and testing purposes and requires
good knowledge of @command{GDBM} internals. The use of this command is
not recommended.
@end deffn
@deffn {command verb} delete @var{key}
Delete record with the given @var{key}
@end deffn
@deffn {command verb} dir
Print hash directory.
@end deffn
@deffn {command verb} downgrade
Downgrade the database from extended to the standard database format.
@xref{Numsync}.
@end deffn
@anchor{gdbmtool export}
@deffn {command verb} export @var{file-name} [truncate] [binary|ascii]
Export the database to the flat file @var{file-name}. @xref{Flat files},
for a description of the flat file format and its purposes. This
command will not overwrite an existing file, unless the
@samp{truncate} parameter is also given. Another optional argument
determines the type of the dump (@pxref{Flat files}). By default, ASCII
dump is created.
The global variable @code{filemode} specifies the permissions to use
for the created output file.
@end deffn
@deffn {command verb} fetch @var{key}
Fetch and display the record with the given @var{key}.
@end deffn
@deffn {command verb} first
Fetch and display the first record in the database. Subsequent
records can be fetched using the @code{next} command (see below).
@xref{Sequential}, for more information on sequential access.
@end deffn
@deffn {command verb} hash @var{key}
Compute and display the hash value for the given @var{key}.
@end deffn
@deffn {command verb} header
Print file header.
@end deffn
@deffn {command verb} help
@deffnx {command verb} ?
Print a concise command summary, showing each command verb
with its parameters and a short description of what it does. Optional
arguments are enclosed in square brackets.
@end deffn
@anchor{gdbmtool import}
@deffn {command verb} import @var{file-name} [replace] [nometa]
Import data from a flat dump file @var{file-name}
(@pxref{Flat files}). If the word @samp{replace} is given
as an argument, any records with the same keys as the already
existing ones will replace them. The word @samp{nometa} turns off
restoring meta-information from the dump file.
@end deffn
@deffn {command verb} history
@deffnx {command verb} history @var{count}
@deffnx {command verb} history @var{n} @var{count}
Shows the command history list with line numbers. When used without
arguments, shows entire history. When used with one argument,
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 @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
@deffn {command verb} list
List the contents of the database.
@end deffn
@deffn {command verb} next [@var{key}]
Sequential access: fetch and display the next record. If the @var{key} is
given, the record following the one with this key will be fetched.
Issuing several @code{next} commands in row is rather common. A
shortcut is provided to facilitate such use: if the last entered
command was @command{next}, hitting the @kbd{Enter} key repeats it
without arguments.
See also @code{first}, above.
@xref{Sequential}, for more information on sequential access.
@end deffn
@deffn {command verb} open @var{filename}
@deffnx {command verb} open
Open the database file @var{filename}. If used without arguments, the
database name is taken from the variable @code{filename}.
If successful, any previously open database is closed and the
@code{filename} variable is updated. Otherwise, if the operation
fails, the currently opened database remains unchanged.
This command takes additional information from the following
variables:
@table @code
@item filename
Name of the database to open, if no argument is given.
@item fd
File descriptor to use. If set, this must be an open file descriptor
referring to a valid database file. The database will be opened using
@code{gdbm_fd_open} (@pxref{gdbm_fd_open}). The file descriptor will
be closed and the variable unset upon closing the database.
@item filemode
Specifies the permissions to use in case a new file is created.
@item open
The database access mode. @xref{openvar,, The @var{open} variable},
for a list of its values.
@item lock
Whether or not to lock the database. Default is @code{on}.
@item mmap
Use the memory mapping. Default is @code{on}.
@item sync
Synchronize after each write. Default is @code{off}.
@end table
@xref{open parameters}, for a detailed description of these variables.
@end deffn
@deffn {command verb} perror [@var{code}]
Describe the given @command{GDBM} error code.
The description occupies one or two lines. The second line is present
if the system error number should be checked when handling this code.
In this case, the second line states @samp{Examine errno}.
If @var{code} is omitted, the latest error that occurred in the
current database is described. Second line of the output (if
present), contains description of the latest system error.
Example:
@example
gdbmtool> perror 3
GDBM error code 3: "File open error"
Examine errno.
@end example
@end deffn
@deffn {command verb} quit
Close the database and quit the utility.
@end deffn
@deffn {command verb} recover [@var{options}]
Recover the database from structural inconsistencies. @xref{Database
consistency}.
The following @var{options} are understood:
@table @option
@item backup
Create a backup copy of the original database.
@item max-failed-buckets=@var{n}
Abort recovery process if @var{n} buckets could not be recovered.
@item max-failed-keys=@var{n}
Abort recovery process if @var{n} keys could not be recovered.
@item max-failures=@var{n}
Abort recovery process after @var{n} failures. A @dfn{failure} in this
context is either a key or a bucket that failed to be recovered.
@item summary
Print the recovery statistics at the end of the run. The statistics
includes number of successfully recovered, failed and duplicate keys
and the number of recovered and failed buckets.
@item verbose
Verbosely list each error encountered.
@end table
@end deffn
@deffn {command verb} reorganize
Reorganize the database (@pxref{Reorganization}).
@end deffn
@deffn {command verb} shell @var{command}
@deffnx {command verb} ! @var{command}
Execute @var{command} via current shell. If @var{command} is empty,
shell is started without additional arguments. Otherwise, it is run
as @samp{$SHELL -c @var{command}}.
For convenience, @var{command} is not parsed as @command{gdbmtool}
command line. It is passed to the shell verbatim. It can include
newline characters if these are preceded by a backslash or appear
within singly or doubly quoted strings.
When using @code{!} form, be sure to separate it from @var{command} by
whitespace, otherwise it will be treated as readline @dfn{event specifier}.
@end deffn
@deffn {command verb} snapshot @var{filename} @var{filename}
Analyze two snapshot files and select the most recent of them. In
case of error, display a detailed diagnostics and meta-information of
both snapshots.
@xref{Manual crash recovery}, for a detailed discussion.
@end deffn
@deffn {command verb} source @var{filename}
Read @command{gdbmtool} commands from the file @var{filename}.
@end deffn
@deffn {command verb} status
Print current program status. The following example shows the
information displayed:
@example
Database file: junk.gdbm
Database is open
define key string
define content string
@end example
The two @code{define} strings show the defined formats for key and
content data. @xref{definitions}, for a detailed discussion of their
meaning.
@end deffn
@deffn {command verb} store @var{key} @var{data}
Store the @var{data} with @var{key} in the database. If @var{key}
already exists, its data will be replaced.
@end deffn
@deffn {command verb} sync
Synchronize the database with the disk storage (@pxref{Sync}).
@end deffn
@deffn {command verb} upgrade
Upgrade the database from standard to extended database format.
@xref{Numsync}.
@end deffn
@deffn {command verb} version
Print the version of @command{gdbm}.
@end deffn
@node definitions
@subsection Data Definitions
@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
records.
The @code{define} command defines a record structure. The general
syntax is:
@example
define @var{what} @var{definition}
@end example
@noindent
where @var{what} is @code{key} to defining the structure of key data and
@code{content} to define the structure of the content records.
The @var{definition} can be of two distinct formats. In the simplest
case it is a single data type. For example,
@example
define content int
@end example
@noindent
defines content records consisting of a single integer field.
Supported data types are:
@table @asis
@item char
Single byte (signed).
@item short
Signed short integer.
@item ushort
Unsigned short integer.
@item int
Signed integer.
@item unsigned
@itemx uint
Unsigned integer.
@item long
Signed long integer.
@item ulong
Unsigned long integer.
@item llong
Signed long long integer.
@item ullong
Unsigned long long integer.
@item float
A floating point number.
@item double
Double-precision floating point number.
@item string
Array of bytes.
@item stringz
Null-terminated string, trailing null being part of the string.
@end table
All numeric data types (integer as well as floating point) have the
same respective widths as in C language on the host where the database
file resides.
The @code{string} and @code{stringz} are special. Both define a
string of bytes, similar to @samp{char x[]} in C. The former
defines an array of bytes, the latter - a null-terminated string.
This makes a difference, in particular, when the string is the only
part of datum. Consider the following two definitions:
@enumerate 1
@item @code{define key string}
@item @code{define key stringz}
@end enumerate
@noindent
Now, suppose we want to store the string "ab" in the key. Using the
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},
and ASCII 0. The @code{dsize} member will have the value 3.
The definition (1) is the default for both key and content.
The second form of the @code{define} statement is similar to the C
@code{struct} statement and allows for defining structural data. In
this form, the @var{definition} part is a comma-separated list of data
types and variables enclosed in curly braces. In contrast to the
rest of @command{gdbm} commands, this command is inherently
multiline and is terminated with the closing curly brace. For
example:
@example
define content @{
int status,
pad 8,
char id[3],
string name
@}
@end example
@noindent
This defines a structure consisting of three members: an integer
@code{status}, an array of 3 bytes @code{id}, and an array of
bytes @code{name}. Notice the @code{pad} statement: it allows to
introduce padding between structure members. Another useful statement
is @code{offset}: it specifies that the member following it begins at
the given offset in the structure. Assuming the size of @code{int} is
8 bytes, the above definition can also be written as
@example
define content @{
int status,
offset 16,
char id[3],
string name
@}
@end example
@emph{NOTE}: The @code{string} type can reasonably be used only if it
is the last or the only member of the data structure. That's because it
provides no information about the number of elements in the array, so
it is interpreted to contain all bytes up to the end of the datum.
When displaying the structured data, @command{gdbmtool} precedes each
value with the corresponding field name and delimits parts of the
structure with the string defined in the @code{delim1} variable
(@pxref{variables}). Array elements are delimited using the string from
@code{delim2}. For example:
@example
gdbmtool> fetch foo
status=2,id=@{ a, u, x @},name="quux"
@end example
To supply a structured datum as an argument to a @command{gdbmtool}
command, use the same notation, e.g.:
@example
gdbmtool> store newkey @{ status=2, id=@{a,u,x@}, name="quux" @}
@end example
The order in which the fields are listed is not significant. The
above command can as well be written as:
@example
gdbmtool> store newkey @{ id=@{a,u,x@}, status=2, name="quux" @}
@end example
You are not required to supply all defined fields. Any number of them
can be omitted, provided that at least one remains. The omitted
fields are filled with 0:
@example
gdbmtool> store newkey @{ name="bar" @}
gdbmtool> fetch newkey
status=0,id=@{ ,, @},name=bar
@end example
Yet another way to supply structured data to a command is by listing
the value for each field in the order they are defined, without field
names:
@example
gdbmtool> store newkey @{ 2, @{a,u,x@}, "quux" @}
@end example
@node startup files
@subsection Startup Files
@cindex startup file, gdbmtool
@cindex init file, gdbmtool
@flindex .gdbmtoolrc
Upon startup @command{gdbmtool} looks for a file named
@file{.gdbmtoolrc} first in the current working directory and, if not
found, in the home directory of the user who started the command.
If found, this file is read and interpreted as a list of
@command{gdbmtool} commands. This allows you to customize the
program behavior.
Following is an example startup file which disables the welcome
banner, sets command line prompt to contain the name of the database
file in parentheses and defines the structure of the database content
records:
@example
@group
set quiet
set ps1="(%f) "
define key stringz
define content @{
int time,
pad 4,
int status
@}
@end group
@end example
@node gdbm_dump
@chapter The @command{gdbm_dump} utility
@prindex gdbm_dump
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,
@command{gdbm_dump} will produce the dump on the standard output.
For example, the following invocation creates a dump of the database
@file{file.db} in the file @file{file.dump}:
@example
$ gdbm_dump file.db file.dump
@end example
By default the utility creates dumps in ASCII format (@pxref{Flat
files,ASCII}). Another format can be requested using the
@option{--format} (@option{-H}) option.
The @command{gdbm_dump} utility understands the following command line
options:
@table @option
@item -H @var{fmt}
@itemx --format=@var{fmt}
Select output format. Valid values for @var{fmt} are: @code{binary}
or @code{0} to select binary dump format, and @code{ascii} or @code{1}
to select ASCII format.
@item -h
@itemx --help
Print a concise help summary.
@item -V
@itemx --version
Print program version and licensing information and exit.
@item --usage
Print a terse invocation syntax summary along with a list of available
command line options.
@end table
@node gdbm_load
@chapter The @command{gdbm_load} utility
@prindex gdbm_load
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.
By default the utility attempts to restore the database under its
original name, as stored in the input file. It will fail to do so if
the input is in binary format. In that case, the name of the database
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.
The utility understands the following command line arguments:
@table @option
@item -b @var{num}
@itemx --block-size=@var{num}
Sets block size. @xref{Open, block_size}.
@item -c @var{num}
@itemx --cache-size=@var{num}
Sets cache size. @xref{Options, GDBM_SETCACHESIZE}.
@item -M
@itemx --mmap
Use memory mapping.
@item -m @var{mode}
@item --mode=@var{mode}
Sets the file mode. The argument is the desired file mode in octal.
@item -n
@itemx --no-meta
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
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.
User and group parts can be separated by a dot, instead of the colon.
@item -h
@itemx --help
Print a concise help summary.
@item -V
@itemx --version
Print program version and licensing information and exit.
@item --usage
Print a terse invocation syntax summary along with a list of available
command line options.
@end table
@node Exit codes
@chapter Exit codes
@cindex exit code
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
@item 0 @tab Successful termination.
@item 1 @tab A fatal error occurred.
@item 2 @tab Program was unable to restore file ownership or mode.
@item 3 @tab Command line usage error.
@end multitable
@node Bugs
@chapter Problems and bugs
If you have problems with GNU @code{dbm} or think you've found a bug,
please report it. Before reporting a bug, make sure you've actually
found a real bug. Carefully reread the documentation and see if it
really says you can do what you're trying to do. If it's not clear
whether you should be able to do something or not, report that too; it's
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 @command{GDBM} gave you. Also
say what you expected to occur; this will help us decide whether the
problem was really in the documentation.
Once you've got a precise problem, send e-mail to
@email{bug-gdbm@@gnu.org}.
Please include the version number of GNU @code{dbm} you are using. You can get
this information by printing the variable @code{gdbm_version}
(@pxref{Variables}).
Non-bug suggestions are always welcome as well. If you have questions
about things that are unclear in the documentation or are just obscure
features, please report them too.
You may contact the authors and maintainers by e-mail:
Philip Nelson @email{phil@@cs.wwu.edu},
Jason Downs @email{downsj@@downsj.com},
Sergey Poznyakoff @email{gray@@gnu.org} or @email{gray@@gnu.org.ua}.
Crash tolerance support written by Terence Kelly
@email{tpkelly@@acm.org}, @email{tpkelly@@cs.princeton.edu}, or
@email{tpkelly@@eecs.umich.edu}.
@node Resources
@chapter Additional resources
For the latest updates and pointers to additional resources, visit
@uref{http://www.gnu.org/@/software/@/gdbm}.
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 @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},
or from any
@ifhtml
@uref{http://www.gnu.org/order/ftp.html,,GNU mirror} worldwide.
@end ifhtml
@ifnothtml
GNU mirror worldwide. See @uref{http://www.gnu.org/@/order/@/ftp.html},
for a list of mirrors.
@end ifnothtml
To track @command{GDBM} development, visit
@uref{http://puszcza.gnu.org.ua/@/projects/@/gdbm}.
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texi
@node Index
@unnumbered Index
@printindex cp
@ifset WEBDOC
@ifhtml
@node This Manual in Other Formats
@unnumbered This Manual in Other Formats
@include otherdoc.texi
@end ifhtml
@end ifset
@bye
gdbm-1.23/doc/gendocs.pl 0000644 0001750 0001750 00000026526 14164261602 012032 0000000 0000000 # This file is part of GNU Pies.
# Copyright (C) 2020-2021 Sergey Poznyakoff
#
# GNU Pies is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3, or (at your option)
# any later version.
#
# GNU Pies is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with GNU Pies. If not, see .
use strict;
use warnings;
use Getopt::Long qw(:config gnu_getopt no_ignore_case);
use File::Basename;
use File::Spec;
use File::Path qw(make_path);
use Pod::Usage;
my $dirname = '.';
my $pkgname;
my $srcname;
my $output_name;
my @includes;
GetOptions("h" => sub {
pod2usage(-message => "$0: generate docs",
-exitstatus => 0);
},
"help" => sub {
pod2usage(-exitstatus => 0, -verbose => 2);
},
"usage" => sub {
pod2usage(-exitstatus => 0, -verbose => 0);
},
'source|s=s' => \$srcname,
'directory|C=s' => \$dirname,
'output|o=s' => \$output_name,
'include|I=s@' => \@includes
) or exit(1);
$pkgname = shift @ARGV or pod2usage(-exitstatus => 1, -verbose => 0);
$srcname //= "${pkgname}.texi";
my $template_name = shift @ARGV or pod2usage(-exitstatus => 1, -verbose => 0);
unless (-d $dirname) {
make_path($dirname);
}
unless ($output_name) {
$output_name = File::Spec->catfile($dirname, (fileparse($template_name, qr/\.[^.]*/))[0]);
}
if (@includes) {
@includes = map { '-I '.$_} @includes;
# FIXME: Not used yet
}
sub template_scan {
my $file = shift;
open(FH, '<', $file) or die "can't open $file: $!\n";
my $line = 0;
while () {
chomp;
++$line;
s{ \$ ((?:BASE)?FILE|SIZE) \( ([a-z_]+) \) }{
eval { Gendocs->instance($2, $pkgname, $srcname) };
if ($@) {
if ($@ =~ m{Can't locate object method "new"}) {
die "$file:$line: unknown format: $2\n";
} else {
die $@;
}
}
}gex;
}
close FH
}
sub template_expand {
my ($infile, $outfile) = @_;
open(IFH, '<', $infile) or die "can't open $infile: $!\n";
open(OFH, '>', $outfile) or die "can't open $outfile: $!\n";
while () {
chomp;
s{ \$ ((?:BASE)?FILE|SIZE) \( ([a-z_]+) \) }{
if ($1 eq 'FILE') {
Gendocs->instance($2)->output;
} elsif ($1 eq 'BASEFILE') {
basename(Gendocs->instance($2)->output);
} else {
Gendocs->instance($2)->size;
}
}gex;
print OFH "$_\n";
}
}
template_scan $template_name;
Gendocs->generate();
template_expand($template_name, $output_name);
Gendocs->sweep();
package Gendocs;
use strict;
use warnings;
my %registry;
sub generate {
my ($class) = @_;
my @keys = keys %registry;
foreach my $k (@keys) {
$registry{$k}->build();
$registry{$k}->mark();
}
}
sub sweep {
my ($class) = @_;
my @keys = keys %registry;
foreach my $k (@keys) {
unless ($registry{$k}->has_mark) {
$registry{$k}->remove;
delete $registry{$k};
}
}
}
sub new {
my ($class, $pkgname, $name) = @_;
unless (exists($registry{$class})){
$registry{$class} = bless { pkgname => $pkgname, input => $name }, $class;
}
return $registry{$class}
}
sub instance {
my ($class, $fmt, @args) = @_;
my $subclass = "Gendocs::".ucfirst($fmt);
unless (exists($registry{$subclass})) {
$registry{$subclass} = $subclass->new(@args);
}
return $registry{$subclass};
}
sub runcom {
my $self = shift;
system @_;
if ($? == -1) {
die "failed to execute $_[0]: $!";
} elsif ($? & 127) {
die sprintf("$_[0] died with signal %d\n", $? & 127);
} elsif ($? >> 8) {
warn sprintf("$_[0] exited with value %d\n", $? >> 8);
}
}
sub mark { shift->{mark} = 1 }
sub has_mark { shift->{mark} }
sub remove {
my ($self) = @_;
if ($self->{output}) {
unlink $self->{output};
delete $self->{output};
}
}
sub size {
my ($self) = @_;
my $s = (stat($self->output))[7];
if ($s > 1048576) {
$s = int($s / 1048576) . 'M';
} elsif ($s > 1024) {
$s = int($s / 1024) . 'K';
}
return $s;
}
sub pkgname { shift->{pkgname} }
sub input { shift->{input} }
sub output { shift->{output} }
package Gendocs::Makeinfo;
use strict;
use warnings;
use base 'Gendocs';
sub new {
my $class = shift;
my $self = $class->SUPER::new(@_);
$self->{makeinfo} = $ENV{'MAKEINFO'} || 'makeinfo';
return $self;
}
package Gendocs::Info;
use strict;
use warnings;
use base 'Gendocs::Makeinfo';
sub build {
my ($self) = @_;
unless ($self->{output}) {
my $output = File::Spec->catfile($dirname, $self->pkgname . '.info');
print "Generating info file: " . $self->input . " -> $output\n";
$self->runcom("$self->{makeinfo} -o $output " . $self->input);
$self->{output} = $output;
}
return $self->{output};
}
package Gendocs::Info_gz;
use strict;
use warnings;
use base 'Gendocs';
sub build {
my ($self) = @_;
unless ($self->{output}) {
my $input = Gendocs->instance('info', $self->pkgname, $self->input)->build();
my $output = "$input.gz";
print "Compressing info file: $input -> $output\n";
$self->runcom("gzip -f -9 -c $input > $output");
$self->{output} = $output;
}
return $self->{output};
}
package Gendocs::Ascii;
use strict;
use warnings;
use base 'Gendocs::Makeinfo';
sub build {
my ($self) = @_;
unless ($self->{output}) {
my $output = File::Spec->catfile($dirname, $self->pkgname . '.txt');
print "Generating ascii file: " . $self->input . " -> $output\n";
$self->runcom("$self->{makeinfo} -o $output --no-split --no-headers " . $self->input);
$self->{output} = $output;
}
return $self->{output};
}
package Gendocs::Ascii_gz;
use strict;
use warnings;
use base 'Gendocs';
sub build {
my ($self) = @_;
unless ($self->{output}) {
my $input = Gendocs->instance('ascii', $self->pkgname, $self->input)->build();
my $output = "$input.gz";
print "Compressing ascii file: $input -> $output\n";
$self->runcom("gzip -f -9 -c $input > $output");
$self->{output} = $output;
}
return $self->{output};
}
package Gendocs::Texinfo_gz;
use strict;
use warnings;
use base 'Gendocs';
sub build {
my ($self) = @_;
unless ($self->{output}) {
my $output = File::Spec->catfile($dirname, $self->pkgname . '.tar.gz');
print "Creating compressed sources: $output\n";
$self->runcom("tar czfh $output *.texinfo *.texi *.txi *.eps 2>/dev/null || /bin/true");
$self->{output} = $output;
}
return $self->{output};
}
package Gendocs::Dvi;
use strict;
use warnings;
use base 'Gendocs';
sub new {
my $class = shift;
my $self = $class->SUPER::new(@_);
$self->{texi2dvi} = $ENV{'TEXI2DVI'} || 'texi2dvi --build=tidy -t @finalout';
return $self;
}
sub build {
my ($self) = @_;
unless ($self->{output}) {
my $output = File::Spec->catfile($dirname, $self->pkgname . '.dvi');
my $cmd = "$self->{texi2dvi} -o $output $self->{input}";
print "Creating dvi: $cmd\n";
$self->runcom($cmd);
$self->{output} = $output;
}
return $self->{output};
}
package Gendocs::Dvi_gz;
use strict;
use warnings;
use base 'Gendocs';
sub build {
my ($self) = @_;
unless ($self->{output}) {
my $input = Gendocs->instance('dvi', $self->pkgname, $self->input)->build();
my $output = "$input.gz";
print "Compressing dvi file: $input -> $output\n";
$self->runcom("gzip -f -9 -c $input > $output");
$self->{output} = $output;
}
return $self->{output};
}
package Gendocs::Pdf;
use strict;
use warnings;
use base 'Gendocs::Dvi';
sub build {
my ($self) = @_;
unless ($self->{output}) {
my $output = File::Spec->catfile($dirname, $self->pkgname . '.pdf');
my $cmd = "$self->{texi2dvi} -o $output --pdf $self->{input}";
print "Creating pdf: $cmd\n";
$self->runcom($cmd);
$self->{output} = $output;
}
return $self->{output};
}
__END__
=head1 NAME
gendocs.pl - generate documentation in various formats
=head1 SYNOPSIS
B
[B<-C> I]
[B<-s> I]
[B<-o> I]
[B<-I> I]
[B<--directory=>I]
[B<--include=>I]
[B<--output=>I]
[B<--source=>I]
I I
B B<-h> | B<--help> | B<--usage>
=head1 DESCRIPTION
Generates documentation for the I in various formats. I
is a template file for the index page. When processing I the
following I inform B about the desired documentation
formats and are expanded on output:
=over 4
=item B<$FILE(I)>
Full pathname of the documentation file in format I.
=item B<$BASEFILE(I)>
Base name of the documentation file for format I.
=item B<$SIZE(I)>
Size of the documentation file in format I. Proper size suffix
(B or B) is appended, as needed.
=back
The file is processed twice. On the first pass, the program collects the
mentioned Is. Then the requested files are generated. On the
second pass, the macros are replaced with the actual values and the output
index file is generated. The name of the index file can be supplied using
the B<-o> (B<--output>) option. If it is not given, the name is obtained
by removing last suffix (a substring beginning with a dot and containing
one or more characters, excepting dots) from the I argument.
Unless the B<-C> (B<--directory>) option is given, the output will be
generated in the current working directory. If the B<-C> option is
given, all output files, including index file, will be generated in
the supplied directory.
The following output formats are supported:
=over 4
=item B
Monolithic info file.
=item B
Monolithic info file, compressed with B
=item B
Monolithic ASCII file.
=item B
Monolithic ASCII file, compressed with B
=item B
A tar archive with the Texinfo documentation sources, compressed with B.
=item B
TeX B file.
=item B
TeX B file, compressed with B
=item B
A B file.
=back
=head1 OPTIONS
=over 4
=item B<-C>, B<--directory=>I
Create all output files in the directory I.
=item B<-s>, B<--source=>I
Name of the main Texinfo source file. By default F.texi> is
used.
=item B<-o>, B<--output=>I
Name of the output index file. By default it is constructed by removing
the last filename suffix from I. E.g. F produces
F.
=item B<-I>, B<--include=>I
Name of the directory with Texinfo include files. This option is not
actually used. It is reserved for future use.
=back
=head1 ENVIRONMENT
The following environment variables affect the behavior of B:
=over 4
=item B
Name and initial options of the B program.
=item B
Name and initial options of the B program. The default is
F.
=item B
Used by F. Colon-separated list of Texinfo input directories.
=back
=cut
gdbm-1.23/doc/Makefile.am 0000644 0001750 0001750 00000005104 14164261602 012074 0000000 0000000 # This file is part of GDBM. -*- Makefile -*-
# Copyright (C) 2007-2022 Free Software Foundation, Inc.
#
# GDBM is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3, or (at your option)
# any later version.
#
# GDBM is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with GDBM. If not, see . */
# Documentation
info_TEXINFOS = gdbm.texi
gdbm_TEXINFOS=\
fdl.texi
dist_man_MANS = gdbm.3 gdbm_dump.1 gdbm_load.1 gdbmtool.1
GENDOCS = perl gendocs.pl
EXTRA_DIST = gendocs.pl webdoc.init htmlxref.cnf
TEXI2DVI=texi2dvi -t '@set $(RENDITION)'
# Make sure you set TEXINPUTS.
# TEXINPUTS=/usr/share/texmf/pdftex/plain/misc/ is ok for most distributions
.PHONY: manual
manual:
rm -rf manual
TEXINPUTS=$(srcdir):$(top_srcdir)/build-aux:$(TEXINPUTS) \
MAKEINFO="$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS)" \
TEXI2DVI="$(TEXI2DVI) -t @finalout" \
$(GENDOCS) -C manual -o otherdoc.texi $(PACKAGE) otherdoc.texi.in
$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -DWEBDOC \
--html --init-file=webdoc.init $(info_TEXINFOS) -o manual
# Checking
check-tabs:
@if test -n "`cat $(info_TEXINFOS) $(gdbm_TEXINFOS) | tr -d -c '\t'`"; then \
echo "Sources contain tabs; run make untabify"; \
false; \
fi
check-sentence-spacing:
@if grep -q '\. [@A-Z]' $(info_TEXINFOS) $(gdbm_TEXINFOS); then \
echo >&2 "Sources contain single-space sentence separators"; \
echo >&2 "Run make fix-sentence-spacing to fix"; \
fi
check-fixmes:
@for file in $(info_TEXINFOS) $(gdbm_TEXINFOS); \
do \
sed -e = $$file | \
sed -n 'N;/@c *FIXME:/{s/\(^[0-9][0-9]*\).*@c *FIXME:\(.*\)/'$$file':\1: \2/gp}'; \
done > $@-t; \
if [ -s $@-t ]; then \
echo "Unresolved FIXMEs:"; \
cat $@-t; \
rm $@-t; \
false; \
else \
rm -f $@-t; \
fi
check-format: check-tabs check-sentence-spacing
check-docs: check-format check-fixmes
untabify:
emacs -batch -l untabify.el $(info_TEXINFOS) $(gdbm_TEXINFOS)
fix-sentence-spacing:
for file in $(info_TEXINFOS) $(gdbm_TEXINFOS); \
do \
if grep -q '\. [@A-Z]' $$file; then \
mv $$file $${file}~; \
sed -r 's/\. ([@A-Z])/. \1/g' $${file}~ > $$file; \
fi; \
done
final: untabify fix-sentence-spacing
gdbm-1.23/doc/gdbmtool.1 0000644 0001750 0001750 00000034334 14164261602 011740 0000000 0000000 .\" This file is part of GDBM. -*- nroff -*-
.\" Copyright (C) 2013-2022 Free Software Foundation, Inc.
.\"
.\" GDBM is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
.\" GDBM is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with GDBM. If not, see . */
.TH GDBMTOOL 1 "August 1, 2021" "GDBM" "GDBM User Reference"
.SH NAME
gdbmtool \- examine and modify a GDBM database
.SH SYNOPSIS
\fBgdbmtool\fR\
[\fB\-lmNnqrs\fR]\
[\fB\-b\fR \fISIZE\fR]\
[\fB\-c\fR \fISIZE\fR]\
[\fB\-f\fR \fIFILE\fR]\
[\fB\-\-block\-size\fR=\fISIZE\fR]\
[\fB\-\-cache\-size\fR=\fISIZE\fR]\
[\fB\-\-file\fR \fIFILE\fR]\
[\fB\-\-newdb\fR]\
[\fB\-\-no\-lock\fR]\
[\fB\-\-no\-mmap\fR]\
[\fB\-\-norc\fR]\
[\fB\-\-quiet\fR]\
[\fB\-\-read\-only\fR]\
[\fB\-\-synchronize\fR]\
[\fIDBFILE\fR] [\fICOMMAND\fR [; \fICOMMAND\fR...]]
.sp
\fBgdbmtool\fR\
[\fB\-Vh\fR]\
[\fB\-\-help\fR]\
[\fB\-\-usage\fR]\
[\fB\-\-version\fR]
.SH DESCRIPTION
The
.B gdbmtool
utility allows you to view and modify an existing GDBM database or to
create a new one.
.PP
The \fIDBFILE\fR argument supplies the name of the database to open.
If not supplied, the default name
.B junk.gdbm
is used instead.
If the named database does not exist, it will be created. An existing
database can be cleared (i.e. all records removed from it) using the
\fB\-\-newdb\fR option (see below).
.PP
Unless the \fB\-N\fR (\fB\-\-norc\fR) option is given, after startup
.B gdbmtool
looks for file named
.B .gdbmtoolrc
first in the current working directory, and, if not found there, in
the home directory of the user who started the program. If found,
this file is read and interpreted as a list of
.B gdbmtool
commands.
.PP
Then
.B gdbmtool
starts a loop, in which it reads
commands from the standard input, executes them and prints the results on the
standard output. If the standard input is attached to a console,
the program runs in interactive mode.
.PP
The program terminates when the
.B quit
command is given, or end-of-file is detected on its standard input.
.PP
Commands can also be specified in the command line, after the \fIDBFILE\fR
argument. In this case, they will be interpreted without attempting to
read more commands from the standard input.
.PP
If several commands are supplied, they must be separated by
semicolons (properly escaped or quoted, in order to prevent them from
being interpreted by the shell).
.PP
A
.B gdbmtool
command consists of a command verb, optionally
followed by one or more arguments, separated by any amount of white
space. A command verb can be entered either in full or in an
abbreviated form, as long as that abbreviation does not match any other
verb.
.PP
Any sequence of non-whitespace characters appearing after the command
verb forms an argument. If the argument contains whitespace or
unprintable characters it must be enclosed in double quotes. Within
double quotes the usual escape sequences are understood, as
shown in the table below:
.sp
.nf
.ta 8n 20n
.ul
Escape Expansion
\\a Audible bell character (ASCII 7)
\\b Backspace character (ASCII 8)
\\f Form-feed character (ASCII 12)
\\n Newline character (ASCII 10)
\\r Carriage return character (ASCII 13)
\\t Horizontal tabulation character (ASCII 9)
\\v Vertical tabulation character (ASCII 11)
\\\\ Single slash
\" Double quote
.fi
.PP
In addition, a backslash immediately followed by the end-of-line
character effectively removes that character, allowing to split long
arguments over several input lines.
.SH OPTIONS
.TP
\fB\-b\fR, \fB\-\-block\-size\fR=\fISIZE\fR
Set block size.
.TP
\fB\-c\fR, \fB\-\-cache\-size\fR=\fISIZE\fR
Set cache size.
.TP
\fB\-f\fR, \fB\-\-file\fR=\fIFILE\fR
Read commands from \fIFILE\fR, instead of from the standard input.
.TP
\fB\-l\fR, \fB\-\-no\-lock\fR
Disable file locking.
.TP
\fB\-m\fR, \fB\-\-no\-mmap\fR
Do not use
.BR mmap (2).
.TP
\fB\-n\fR, \fB\-\-newdb\fR
Create the database, truncating it if it already exists.
.TP
\fB\-q\fR, \fB\-\-quiet\fR
Don't print initial banner.
.TP
\fB\-r\fR, \fB\-\-read\-only\fR
Open database in read-only mode.
.TP
\fB\-s\fR, \fB\-\-synchronize\fR
Synchronize to disk after each write.
.TP
\fB\-h\fR, \fB\-\-help\fR
Print a short usage summary.
.TP
\fB\-\-usage\fR
Print a list of available options.
.TP
\fB\-V\fR, \fB\-\-version\fR
Print program version
.SH SHELL COMMANDS
.TP
.BR avail
Print the
.BR "avail list" .
.TP
\fBbucket\fR \fINUM\fR
Print the bucket number \fINUM\fR and set is as the current one.
.TP
.BR cache
Print the bucket cache.
.TP
.B close
Close the currently open database.
.TP
.BR count
Print the number of entries in the database.
.TP
.BR current
Print the current bucket.
.TP
\fBdelete\fR \fIKEY\fR
Delete record with the given \fIKEY\fR.
.TP
.BR dir
Print hash directory.
.TP
.BR downgrade
Downgrade the database from the extended \fInumsync\fR format to the
standard format.
.TP
\fBexport\fR \fIFILE\-NAME\fR [\fBtruncate\fR] [\fBbinary\fR|\fBascii\fR]
Export the database to the flat file \fIFILE\-NAME\fR. This is equivalent to
.BR gdbm_dump (1).
This command will not overwrite an existing file, unless the
.B truncate
parameter is also given. Another optional parameter determines the type of
the dump (*note Flat files::). By default, ASCII dump will be created.
.TP
\fBfetch\fR \fIKEY\fR
Fetch and display the record with the given \fIKEY\fR.
.TP
.BR first
Fetch and display the first record in the database. Subsequent
records can be fetched using the
.B next
command (see below).
.TP
\fBhash\fR \fIKEY\fR
Compute and display the hash value for the given \fIKEY\fR.
.TP
.BR header
Print file header.
.TP
.BR help " or " ?
Print a concise command summary, showing each command letter and
verb with its parameters and a short description of what it does.
Optional arguments are enclosed in square brackets.
.TP
.B history
Shows the command history list with line numbers. This command is
available only if the program was compiled with GNU Readline.
.TP
\fBhistory\fR \fICOUNT\fR.
Shows \fICOUNT\fR latest commands from the command history.
.TP
\fBhistory\fR \fIN\fR \fICOUNT\fR.
Shows \fICOUNT\fR commands from the command history starting with \fIN\fRth
command.
.TP
\fBimport\fR \fIFILE\-NAME\fR [\fBreplace\fR] [\fBnometa\fR]
Import data from a flat dump file \fIFILE\-NAME\fR.
If the
.B replace
argument is given, any records with the same keys as the already
existing ones will replace them. The
.B nometa
argument turns off restoring meta-information from the dump file.
.TP
\fBlist\fR
List the contents of the database.
.TP
\fBnext\fR [\fIKEY\fR]
Sequential access: fetch and display the next record. If the \fIKEY\fR is
given, the record following the one with this key will be fetched.
.TP
\fBopen\fR \fIFILE\fR
Open the database file \fIFILE\fR. If successful, any previously
open database is closed. Otherwise, if the operation fails, the
currently opened database remains unchanged.
This command takes additional information from the variables
.BR open ,
.BR lock ,
.BR mmap ", and"
.BR sync .
See the section
.BR VARIABLES ,
for a detailed description of these.
.TP
.B quit
Close the database and quit the utility.
.TP
.BR reorganize
Reorganize the database.
.TP
\fBset\fR [\fIVAR\fR=\fIVALUE\fR...]
Without arguments, lists variables and their values. If arguments are
specified, sets variables. Boolean variables can be set by specifying
variable name, optionally prefixed with \fBno\fR, to set it to
\fBfalse\fR.
.TP
\fBsnapshot\fR \fIFILE\fR \fIFILE\fR
Analyzes two database snapshots and selects the most recent of them.
In case of error, prints a detailed diagnostics. Use this command to
manually recover from a crash. For details, please refer to the chapter
.B "Crash Tolerance"
in the
.BR "GDBM manual" .
.TP
\fBsource\fR \fIFILE\fR
Read commands from the given \fIFILE\fR.
.TP
.BR status
Print current program status.
.TP
\fBstore\fR \fIKEY\fR \fIDATA\fR
Store the \fIDATA\fR with the given \fIKEY\fR in the database. If the
\fIKEY\fR already exists, its data will be replaced.
.TP
.B sync
Synchronize the database file with the disk storage.
.TP
.B upgrade
Upgrade the database from the standard to the extended \fInumsync\fR
format.
.TP
\fBunset\fR \fIVARIABLE\fR...
Unsets listed variables.
.TP
.BR version
Print the version of
.BR gdbm .
.SH "DATA DEFINITIONS"
The \fBdefine\fR statement provides a mechanism for defining key or
content structures. It is similar to the \fBC\fR \fBstruct\fR
declaration:
.sp
.nf
.in +4
\fBdefine\fR \fBkey\fR|\fBcontent\fR \fB{\fR \fIdefnlist\fR \fB}\fR
.in
.fi
.PP
The \fIdefnlist\fR is a comma-separated list of member declarations.
Within \fIdefnlist\fR the newline character looses its special meaning
as the command terminator, so each declaration can appear on a
separate line and arbitrary number of comments can be inserted to
document the definition.
.PP
Each declaration has one of the following formats
.sp
.nf
.in +4
\fItype\fR \fIname\fR
\fItype\fR \fIname\fR \fB[\fIN\fB]\fR
.in
.fi
.sp
where \fItype\fR is a data type and \fIname\fR is the member name.
The second format defines the member \fIname\fR as an array of \fIN\fR
elements of \fItype\fR.
.PP
The supported types are:
.sp
.nf
.ta 8n 20n
.ul
type meaning
char single byte (signed)
short signed short integer
ushort unsigned short integer
int signed integer
unsigned unsigned integer
uint ditto
long signed long integer
ulong unsigned long integer
llong signed long long integer
ullong unsigned long long integer
float a floating point number
double double-precision floating point number
string array of characters (see the \fBNOTE\fR below)
stringz null-terminated string of characters
.fi
.PP
The following alignment declarations can be used within \fIdefnlist\fR:
.TP
\fBoffset\fR \fIN\fR
The next member begins at offset \fIN\fR.
.TP
\fBpad\fR \fIN\fR
Add \fIN\fR bytes of padding to the previous member.
.PP
For example:
.sp
.nf
.in +4
\fBdefine content {
int status,
pad 8,
char id[3],
stringz name
}\fR
.fi
.PP
To define data consisting of a single data member, the following
simplified construct can be used:
.sp
.nf
.in +4
\fBdefine\fR \fBkey\fR|\fBcontent\fR \fItype\fR
.fi
.PP
where \fItype\fR is one of the types discussed above.
.PP
\fBNOTE\fR: The \fBstring\fR type can reasonably be used only if it is
the last or the only member of the data structure. That's because it
provides no information about the number of elements in the array, so
it is interpreted to contain all bytes up to the end of the datum.
.SH VARIABLES
.TP
.BR confirm ", boolean"
Whether to ask for confirmation before certain destructive operations,
such as truncating the existing database. Default is
.BR true .
.TP
.BR ps1 ", string"
Primary prompt string. Its value can contain \fIconversion
specifiers\fR, consisting of the \fB%\fR character followed by another
character. These specifiers are expanded in the resulting prompt as
follows:
.sp
.nf
.ta 8n 20n
.ul
Sequence Expansion
\fB%f\fR name of the db file
\fB%p\fR program name
\fB%P\fR package name (\fBgdbm\fR)
\fB%_\fR horizontal space (\fBASCII\fR 32)
\fB%v\fR program version
\fB%%\fR \fB%\fR
.fi
.sp
The default prompt is \fB%p>%_\fR.
.TP
.BR ps2 ", string"
Secondary prompt. See
.B ps1
for a description of its value.
This prompt is displayed before reading the second and subsequent
lines of a multi-line command.
The default value is \fB%_>%_\fR.
.TP
.BR delim1 ", string"
A string used to delimit fields of a structured datum on output
(see the section \fBDATA DEFINITIONS\fR).
Default is \fB,\fR (a comma). This variable cannot be unset.
.TP
.BR delim2 ", string"
A string used to delimit array items when printing a structured datum.
Default is \fB,\fR (a comma). This variable cannot be unset.
.TP
.BR pager ", string"
The name and command line of the pager program to pipe output to.
This program is used in interactive mode when the estimated number of
output lines is greater then the number of lines on your screen.
The default value is inherited from the environment variable
\fBPAGER\fR. Unsetting this variable disables paging.
.TP
.BR quiet ", boolean"
Whether to display welcome banner at startup. This variable should
be set in a startup script file.
.PP
The following variables control how the database is opened:
.TP
.BR cachesize ", numeric"
Sets the cache size. By default this variable is not set.
.TP
.BR blocksize ", numeric"
Sets the block size. Unset by default.
.TP
.BR open ", string"
Open mode. The following values are allowed:
.RS 7
.TP
.BR newdb
Truncate the database if it exists or create a new one. Open it in
read-write mode.
.TP
.BR wrcreat " or " rw
Open the database in read-write mode. Create it if it does not
exist. This is the default.
.TP
.BR reader " or " readonly
Open the database in read-only mode. Signal an error if it does not
exist.
.RE
.TP
.BR filemode ", octal"
Sets the file mode for newly created database files. Default is 0644.
.TP
.BR lock ", boolean"
Lock the database. This is the default.
.TP
.BR mmap ", boolean"
Use memory mapping. This is the default.
.TP
.BR coalesce ", boolean"
When set, this option causes adjacent free blocks to be merged which
allows for more efficient memory management at the expense of a
certain increase in CPU usage.
.TP
.BR centfree ", boolean"
Enables central free block pool. This causes all free blocks of space
to be placed in the global pool, thereby speeding up the allocation of
data space.
.SH "SEE ALSO"
.BR gdbm_dump (1),
.BR gdbm_load (1),
.BR gdbm (3).
.SH "REPORTING BUGS"
Report bugs to .
.SH COPYRIGHT
Copyright \(co 2013-2021 Free Software Foundation, Inc
.br
.na
License GPLv3+: GNU GPL version 3 or later
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH GDBM[A-Z_-]* 1 \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end:
gdbm-1.23/doc/gdbm_dump.1 0000644 0001750 0001750 00000005453 14164261602 012067 0000000 0000000 .\" This file is part of GDBM.
.\" Copyright (C) 2013-2022 Free Software Foundation, Inc.
.\"
.\" GDBM is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
.\" GDBM is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with GDBM. If not, see . */
.TH GDBM_DUMP 1 "May 8, 2013" "GDBM" "GDBM User Reference"
.SH NAME
gdbm_dump \- dump a GDBM database to a file
.SH SYNOPSIS
\fBgdbm_dump\fR [\fB\-H \fIFMT\fR] [\fB\-\-format\fR=\fIFMT\fR] \fIDB_FILE\fR [\fIFILE\fR]
.sp
\fBgdbm_dump\fR [\fB\-Vh\fR] [\fB\-\-help\fR] [\fB\-\-usage\fR] [\fB\-\-version\fR]
.SH DESCRIPTION
The
.B gdbm_dump
utility creates a dump of the specified
.BR gdbm (3)
database file. The name for the output dump file is supplied by the
second argument (\fIFILE\fR). If not specified, the output goes to
the standard error.
.PP
The created dump can be given as argument to the
.BR gdbm_load (1)
utility in order to re-create an exact copy of the \fIDB_FILE\fR.
.SH OPTIONS
.TP
\fB\-H\fR, \fB\-\-format\fR=\fIFMT\fR
Select dump format. The value \fBbinary\fR (or \fB0\fR) instructs
.B gdbm_dump
to produce a binary dump, compatible with earlier
.B gdbm
versions (up to version 1.9). The value \fBascii\fR (or \fB1\fR)
instructs it to create an ASCII dump (this is the default). The
latter is preferred because, apart from the actual data, it also
contains meta-information which will allow
.BR gdbm_load (1)
to recreate an exact copy of the file.
.TP
\fB\-h\fR, \fB\-\-help\fR
Print a short usage summary.
.TP
\fB\-\-usage\fR
Print a list of available options.
.TP
\fB\-V\fR, \fB\-\-version\fR
Print program version
.SH "SEE ALSO"
.BR gdbm_load (1),
.BR gdbmtool (1),
.BR gdbm (3).
.PP
For a detailed description of
.B gdbm_dump
and other
.B gdbm
utilities, refer to the \fBGDBM Manual\fR available in
Texinfo format. To access it, run:
\fBinfo gdbm\fR
.SH "REPORTING BUGS"
Report bugs to .
.SH COPYRIGHT
Copyright \(co 2013-2021 Free Software Foundation, Inc
.br
.na
License GPLv3+: GNU GPL version 3 or later
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH GDBM[A-Z_-]* 1 \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end:
gdbm-1.23/doc/version.texi 0000644 0001750 0001750 00000000140 14177230744 012422 0000000 0000000 @set UPDATED 2 January 2022
@set UPDATED-MONTH January 2022
@set EDITION 1.23
@set VERSION 1.23
gdbm-1.23/doc/htmlxref.cnf 0000644 0001750 0001750 00000000630 14164261602 012360 0000000 0000000 GNU=http://www.gnu.org/software
READLINE=${GNU}/readline/manual
readline mono ${READLINE}/readline.html
readline node ${READLINE}/html_node/
readline section ${READLINE}/html_section/
readline chapter ${READLINE}/html_chapter/
open(2) mono https://man.gnu.org.ua/2/open
stat(2) mono https://man.gnu.org.ua/2/stat
chmod(2) mono https://man.gnu.org.ua/2/chmod
printf(3) mono https://man.gnu.org.ua/3/printf
gdbm-1.23/doc/webdoc.init 0000644 0001750 0001750 00000000466 14164261602 012176 0000000 0000000 use strict;
use warnings;
set_from_init_file('EXTRA_HEAD', qq{
});
gdbm-1.23/doc/gdbm.info 0000644 0001750 0001750 00000601321 14177231124 011631 0000000 0000000 This is gdbm.info, produced by makeinfo version 6.7 from gdbm.texi.
Published by the Free Software Foundation, 51 Franklin Street, Fifth
Floor Boston, MA 02110-1301, USA
Copyright (C) 1989-1999, 2007-2022 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
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover, and no Back-Cover texts. A copy of
the license is included in the section entitled "GNU Free Documentation
License."
INFO-DIR-SECTION Programming & development tools
START-INFO-DIR-ENTRY
* GDBM: (gdbm). The GNU database manager.
* gdbm_dump: (gdbm) gdbm_dump. Dump the GDBM database into a flat file.
* gdbm_load: (gdbm) gdbm_load. Load the database from a flat file.
* gdbmtool: (gdbm) gdbmtool. Examine and modify a GDBM database.
END-INFO-DIR-ENTRY
File: gdbm.info, Node: Top, Next: Copying, Up: (dir)
The GNU database manager
************************
GNU 'dbm' ('GDBM') is a library of functions implementing a hashed
database on a disk file. This manual documents GNU 'dbm' Version 1.23.
The software was originally written by Philip A. Nelson. This document
was originally written by Pierre Gaumond from texts written by Phil.
* Menu:
* Copying:: Your rights.
* Intro:: Introduction to GNU dbm.
Functions:
* Open:: Opening the database.
* Close:: Closing the database.
* Count:: Counting records in the database.
* Store:: Inserting and replacing records in the database.
* Fetch:: Searching records in the database.
* Delete:: Removing records from the database.
* Sequential:: Sequential access to records.
* Reorganization:: Database reorganization.
* Sync:: Insure all writes to disk have competed.
* Database format:: GDBM database formats.
* Flat files:: Export and import to Flat file format.
* Errors:: Error handling.
* Database consistency:: Structural and logical consistency.
* Recovery:: Recovery from fatal errors.
* Crash Tolerance:: Ensuring recovery to a consistent state.
* Options:: Setting internal options.
* Locking:: File locking.
* Variables:: Useful global variables.
* Additional functions:: Functions for verifying internal structures.
* Error codes:: Error codes returned by GDBM calls.
* Compatibility:: Compatibility with UNIX dbm and ndbm.
Programs
* gdbmtool:: Examine and modify a GDBM database.
* gdbm_dump:: Dump the database into a flat file.
* gdbm_load:: Load the database from a flat file.
* Exit codes:: Exit codes returned by GDBM utilities.
Other topics:
* Bugs:: Problems and bugs.
* Resources:: Additional resources,
* GNU Free Documentation License:: Document license.
* Index:: Index
-- The Detailed Node Listing --
Compatibility with standard 'dbm' and 'ndbm'
* ndbm:: NDBM interface functions.
* dbm:: DBM interface functions.
Examine and modify a GDBM database
* invocation::
* shell::
gdbmtool interactive mode
* variables:: shell variables.
* commands:: shell commands.
* definitions:: how to define structured data.
* startup files::
File: gdbm.info, Node: Copying, Next: Intro, Prev: Top, Up: Top
1 Copying Conditions
********************
This library is "free"; this means that everyone is free to use it and
free to redistribute it on a free basis. GNU 'dbm' ('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 'GDBM'
that they might get from you.
Specifically, we want to make sure that you have the right to give
away copies of '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 of '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 '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.
'GDBM' is currently distributed under the terms of the GNU General
Public License, Version 3. (_NOT_ under the GNU General Library Public
License.) A copy the GNU General Public License is included with the
distribution of 'GDBM'.
File: gdbm.info, Node: Intro, Next: Open, Prev: Copying, Up: Top
2 Introduction to GNU 'dbm'
***************************
GNU 'dbm' ('GDBM') is a library of database functions that use
extensible hashing and work similar to the standard UNIX 'dbm'
functions. These routines are provided to a programmer needing to
create and manipulate a hashed database. ('GDBM' is _NOT_ a complete
database package for an end user.)
The basic use of '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 'GDBM' is the structure:
typedef struct
{
char *dptr;
int dsize;
} datum;
This structure allows for arbitrary sized keys and data items. In
particular, zero-length keys or data ('dsize = 0') are allowed.
However, the 'dptr' field is required to point to a valid memory
location. In other words, 'dptr' cannot be NULL. Note also that its
type is '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 'GDBM' disk file, called a "gdbm
database". An application must open a 'GDBM' database to be able
manipulate the keys and data contained in it. 'GDBM' allows an
application to have multiple databases open at the same time. When an
application opens a 'GDBM' database, it is designated as a 'reader' or a
'writer'. A '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 'GDBM' database at the same time.
Speaking about "application" we usually mean a separate process.
However, it is entirely normal for a multi-thread program to operate as
a 'GDBM' reader in one thread and writer in another, provided, of
course, that the two threads don't operate on the same database
simultaneously.
To use the 'GDBM' functions, the programmer must first include the
header file 'gdbm.h'.
This file defines, among others, the '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
'gdbm_open' function. The function takes several arguments, the name of
the database file being one of them, and returns a '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 "closes" it using the 'gdbm_close' call.
These and other functions are discussed in detail in chapters that
follow. Here we show an example illustrating the use of 'GDBM' to look
up a key in the database.
#include
#include
#include
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;
}
To compile this example, run
cc -oexample example.c -lgdbm
To run it, you will need an example database. The easiest way to
create it is by using the 'gdbtool' program, which is part of the 'GDBM'
package (*note gdbmtool::):
$ gdbmtool test.gdbm store foo bar
This creates database file 'test.gdbm' and stores a single record in it.
The record's key is 'foo', and the value is 'bar'. Now you can run the
example program to see how it works:
$ ./example test.gdbm foo
bar
$ ./example test.gdbm baz
no such key
File: gdbm.info, Node: Open, Next: Close, Prev: Intro, Up: Top
3 Opening the database
**********************
-- gdbm interface: GDBM_FILE gdbm_open (const char *NAME, int
BLOCK_SIZE, int FLAGS, int MODE, void (*FATAL_FUNC)(const char
*))
Opens or creates a 'GDBM' database file.
The arguments are:
NAME
The name of the file (the complete name, 'GDBM' does not
append any characters to this name).
BLOCK_SIZE
This parameter is used only when '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 'GDBM_BSEXACT' flag is set and the
size needs to be adjusted, the function will return with error
status, setting the 'gdbm_errno' variable to
'GDBM_BLOCK_SIZE_ERROR'.
FLAGS
If 'flags' is set to 'GDBM_READER', the user wants to just
read the database and any call to 'gdbm_store' or
'gdbm_delete' will fail. Many readers can access the database
at the same time. If 'flags' is set to 'GDBM_WRITER', the
user wants both read and write access to the database and
requires exclusive access. If 'flags' is set to
'GDBM_WRCREAT', the user wants both read and write access to
the database and wants it created if it does not already
exist. If 'flags' is set to 'GDBM_NEWDB', the user want a new
database created, regardless of whether one existed, and wants
read and write access to the new database. If an existing
database file is opened with the 'GDBM_NEWDB' flag, the
existing data are destroyed, and an empty database structure
is created in its place.
The following constants may also be logically or'd into the
database flags:
-- gdbm_open flag: GDBM_CLOEXEC
Set the close-on-exec flag on the database file
descriptor. The 'libc' must support the 'O_CLOEXEC' flag
(*note (open(2))O_CLOEXEC::).
-- gdbm_open flag: GDBM_NOLOCK
Don't lock the database file. Use this flag if you
intend to do locking separately. *Note Locking::.
-- gdbm_open flag: GDBM_NOMMAP
Disable memory mapping mechanism. Note, that this
degrades performance.
-- gdbm_open flag: GDBM_PREREAD
When mapping 'GDBM' file to memory, read its contents
immediately, instead of when needed ("prefault reading").
This can be advantageous if you open a _read-only_
database and are going to do a lot of look-ups on it. In
this case entire database will be pre-read and look-ups
will operate on an in-memory copy. In contrast,
'GDBM_PREREAD' should not be used if you open a database
(even in read-only mode) only to do a couple of look-ups.
Finally, never use 'GDBM_PREREAD' when opening a database
for updates, especially for inserts: this will degrade
performance.
This flag has no effect if 'GDBM_NOMMAP' is given, or if
the operating system does not support prefault reading.
It is known to work on Linux and FreeBSD kernels.
-- 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.
*Note Additional functions::.
The following additional flags are valid when the database is
opened for writing (i.e. together with 'GDBM_WRITER',
'GDBM_WRCREAT', or 'GDBM_NEWDB'):
-- 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 (*note Sync::). *Note Crash
Tolerance::, for a discussion of how to ensure database
consistency with minimal performance overhead.
-- gdbm_open flag: GDBM_FAST
A reverse of 'GDBM_SYNC'. Synchronize writes only when
needed. This is the default. The flag is provided for
compatibility with previous versions of 'GDBM'.
The following flags can be used together with 'GDBM_NEWDB'.
They also take effect when used with 'GDBM_WRCREAT', if the
requested database file doesn't exist:
-- gdbm_open flag: GDBM_BSEXACT
If this flag is set and the requested BLOCK_SIZE cannot
be used without adjustment, 'gdbm_open' will refuse to
create the databases. In this case it will set the
'gdbm_errno' variable to 'GDBM_BLOCK_SIZE_ERROR' and
return 'NULL'.
-- gdbm_open flag: GDBM_NUMSYNC
Useful only together with 'GDBM_NEWDB', this bit
instructs 'gdbm_open' to create new database in "extended
database format", a format best suitable for effective
crash recovery. *Note Numsync::, for a detailed
discussion of this format, and *note Crash Tolerance::,
for a discussion of crash recovery.
MODE
File mode(1), which is used if the file is created.
FATAL_FUNC
This parameter is deprecated and must always be 'NULL'.
Early versions of '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, 'fatal_func' was provided as a hook, allowing the
caller to do proper cleanup before such abnormal exit. As of
version 1.23, this functionality is deprecated, although still
supported for backward compatibility.
The return value, is the pointer needed by all other functions to
access that 'GDBM' file. If the return is the 'NULL' pointer,
'gdbm_open' was not successful. The errors can be found in
'gdbm_errno' variable (*note gdbm_errno: Variables.). Available
error codes are discussed in *note Error codes::.
In all of the following calls, the parameter DBF refers to the
pointer returned from 'gdbm_open' (or 'gdbm_fd_open', described
below).
-- gdbm interface: GDBM_FILE gdbm_fd_open (int FD, const char *NAME,
int BLOCK_SIZE, int FLAGS, int MODE, void (*FATAL_FUNC)(const
char *))
Alternative function for opening a 'GDBM' database. The FD
argument is the file descriptor of the database file obtained by a
call to 'open'(2), 'creat'(2) or similar functions. The descriptor
is not dup'ed, and will be closed when the returned 'GDBM_FILE' is
closed. Use 'dup'(2) if that is not desirable.
In case of error, the function behaves like 'gdbm_open' and _does
not close_ FD. This can be altered by the following value passed
in the FLAGS argument:
-- gdbm_open flag: GDBM_CLOERROR
Close FD before exiting on error.
-- gdbm interface: int gdbm_copy_meta (GDBM_FILE DST, GDBM_FILE SRC)
Copy file ownership and mode from SRC to DST.
---------- Footnotes ----------
(1) *Note (chmod(2))chmod::, and *Note open a file: (open(2))open.
File: gdbm.info, Node: Close, Next: Count, Prev: Open, Up: Top
4 Closing the database
**********************
It is important that every file opened is also closed. This is needed
to properly update its disk structure and maintain a consistent locking
state on the file.
-- gdbm interface: int gdbm_close (GDBM_FILE DBF)
This function closes the 'GDBM' file and frees all memory
associated with it. The parameter is:
DBF
The pointer returned by 'gdbm_open'.
'Gdbm_close' returns 0 on success. On error, it sets 'gdbm_errno'
and system 'errno' variables to the codes describing the error and
returns -1.
File: gdbm.info, Node: Count, Next: Store, Prev: Close, Up: Top
5 Number of Records
*******************
-- gdbm interface: int gdbm_count (GDBM_FILE DBF, gdbm_count_t *PCOUNT)
Counts the number of records in the database DBF. On success,
stores it in the memory location pointed to by PCOUNT and returns
0. On error, sets 'gdbm_errno' (if relevant, also 'errno') and
returns -1.
-- gdbm interface: int gdbm_bucket_count (GDBM_FILE DBF, size_t
*PCOUNT)
Counts the number of buckets in the database DBF. On success,
stores it in the memory location pointed to by PCOUNT and return 0.
On error, sets 'gdbm_errno' (if relevant, also 'errno') and returns
-1.
File: gdbm.info, Node: Store, Next: Fetch, Prev: Count, Up: Top
6 Inserting and replacing records in the database
*************************************************
-- gdbm interface: int gdbm_store (GDBM_FILE DBF, datum KEY, datum
CONTENT, int FLAG)
The function 'gdbm_store' inserts or replaces records in the
database.
The parameters are:
DBF
The pointer returned by 'gdbm_open'.
KEY
The search key.
CONTENT
The data to be associated with the key.
FLAG
Defines the action to take when the key is already in the
database. The value 'GDBM_REPLACE' asks that the old data be
replaced by the new CONTENT. The value 'GDBM_INSERT' asks
that an error be returned and no action taken if the KEY
already exists.
This function can return the following values:
0
Success. The value of CONTENT is keyed by KEY in the
database.
-1
An error occurred which prevented the item from being stored
in the database. Examine the 'gdbm_errno' variable to
determine the actual cause of the error.
+1
The item was not stored because the argument FLAG was
'GDBM_INSERT' and the KEY was already in the database. The
'gdbm_errno' variable is set to 'GDBM_CANNOT_REPLACE'.
If the function returns -1, 'gdbm_errno' can have the following
values:
'GDBM_READER_CANT_STORE'
Database was open in read-only mode, i.e. with the
'GDBM_READER' flag. *Note Open::.
'GDBM_MALFORMED_DATA'
Either KEY or CONTENT had their 'dptr' field set to 'NULL'.
It is OK to have a "zero-length" key or content, i.e. a datum
with 'dsize' set to 0, but the 'dptr' field must always be a
non-NULL value.
'GDBM_BAD_HASH_TABLE'
Database hash table is malformed. This usually means that
some error in the application or the library caused memory
overrun. The database is marked as needing recovery. All
further calls on this database will return with 'gdbm_error'
set to 'GDBM_NEED_RECOVERY'. *Note Recovery::, for a
discussion of database recovery process.
'GDBM_BAD_DIR_ENTRY'
Database directory entry is corrupted. The database is marked
as needing recovery. *Note Recovery::.
'GDBM_BAD_BUCKET'
Database bucket is corrupted. The database is marked as
needing recovery. *Note Recovery::.
'GDBM_BAD_AVAIL'
Database available storage index is corrupted. The database
is marked as needing recovery. *Note Recovery::.
'GDBM_FILE_SEEK_ERROR'
A seek error occurred on the underlying disk file. Examine
the system 'errno' variable for more detail.
If you store data for a KEY that is already in the data base, 'GDBM'
replaces the old data with the new data if called with 'GDBM_REPLACE'.
You do not get two data items for the same 'key' and you do not get an
error from 'gdbm_store'.
The size of datum in 'GDBM' is restricted only by the maximum value
for an object of type 'int' (type of the 'dsize' member of 'datum').
File: gdbm.info, Node: Fetch, Next: Delete, Prev: Store, Up: Top
7 Searching for records in the database
***************************************
-- gdbm interface: datum gdbm_fetch (GDBM_FILE DBF, datum KEY)
Looks up a given KEY and returns the information associated with
it. The 'dptr' field in the structure that is returned points to a
memory block allocated by 'malloc'. It is the caller's
responsibility to free it when no longer needed.
If the 'dptr' is 'NULL', inspect the value of the 'gdbm_errno'
variable (*note gdbm_errno: Variables.). If it is
'GDBM_ITEM_NOT_FOUND', no data was found. Any other value means an
error occurred. Use 'gdbm_strerror' function to convert
'gdbm_errno' to a human-readable string.
The parameters are:
DBF
The pointer returned by 'gdbm_open'.
KEY
The search key.
An example of using this function:
content = gdbm_fetch (dbf, key);
if (content.dptr == NULL)
{
if (gdbm_errno == GDBM_ITEM_NOT_FOUND)
fprintf(stderr, "key not found\n");
else
fprintf(stderr, "error: %s\n", gdbm_db_strerror (dbf));
}
else
{
/* do something with content.dptr */
}
You may also search for a particular key without retrieving it:
-- gdbm interface: int gdbm_exists (GDBM_FILE DBF, datum KEY)
Checks whether the KEY exists in the database DBF.
If KEY is found, returns 'true' ('1'). If it is not found, returns
'false' ('0') and sets 'gdbm_errno' to 'GDBM_NO_ERROR' ('0').
On error, returns '0' and sets 'gdbm_errno' to a non-'0' error
code.
The parameters are:
DBF
The pointer returned by 'gdbm_open'.
KEY
The search key.
File: gdbm.info, Node: Delete, Next: Sequential, Prev: Fetch, Up: Top
8 Removing records from the database
************************************
To remove some data from the database, use the 'gdbm_delete' function.
-- gdbm interface: int gdbm_delete (GDBM_FILE DBF, datum KEY)
Deletes the data associated with the given KEY, if it exists in the
database DBF.
The parameters are:
DBF
The pointer returned by 'gdbm_open'.
DATUM KEY
The search key.
The function returns '-1' if the item is not present or if an error
is encountered. Examine the 'gdbm_errno' variable or the return
from 'gdbm_last_errno (DBF)' to know the reason.
The return of '0' marks a successful delete.
File: gdbm.info, Node: Sequential, Next: Reorganization, Prev: Delete, Up: Top
9 Sequential access to records
******************************
The next two functions 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.
'gdbm_firstkey' starts the visit of all keys in the database.
'gdbm_nextkey' finds and reads the next entry in the hash structure for
'dbf'.
-- gdbm interface: datum gdbm_firstkey (GDBM_FILE DBF)
Initiate sequential access to the database DBF. The returned value
is the first key accessed in the database. If the 'dptr' field in
the returned datum is 'NULL', inspect the 'gdbm_errno' variable
(*note gdbm_errno: Variables.). The value of 'GDBM_ITEM_NOT_FOUND'
means that the database contains no data. Other value means an
error occurred.
On success, 'dptr' points to a memory block obtained from 'malloc',
which holds the key value. The caller is responsible for freeing
this memory block when no longer needed.
-- gdbm interface: datum gdbm_nextkey (GDBM_FILE DBF, datum PREV)
This function continues iteration over the keys in DBF, initiated
by 'gdbm_firstkey'. The parameter PREV holds the value returned
from a previous call to 'gdbm_nextkey' or 'gdbm_firstkey'.
The function returns next key from the database. If the 'dptr'
field in the returned datum is 'NULL' inspect the 'gdbm_errno'
variable (*note gdbm_errno: Variables.). The value of
'GDBM_ITEM_NOT_FOUND' means that all keys in the database has been
visited. Any other value means an error occurred.
Otherwise, 'dptr' points to a memory block obtained from 'malloc',
which holds the key value. The caller is responsible for freeing
this memory block when no longer needed.
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:
key = gdbm_firstkey (dbf);
while (key.dptr)
{
datum nextkey;
/* do something with the key */
...
/* Obtain the next key */
nextkey = gdbm_nextkey (dbf, key);
/* Reclaim the memory used by the key */
free (key.dptr);
/* Use nextkey in the next iteration. */
key = nextkey;
}
Don't use 'gdbm_delete' or 'gdbm_store' in such a loop. File
visiting is based on a "hash table". The 'gdbm_delete' function
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. So it is possible that
some key will not be visited or will be visited twice, if a loop like
the following is executed:
key = gdbm_firstkey (dbf);
while (key.dptr)
{
datum nextkey;
if (some condition)
{
gdbm_delete (dbf, key);
}
nextkey = gdbm_nextkey (dbf, key);
free (key.dptr);
key = nextkey;
}
File: gdbm.info, Node: Reorganization, Next: Sync, Prev: Sequential, Up: Top
10 Database reorganization
**************************
The following function should be used very seldom.
-- gdbm interface: int gdbm_reorganize (GDBM_FILE DBF)
Reorganizes the database.
The parameter is:
DBF
The pointer returned by 'gdbm_open'.
If you have had a lot of deletions and would like to shrink the space
used by the 'GDBM' file, this function will reorganize the database.
This results, in particular, in shortening the length of a 'GDBM' file
by removing the space occupied by deleted records.
This reorganization requires creating a new file and inserting all
the elements in the old file DBF into the new file. The new file is
then renamed to the same name as the old file and DBF is updated to
contain all the 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.
File: gdbm.info, Node: Sync, Next: Database format, Prev: Reorganization, Up: Top
11 Database Synchronization
***************************
Normally, 'GDBM' functions don't flush changed data to the disk
immediately after a change. This allows for faster writing of databases
at the risk of having a corrupted database if the application terminates
in an abnormal fashion. The following function allows the programmer to
make sure the disk version of the database has been completely updated
with all changes to the current time.
-- gdbm interface: int gdbm_sync (GDBM_FILE DBF)
Synchronizes the changes in DBF with its disk file. The parameter
is a pointer returned by 'gdbm_open'.
This function would usually be called after a complete set of
changes have been made to the database and before some long waiting
time. This set of changes should preserve application-level
invariants. In other words, call 'gdbm_sync' only when the
database is in a consistent state with regard to the application
logic, a state from which you are willing and able to recover. You
can think about all database operations between two consecutive
'gdbm_sync' calls as constituting a single "transaction". *Note
Synchronizing the Database::, for a detailed discussion about how
to properly select the synchronization points.
The 'gdbm_close' function automatically calls the equivalent of
'gdbm_sync' so no call is needed if the database is to be closed
immediately after the set of changes have been made.
'Gdbm_sync' returns 0 on success. On error, it sets 'gdbm_errno'
and system 'errno' variables to the codes describing the error and
returns -1.
Opening the database with 'GDBM_SYNC' flag ensures that 'gdbm_sync'
function will be called after each change, thereby flushing the changes
to disk immediately. You are advised against using this flag, however,
because it incurs a severe performance penalty, while giving only a
moderate guarantee that the _structural_ consistency of the database
will be preserved in case of failure, and that only unless the failure
occurs while being in the 'fsync' call. For the ways to ensure proper
_logical_ consistency of the database, see *note Crash Tolerance::.
File: gdbm.info, Node: Database format, Next: Flat files, Prev: Sync, Up: Top
12 Changing database format
***************************
As of version 1.23, 'GDBM' supports databases in two formats: "standard"
and "extended". The standard format is used most often. The "extended"
database format is used to provide additional crash resistance (*note
Crash Tolerance::).
Depending on the value of the FLAGS parameter in a call to
'gdbm_open' (*note GDBM_NUMSYNC: Open.), a database can be created in
either format.
The format of an existing database can be changed using the
'gdbm_convert' function:
-- gdbm interface: int gdbm_convert (GDBM_FILE DBF, int FLAG)
Changes the format of the database file DBF. Allowed values for
FLAG are:
'0'
Convert database to the standard format.
'GDBM_NUMSYNC'
Convert database to the extended "numsync" format (*note
Numsync::).
On success, the function returns 0. In this case, it should be
followed by a call to 'gdbm_sync' (*note Sync::) or 'gdbm_close'
(*note Close::) to ensure the changes are written to the disk.
On error, returns -1 and sets the 'gdbm_errno' variable (*note
gdbm_errno: Variables.).
If the database is already in the requested format, the function
returns success (0) without doing anything.
File: gdbm.info, Node: Flat files, Next: Errors, Prev: Database format, Up: Top
13 Export and Import
********************
'GDBM' databases can be converted into so-called "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
'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 key/value pairs as the database from which
the flat file was created. However, it will not constitute a
byte-to-byte equivalent of the latter. Various internal structures in
the database can differ. In particular, ordering of key/value pairs can
be different and the table of available file space will most probably
differ, too. For databases in extended format, the 'numsync' counter
will be reset to 0 (*note Numsync::). These details are not visible to
the application programmer, and are mentioned here only for completeness
sake.
The fact that the restored database contains the same set of
key/value pairs does not necessarily mean, however, that it can be used
in the same way as the original one. For example, if the original
database contained non-ASCII data (e.g. C structures, integers etc.),
the recreated database can be of any use only if the target machine has
the same integer size and byte ordering as the source one and if its C
compiler uses the same packing conventions as the one which generated C
which populated the 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.
'GDBM' version 1.23 supports two flat file formats. The "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. This format is supported for backward compatibility.
The "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
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.
We call a process of creating a flat file from a database "exporting"
or "dumping" this database. The reverse process, creating the database
from a flat file is called "importing" or "loading" the database.
-- gdbm interface: int gdbm_dump (GDBM_FILE DBF, const char *FILENAME,
int FORMAT, int OPEN_FLAGS, int MODE)
Dumps the database file to the named file in requested format.
Arguments are:
DBF
A pointer to the source database, returned by a prior call to
'gdbm_open'.
FILENAME
Name of the dump file.
FORMAT
Output file format. Allowed values are:
'GDBM_DUMP_FMT_BINARY' to create a binary dump and
'GDBM_DUMP_FMT_ASCII' to create an ASCII dump file.
OPEN_FLAGS
How to create the output file. If FLAG is 'GDBM_WRCREAT' the
file will be created if it does not exist. If it does exist,
the 'gdbm_dump' will fail.
If FLAG is 'GDBM_NEWDB', the function will create a new output
file, replacing it if it already exists.
MODE
The permissions to use when creating the output file (*note
open a file: (open(2))open.).
-- gdbm interface: int gdbm_load (GDBM_FILE *PDBF, const char
*FILENAME, int FLAG, int META_MASK, unsigned long *ERRLINE)
Loads data from the dump file FILENAME into the database pointed to
by PDBF. The latter can point to '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 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 'gdbm_errno' to 'GDBM_NO_DBNAME' and return '-1',
indicating failure.
The FLAG has the same meaning as the FLAG argument to the
'gdbm_store' function (*note Store::).
The META_MASK argument 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:
GDBM_META_MASK_MODE
Do not restore file mode.
GDBM_META_MASK_OWNER
Do not restore file owner.
The function returns 0 upon successful completion or -1 on fatal
errors and 1 on mild (non-fatal) errors.
If a fatal error occurs, 'gdbm_errno' will be set to one of the
following values:
GDBM_FILE_OPEN_ERROR
Input file (FILENAME) cannot be opened. The 'errno' variable
can be used to get more detail about the failure.
GDBM_MALLOC_ERROR
Not enough memory to load data.
GDBM_FILE_READ_ERROR
Reading from FILENAME failed. The 'errno' variable can be
used to get more detail about the failure.
GDBM_MALFORMED_DATA
GDBM_ILLEGAL_DATA
Input contained malformed data, i.e. it is not a valid 'GDBM'
dump file. This often means that the dump file got corrupted
during the transfer.
The 'GDBM_ILLEGAL_DATA' is an alias for this error code,
maintained for backward compatibility.
GDBM_ITEM_NOT_FOUND
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
'GDBM_MALFORMED_DATA'.
Mild errors mean that the function was able to successfully load
and restore the data, but was unable to change the database file
metadata afterwards. The table below lists possible values for
'gdbm_errno' in this case. To get more detail, inspect the system
'errno' variable.
GDBM_ERR_FILE_OWNER
The function was unable to restore database file owner.
GDBM_ERR_FILE_MODE
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 ERRLINE parameter, unless
it is 'NULL'.
If the line information is not available or applicable, ERRLINE
will be set to '0'.
-- gdbm interface: int gdbm_dump_to_file (GDBM_FILE DBF, FILE *FP, int
FORMAT)
This is an alternative entry point to 'gdbm_dump' (which see).
Arguments are:
DBF
A pointer to the source database, returned by a call to
'gdbm_open'.
FP
File to write the data to.
FORMAT
Format of the dump file. See the FORMAT argument to the
'gdbm_dump' function.
-- gdbm interface: int gdbm_load_from_file (GDBM_FILE *PDBF, FILE *FP,
int REPLACE, int META_MASK, unsigned long *LINE)
This is an alternative entry point to 'gdbm_load'. It writes the
output to FP which must be a file open for writing. The rest of
arguments is the same as for 'gdbm_load' (excepting of course FLAG,
which is not needed in this case).
-- gdbm interface: int gdbm_export (GDBM_FILE DBF, const char
*EXPORTFILE, int FLAG, int 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 equivalent to
gdbm_dump(DBF, EXPORTFILE, GDBM_DUMP_FMT_BINARY, FLAG, MODE)
-- gdbm interface: int gdbm_export_to_file (GDBM_FILE DBF, FILE *FP)
This is an alternative entry point to 'gdbm_export'. This function
writes to file FP a binary dump of the database DBF.
-- gdbm interface: int gdbm_import (GDBM_FILE DBF, const char
*IMPORTFILE, int FLAG)
This function is retained for compatibility with 'GDBM' 1.10 and
earlier. It loads the file IMPORTFILE, which must be a binary flat
file, into the database DBF and is equivalent to the following
construct:
DBF = gdbm_open (IMPORTFILE, 0,
FLAG == GDBM_REPLACE ?
GDBM_WRCREAT : GDBM_NEWDB,
0600, NULL);
gdbm_load (&DBF, EXPORTFILE, 0, FLAG, NULL)
-- gdbm interface: int gdbm_import_from_file (GDBM_FILE DBF, FILE *FP,
int FLAG)
An alternative entry point to 'gdbm_import'. Reads the binary dump
from the file FP and stores the key/value pairs to DBF. *Note
Store::, for a description of FLAG.
This function is equivalent to:
DBF = gdbm_open (IMPORTFILE, 0,
FLAG == GDBM_REPLACE ?
GDBM_WRCREAT : GDBM_NEWDB,
0600, NULL);
gdbm_load_from_file (DBF, FP, FLAG, 0, NULL);
File: gdbm.info, Node: Errors, Next: Database consistency, Prev: Flat files, Up: Top
14 Error handling
*****************
The global variable 'gdbm_errno' (*note gdbm_errno: Variables.) keeps
the error code of the most recent error encountered by 'GDBM' functions.
To convert this code to human-readable string, use the following
function:
-- gdbm interface: const char * gdbm_strerror (gdbm_error ERRNO)
Converts 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.
Detailed information about the most recent error that occurred while
operating on a 'GDBM' file is stored in the 'GDBM_FILE' object itself.
To retrieve it, the following functions are provided:
-- gdbm interface: gdbm_error gdbm_last_errno (GDBM_FILE DBF)
Returns the code of the most recent error encountered when
operating on DBF.
When 'gdbm_last_errno' called immediately after the failed
function, its return equals the value of the 'gdbm_errno' variable.
However, 'gdbm_errno' can be changed if any 'GDBM' functions
(operating on another databases) were called afterwards, and
'gdbm_last_errno' will always return the code of the last error
that occurred while working with _that_ database.
-- gdbm interface: int gdbm_last_syserr (GDBM_FILE DBF)
Returns the value of the system 'errno' variable associated with
the most recent error.
Notice, that not all 'GDBM' errors have an associated system error
code. The following are the ones that have:
* GDBM_FILE_OPEN_ERROR
* GDBM_FILE_WRITE_ERROR
* GDBM_FILE_SEEK_ERROR
* GDBM_FILE_READ_ERROR
* GDBM_FILE_STAT_ERROR
* GDBM_BACKUP_FAILED
* GDBM_BACKUP_FAILED
* GDBM_FILE_CLOSE_ERROR
* GDBM_FILE_SYNC_ERROR
* GDBM_FILE_TRUNCATE_ERROR
For other errors, 'gdbm_last_syserr' will return 0.
-- gdbm interface: int gdbm_check_syserr (gdbm_errno ERR)
Returns '1', if the system 'errno' value should be inspected to get
more info on the error described by 'GDBM' error code ERR.
To get a human-readable description of the recent error for a
particular database file, use the 'gdbm_db_strerror' function:
-- gdbm interface: const char * gdbm_db_strerror (GDBM_FILE DBF)
Returns textual description of the most recent error encountered
when operating on the database DBF. The resulting string is often
more informative than what would be returned by
'gdbm_strerror(gdbm_last_errno(DBF))'. In particular, if there is
a system error associated with the recent failure, it will be
described as well.
-- gdbm interface: void gdbm_clear_error (GDBM_FILE DBF)
Clears the error state for the database DBF. Normally, this
function is called upon the entry to any 'GDBM' function.
Certain errors (such as write error when saving stored key) can leave
database file in inconsistent state (*note Database consistency::).
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 'gdbm_recover'), will return immediately with
'GDBM' error code 'GDBM_NEED_RECOVERY'. Additionally, the following
function can be used to check the state of the database file:
-- gdbm interface: int gdbm_needs_recovery (GDBM_FILE DBF)
Returns '1' if the database file DBF is in inconsistent state and
needs recovery.
To restore structural consistency of the database, use the
'gdbm_recover' function (*note Recovery::).
Crash tolerance provides a better way of recovery, because it
restores both structural and logical consistency. *Note Crash
Tolerance::, for a detailed discussion,
File: gdbm.info, Node: Database consistency, Next: Recovery, Prev: Errors, Up: Top
15 Database consistency
***********************
In the chapters that follow we will cover different aspects of "database
consistency" and ways to maintain it. Speaking about consistency, it is
important to distinguish between two different aspects of it: structural
and logical consistency.
"Structural consistency" means that all internal structures of the
database are in good order, contain valid data and are coherent with one
another. Structural consistency means that the database is in good
shape "technically", but it does not imply that the data it contains are
in any way meaningful.
"Logical consistency" means that the data stored in the database are
coherent with respect to the application logic. Usually this implies
that structural consistency is observed as well.
For as long as the program is free from memory management errors and
each opened database is properly closed before the program terminates,
structural consistency is maintained. Maintaining logical consistency
is more complex task and its maintenance is entirely the responsibility
of the application programmer. *Note Crash Tolerance::, for a detailed
discussion.
Both consistency aspects can suffer as a result of both application
errors that cause the program to terminate prematurely without properly
saving the database, and hardware errors, such as disk failures or power
outages. When such situations occur, it becomes necessary to "recover
the database".
In the next chapter we will discuss how to recover structural
consistency of a database.
File: gdbm.info, Node: Recovery, Next: Crash Tolerance, Prev: Database consistency, Up: Top
16 Recovering structural consistency
************************************
Certain errors (such as write error when saving stored key) can leave
database file in "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
'gdbm_recover'), will return immediately with 'GDBM' error code
'GDBM_NEED_RECOVERY'.
To escape from this state and bring the database back to operational
state, use the following function:
-- gdbm interface: int gdbm_recover (GDBM_FILE DBF, gdbm_recovery
*RCVR, int FLAGS)
Check the database file DBF and fix eventual errors. The RCVR
argument points to a structure that has "input members", providing
additional information to alter the behavior of 'gdbm_recover', and
"output members", which are used to return additional statistics
about the recovery process (RCVR can be 'NULL' if no such
information is needed).
Each input member has a corresponding flag bit, which must be set
in FLAGS, in order to instruct the function to use it.
The 'gdbm_recover' type is defined as:
typedef struct gdbm_recovery_s
{
/* Input members.
These are initialized before call to gdbm_recover.
The flags argument specifies which of them are initialized. */
void (*errfun) (void *data, char const *fmt, ...);
void *data;
size_t max_failed_keys;
size_t max_failed_buckets;
size_t max_failures;
/* Output members.
The gdbm_recover function fills these before returning. */
size_t recovered_keys;
size_t recovered_buckets;
size_t failed_keys;
size_t failed_buckets;
char *backup_name;
} gdbm_recovery;
The "input members" modify the behavior of 'gdbm_recover':
-- input member of gdbm_recovery: void (*errfun) (void *DATA, char
const *FMT, ...)
If the 'GDBM_RCVR_ERRFUN' flag bit is set, 'errfun' points to
a function that will be called upon each recoverable or
non-fatal error that occurred during the recovery. The 'data'
field of 'gdbm_recovery' will be passed to it as its first
argument. The FMT argument is a 'printf'-like (*note
(printf(3))Format of the format string::), format string. The
rest of arguments supply parameters for that format.
-- input member of gdbm_recovery: void * data
Supplies first argument for the 'errfun' invocations.
-- input member of gdbm_recovery: size_t max_failed_keys
If '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 becomes equal to 'max_failed_keys',
recovery is aborted and error is returned.
-- input member of gdbm_recovery: size_t max_failed_buckets
If '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 becomes equal to 'max_failed_buckets', recovery is
aborted and error is returned.
-- output member of gdbm_recovery: size_t max_failures
If 'GDBM_RCVR_MAX_FAILURES' is set, this member sets the limit
of failures that are tolerated during recovery. If the number
of errors becomes equal to 'max_failures', recovery is aborted
and error is returned.
The following members are filled on output, upon successful return
from the function:
-- output member of gdbm_recovery: size_t recovered_keys
Number of recovered keys.
-- output member of gdbm_recovery: size_t recovered_buckets
Number of recovered buckets.
-- output member of gdbm_recovery: size_t failed_keys
Number of key/data pairs that could not be retrieved.
-- output member of gdbm_recovery: size_t failed_buckets
Number of buckets that could not be retrieved.
-- output member of gdbm_recovery: char * backup_name
Name of the file keeping the copy of the original database, in
the state prior to recovery. It is filled if the
GDBM_RCVR_BACKUP flag is set. The string is allocated using
the 'malloc' call. The caller is responsible for freeing that
memory when no longer needed.
By default, 'gdbm_recovery' first checks the database for
inconsistencies and attempts recovery only if some were found. The
special flag bit 'GDBM_RCVR_FORCE' instructs 'gdbm_recovery' to omit
this check and to perform database recovery unconditionally.
File: gdbm.info, Node: Crash Tolerance, Next: Options, Prev: Recovery, Up: Top
17 Crash Tolerance
******************
Crash tolerance is a new (as of release 1.21) feature that can be
enabled at compile time, and used in environments with appropriate
support from the OS and the filesystem. As of version 1.23, this means
a Linux kernel 5.12.12 or later and a filesystem that supports reflink
copying, such as XFS, BtrFS, or OCFS2. If these prerequisites are met,
crash tolerance code will be enabled automatically by the 'configure'
script when building the package.
The crash-tolerance mechanism, when used correctly, guarantees that a
logically consistent (*note Database consistency::) recent state of
application data can be recovered following a crash. Specifically, it
guarantees that the state of the database file corresponding to the most
recent successful 'gdbm_sync' call can be recovered.
If the new mechanism is used correctly, crashes such as power
outages, OS kernel panics, and (some) application process crashes will
be tolerated. Non-tolerated failures include physical destruction of
storage devices and corruption due to bugs in application logic. For
example, the new mechanism won't help if a pointer bug in your
application corrupts 'GDBM''s private in-memory data which in turn
corrupts the database file.
In the following sections we will describe how to enable crash
tolerance in your application and what to do if a crash occurs.
The design rationale of the crash tolerance mechanism is described in
detail in the article, 'Crashproofing the Original NoSQL Key-Value
Store', by Terence Kelly, 'ACM Queue magazine', July/August 2021,
available from the ACM Digital Library
(https://queue.acm.org/DrillBits5/). If you have difficulty retrieving
this paper, please contact the author at ,
, or .
* Menu:
* Filesystems supporting crash tolerance::
* Enabling crash tolerance::
* Synchronizing the Database::
* Crash recovery::
* Manual crash recovery::
* Performance Impact::
* Availability::
* Numsync::
* Crash Tolerance API::
File: gdbm.info, Node: Filesystems supporting crash tolerance, Next: Enabling crash tolerance, Up: Crash Tolerance
17.1 Using Proper Filesystem
============================
Use a filesystem that supports reflink copying. Currently XFS, BtrFS,
and OCFS2 support reflink. You can create such a filesystem if you
don't have one already. (Note that reflink support may require that
special options be specified at the time of filesystem creation; this is
true of XFS.) The most conventional way to create a filesystem is on a
dedicated storage device. However it is also possible to create a
filesystem _within an ordinary file_ on some other filesystem.
For example, the following commands, executed as root, will create a
smallish XFS filesystem inside a file on another filesystem:
mkdir XFS
cd XFS
truncate --size 512m XFSfile
mkfs -t xfs -m crc=1 -m reflink=1 XFSfile
mkdir XFSmountpoint
mount -o loop XFSfile XFSmountpoint
The XFS filesystem is now available in directory 'XFSmountpoint'.
Now, create a directory where your unprivileged user account may create
and delete files:
cd XFSmountpoint
mkdir test
chown USER:GROUP test
(where USER and GROUP are the user and group names of the unprivileged
account the application uses).
Reflink copying via 'ioctl(FICLONE)' should work for files in and
below this directory. You can test reflink copying using the GNU 'cp'
program:
cp --reflink=always file1 file2
*Note reflink: (coreutils)cp invocation.
Your GNU dbm database file and two "snapshot" files described below
must all reside on the same reflink-capable filesystem.
File: gdbm.info, Node: Enabling crash tolerance, Next: Synchronizing the Database, Prev: Filesystems supporting crash tolerance, Up: Crash Tolerance
17.2 Enabling crash tolerance
=============================
Open a GNU dbm database with 'gdbm_open'. Whenever possible, use the
extended 'GDBM' format (*note Numsync::). Generally speaking, this
means using the 'GDBM_NUMSYNC' flag when creating the database. Unless
you know what you are doing, do not specify the 'GDBM_SYNC' flag when
opening the database. The reason is that you want your application to
explicitly control when 'gdbm_sync' is called; you don't want an
implicit sync on every database operation (*note Sync::).
Request crash tolerance by invoking the following interface:
int gdbm_failure_atomic (GDBM_FILE DBF, const char *EVEN,
const char *ODD);
The EVEN and ODD arguments are the pathnames of two files that will
be created and filled with "snapshots" of the database file. These two
files must not exist when 'gdbm_failure_atomic' is called and must
reside on the same reflink-capable filesystem as the database file.
After you call 'gdbm_failure_atomic', every call to 'gdbm_sync' will
make an efficient reflink snapshot of the database file in either the
EVEN or the ODD snapshot file; consecutive 'gdbm_sync' calls alternate
between the two, hence the names. The permission bits and 'mtime'
timestamps on the snapshot files determine which one contains the state
of the database file corresponding to the most recent successful
'gdbm_sync'. *Note Crash recovery::, for discussion of crash recovery.
File: gdbm.info, Node: Synchronizing the Database, Next: Crash recovery, Prev: Enabling crash tolerance, Up: Crash Tolerance
17.3 Synchronizing the Database
===============================
When your application knows that the state of the database is consistent
(i.e., all relevant application-level invariants hold), you may call
'gdbm_sync'. For example, if your application manages bank accounts,
transferring money from one account to another should maintain the
invariant that the sum of the two accounts is the same before and after
the transfer: It is correct to decrement account 'A' by $7, increment
account 'B' by $7, and then call 'gdbm_sync'. However it is _not_
correct to call 'gdbm_sync' _between_ the decrement of 'A' and the
increment of 'B', because a crash immediately after that call would
destroy money. The general rule is simple, sensible, and memorable:
Call 'gdbm_sync' only when the database is in a state from which you are
willing and able to recover following a crash. (If you think about it
you'll realize that there's never any other moment when you'd really
want to call 'gdbm_sync', regardless of whether crash-tolerance is
enabled. Why on earth would you push the state of an inconsistent
unrecoverable database down to durable media?).
File: gdbm.info, Node: Crash recovery, Next: Manual crash recovery, Prev: Synchronizing the Database, Up: Crash Tolerance
17.4 Crash recovery
===================
If a crash occurs, the snapshot file (EVEN or ODD) containing the
database state reflecting the most recent successful 'gdbm_sync' call is
the snapshot file whose permission bits are read-only and whose
last-modification timestamp is greatest. If both snapshot files are
readable, we choose the one with the most recent last-modification
timestamp. Modern operating systems record timestamps in nanoseconds,
which gives sufficient confidence that the timestamps of the two
snapshots will differ. However, one can't rule out the possibility that
the two snapshot files will both be readable and have identical
timestamps(1). To cope with this, 'GDBM' version 1.21 introduced the
new "extended database format", which stores in the database file header
the number of synchronizations performed so far. This number can
reliably be used to select the most recent snapshot, independently of
its timestamp. We strongly suggest using this new format when writing
crash-tolerant applications. *Note Numsync::, for a detailed
discussion.
The 'gdbm_latest_snapshot' function is provided, that selects the
right snapshot among the two. Invoke it as:
const char *recovery_file = NULL;
result = gdbm_latest_snapshot (even, odd, &recovery_file);
where EVEN and ODD are names of the snapshot files. On success, it
stores the pointer to the most recent snapshot file name in
RECOVERY_FILE and returns 'GDBM_SNAPSHOT_OK'. To finalize the recovery,
rename this file to the name of your database file and re-open it using
'gdbm_open'. You should discard the remaining snapshot.
If an error occurs, 'gdbm_latest_snapshot' returns one of the
following error codes.
-- gdbm_latest_snapshot: GDBM_SNAPSHOT_BAD
Neither snapshot file is readable. This means that the crash has
occurred before 'gdbm_failure_atomic' completed. In this case, it
is best to fall back on a safe backup copy of the data file.
-- gdbm_latest_snapshot: GDBM_SNAPSHOT_ERR
System error occurred in 'gdbm_latest_snapshot'. Examine the
system 'errno' variable for details. Its possible values are:
'EACCES'
The file mode of one of the snapshot files was incorrect.
Each snapshot file can be either readable (0400) or writable
(0200), but not both. This probably means that someone
touched one or both snapshot files after the crash and before
your attempt to recover from it. This case needs additional
investigation. If you're sure that the only change someone
made to the files is altering their modes, and your database
is in "numsync" format (*note Numsync::), you can reset the
modes to 0400 and retry the recovery.
This error can also be returned by underlying 'stat' call,
meaning that search permission was denied for one of the
directories in the path prefix of a snapshot file name. That
again means that someone has messed with permissions after the
crash.
'EINVAL'
Some arguments passed to 'gdbm_latest_snapshot' were not
valid. It is a programmer's error which means that your
application needs to be fixed.
'ENOSYS'
Function is not implemented. This means 'GDBM' was built
without crash-tolerance support.
'Other value (EBADF, EFAULT, etc)'
An error occurred when trying to 'stat' the snapshot file.
*Note (stat(2))ERRORS::, for a discussion of possible 'errno'
values.
-- gdbm_latest_snapshot: GDBM_SNAPSHOT_SAME
File modes and modification dates of both snapshot files are
exactly the same. This can happen only if numsync is not available
(*note Numsync::).
-- gdbm_latest_snapshot: GDBM_SNAPSHOT_SUSPICIOUS
For the database in extended "numsync" format (*note Numsync::):
the 'numsync' values of the two snapshot differ by more than one.
Check the arguments to the 'gdbm_latest_snapshot' function. The
most probably reason of such an error is that the EVEN and ODD
parameters point to snapshot files belonging to different database
files.
If you get any of these errors, we strongly suggest to undertake
"manual recovery".
---------- Footnotes ----------
(1) This can happen, for example, if the storage is very fast and the
system clock is low-resolution, or if the system administrator sets the
system clock backwards. In the latter case one can end up with the most
recent snapshot file having modification time earlier than that of the
obsolete snapshot.
File: gdbm.info, Node: Manual crash recovery, Next: Performance Impact, Prev: Crash recovery, Up: Crash Tolerance
17.5 Manual crash recovery
==========================
"Manual recovery" is usually performed with the help of the 'gdbmtool'
utility. Start 'gdbmtool' in read-only mode (the '-r') option. Once in
the command shell, issue the following command:
snapshot A B
where A and B are names of the two snapshot files you configured using
the 'gdbm_failure_atomic' function. This command investigates both
files and prints out detailed diagnostics.
Its output begins with a line listing one of the error codes above,
followed by a colon and a textual description of the error. The lines
that follow show details for each snapshot file.
Each snapshot description begins with the snapshot file name followed
by a colon and four fields, in this order:
1. File permission bits in octal.
2. File permission bits in 'ls -l' notation.
3. Modification timestamp.
4. Numsync counter. For databases in standard 'GDBM' format, this
field is 'N/A'. If the counter cannot be obtained because of
error, this field is '?'.
Any errors or inconsistencies discovered are reported in the lines
that follow, one error per line. Here's an example of the 'snapshot'
command output, describing the 'GDBM_SNAPSHOT_ERR' condition:
gdbmtool> snapshot even.dbf odd.dbf
GDBM_SNAPSHOT_ERR: Error selecting snapshot.
even.dbf: 200 -w------- 1627820627.485681330 ?
odd.dbf: 600 rw------- 1627820627.689503918 301
odd.dbf: ERROR: bad file mode
Line 2 lists the meta-data of the snapshot 'even.dbf'. The 'numsync'
field contains question mark because the file permissions (write-only)
prevented 'gdbmtool' from opening it.
The lines for 'odd.dbf' show the actual reason for the error: bad
file mode (read-write). Apparently, the file mode has been changed
manually after the crash. The timestamp of the file, which is more
recent than that of 'even.dbf', suggests that it might be used for
recovery. To confirm this guess, change the mode of the 'even.dbf' to
read-only and repeat the 'snapshot' command:
gdbmtool> ! chmod 400 even.dbf
gdbmtool> snapshot even.dbf odd.dbf
GDBM_SNAPSHOT_ERR: Error selecting snapshot.
even.dbf: 400 r-------- 1627820627.485681330 300
odd.dbf: 600 rw------- 1627820627.689503918 301
odd.dbf: ERROR: bad file mode
This shows the numsync value of the 'even.dbf' file, which is exactly
one less than that of 'odd.dbf'. This means that the latter should be
selected for recovery.
For completeness sake, you can change the mode of 'odd.dbf' to
read-only as well and repeat the 'snapshot' command. In this case you
will see:
gdbmtool> ! chmod 400 odd.dbf
gdbmtool> snapshot even.dbf odd.dbf
GDBM_SNAPSHOT_OK: Selected the most recent snapshot.
odd.dbf: 400 r-------- 1627820627.689503918 301
File: gdbm.info, Node: Performance Impact, Next: Availability, Prev: Manual crash recovery, Up: Crash Tolerance
17.6 Performance Impact
=======================
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 'gdbm_sync' call entails overheads. The
performance impact of 'GDBM' crash tolerance will depend on many factors
including the type and configuration of the underlying storage system,
how often the application calls 'gdbm_sync', and the extent of changes
to the database file between consecutive calls to 'gdbm_sync'.
File: gdbm.info, Node: Availability, Next: Numsync, Prev: Performance Impact, Up: Crash Tolerance
17.7 Availability
=================
To ensure that application data can survive the failure of one or more
storage devices, replicated storage (e.g., RAID) may be used beneath the
reflink-capable filesystem. Some cloud providers offer 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'.
File: gdbm.info, Node: Numsync, Next: Crash Tolerance API, Prev: Availability, Up: Crash Tolerance
17.8 Numsync Extension
======================
In *note Crash recovery::, we have shown that for database recovery, one
should select the snapshot whose permission bits are read-only and whose
last-modification timestamp is greatest. However, there may be cases
when a crash occurs at such a time that both snapshot files remain
readable. It may also happen, that their permissions had been reset to
read-only and/or modification times inadvertently changed before
recovery. To make it possible to select the right snapshot in such
cases, a new "extended database format" was introduced in 'GDBM' version
1.21. This format adds to the database header the 'numsync' field,
which holds the number of synchronizations the database underwent before
being closed or abandoned due to a crash.
A readable snapshot is a consistent copy of the database at a given
point of time. Thus, if both snapshots of a database in extended format
are readable, it will suffice to examine their 'numsync' counters and
select the one whose 'numsync' is greater. That's what the
'gdbm_latest_snapshot' function does in this case.
It is worth noticing, that the two counters should differ exactly by
one. If the difference is greater than that, 'gdbm_latest_snapshot'
will return a special status code, 'GDBM_SNAPSHOT_SUSPICIOUS'. If,
during a recovery attempt, you get this status code, we recommend to
proceed with the manual recovery (*note Manual crash recovery::).
To create a database in extended format, call 'gdbm_open' with both
'GDBM_NEWDB' and 'GDBM_NUMSYNC' flags:
dbf = gdbm_open(dbfile, 0, GDBM_NEWDB|GDBM_NUMSYNC, 0600, NULL);
Notice, that this flag must always be used together with 'GDBM_NEWDB'
(*note Open::). It is silently ignored when used together with another
opening flag.
A standard 'GDBM' database can be converted to the extended format
and vice versa. To convert an existing database to the extended format,
use the 'gdbm_convert' function (*note Database format::):
rc = gdbm_convert(dbf, GDBM_NUMSYNC);
You can do the same using the 'gdbmtool' utility (*note upgrade:
commands.):
gdbmtool DBNAME upgrade
To convert a database from extended format back to the standard
'GDBM' format, do:
rc = gdbm_convert(dbf, 0);
To do the same from the command line, run:
gdbmtool DBNAME downgrade
File: gdbm.info, Node: Crash Tolerance API, Prev: Numsync, Up: Crash Tolerance
17.9 Crash Tolerance API
========================
-- gdbm interface: int gdbm_failure_atomic (GDBM_FILE DBF, const char
*EVEN, const char *ODD)
Enables crash tolerance for the database file DBF. The EVEN and
ODD arguments are the pathnames of two files that will be created
and filled with snapshots of the database file. These two files
must not exist when 'gdbm_failure_atomic' is called and must reside
on the same reflink-capable filesystem as the database file.
Returns 0 on success. On failure, returns -1 and sets 'gdbm_errno'
to one of the following values:
'GDBM_ERR_USAGE'
Improper function usage. Either EVEN or ODD is 'NULL', or
they point to the same string.
'GDBM_NEED_RECOVERY'
The database needs recovery. *Note Recovery::.
'GDBM_ERR_SNAPSHOT_CLONE'
Failed to clone the database file into a snapshot. Examine
the system 'errno' variable for details.
If one of the following error codes is returned, examine the system
'errno' variable for details:
'GDBM_ERR_REALPATH'
Call to 'realpath' function failed. 'realpath' is used to
determine actual path names of the snapshot files.
'GDBM_FILE_OPEN_ERROR'
Unable to create snapshot file.
'GDBM_FILE_SYNC_ERROR'
Failed to sync a snapshot file or one of directories in its
pathname, during initial synchronization.
'GDBM_FILE_CLOSE_ERROR'
Failed to close a snapshot file or one of directories in its
pathname, during initial synchronization.
'GDBM_ERR_FILE_MODE'
The 'fchmod' call on one of the snapshot files failed.
Notes:
* It is not an error to call 'gdbm_failure_atomic' several
times. Each subsequent call closes the previously configured
snapshot files and installs new ones instead.
* Crash tolerance settings are cleared by functions
'gdbm_recover' (*note Recovery::) and 'gdbm_reorganize' (*note
Reorganization::). In case of 'gdbm_recover', it should not
be a problem, because if you enabled crash tolerance, the
procedure described in *note Crash recovery:: is the preferred
way of recovering the database. If, however, you decided to
call either function even though you had enabled crash
tolerance previously, be sure to call 'gdbm_failure_atomic'
again with the same arguments as before (provided that the
call returns successfully).
-- gdbm interface: int gdbm_latest_snapshot (const char *EVEN, const
char *ODD, const char **RETVAL)
Selects between two snapshots, EVEN and ODD, the one to be used for
crash recovery. On success, stores a pointer to the selected
filename in the memory location pointed to by RETVAL and returns
'GDBM_SNAPSHOT_OK'. If neither snapshot file is usable, the
function returns 'GDBM_SNAPSHOT_BAD'. If a system error occurs, it
returns 'GDBM_SNAPSHOT_ERR' and sets 'errno' to the error code
describing the problem. Finally, in the unlikely case that it
cannot select between the two snapshots (this means they are both
readable and have exactly the same 'mtime' timestamp), the function
returns 'GDBM_SNAPSHOT_SAME'.
If the 'numsync' extension is enabled (*note Numsync::), the
function can also return the 'GDBM_SNAPSHOT_SUSPICIOUS' status
code. This happens when the 'numsync' counters in the two
snapshots differ by more than one.
*Note Crash recovery::, for a detailed description of possible
return codes and their interpretation.
If any value other than 'GDBM_SNAPSHOT_OK' is returned, it is
guaranteed that the function did not touch RETVAL. In this case it
is recommended to switch to manual recovery procedure, letting the
user examine the snapshots and take the appropriate action. *note
Manual crash recovery::, for details.
File: gdbm.info, Node: Options, Next: Locking, Prev: Crash Tolerance, Up: Top
18 Setting options
******************
'GDBM' supports the ability to set certain options on an already open
database.
-- gdbm interface: int gdbm_setopt (GDBM_FILE DBF, int OPTION, void
*VALUE, int SIZE)
Sets an option on the database or returns the value of an option.
The parameters are:
DBF
The pointer returned by 'gdbm_open'.
OPTION
The option to be set or retrieved.
VALUE
A pointer to the value to which OPTION will be set or where to
place the option value (depending on the option).
SIZE
The length of the data pointed to by VALUE.
The return value will be '-1' upon failure, or '0' upon success.
The global variable 'gdbm_errno' will be set upon failure.
The valid options are:
-- Option: GDBM_SETCACHESIZE
-- Option: GDBM_CACHESIZE
Set the size of the internal bucket cache. The VALUE should point
to a 'size_t' holding the desired cache size, or the constant
'GDBM_CACHE_AUTO', to adjust the cache size automatically.
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 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 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:
size_t bn;
gdbm_bucket_count (dbf, &bn);
ret = gdbm_setopt (dbf, GDBM_SETCACHESIZE, &bn, sizeof (bn));
To request the automatically adjustable cache size, use the
constant 'GDBM_CACHE_AUTO':
size_t bn = GDBM_CACHE_AUTO;
ret = gdbm_setopt (dbf, GDBM_SETCACHESIZE, &bn, sizeof (bn));
-- Option: GDBM_GETCACHESIZE
Return the actual size of the internal bucket cache. The VALUE
should point to a 'size_t' variable, where the size will be stored.
-- Option: GDBM_SETCACHEAUTO
Controls whether the cache size will be adjusted automatically as
needed. The VALUE should point to an integer: 'TRUE' to enable
automatic cache adjustment and 'FALSE' to disable it.
The following two calls are equivalent:
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));
-- Option: GDBM_GETCACHEAUTO
Return the state of the automatic cache size adjustment. The VALUE
should point to an integer which, upon successful return, will have
the value 'TRUE' if the automatic cache size adjustment is enabled
and 'FALSE' otherwise.
-- Option: GDBM_GETFLAGS
Return the flags describing the state of the database. The VALUE
should point to an 'int' variable where to store the flags. On
success, its value will be similar to the flags used when opening
the database (*note gdbm_open: Open.), except that it will reflect
the current state (which may have been altered by another calls to
'gdbm_setopt').
-- Option: GDBM_GETDBFORMAT
Return the database format. The VALUE should point to an 'int'
variable. Upon successful return, it will be set to '0' if the
database is in standard format and 'GDBM_NUMSYNC' if it is in
extended format. *Note Database format::.
-- Option: GDBM_GETDIRDEPTH
Returns the "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 '1 <<
VALUE'.
The VALUE argument should point to an 'int'.
-- Option: GDBM_GETBUCKETSIZE
Returns the "bucket capacity": maximum number of keys per bucket
('int').
-- Option: GDBM_FASTMODE
Enable or disable the "fast writes mode", i.e. writes without
subsequent synchronization. The VALUE should point to an integer:
'TRUE' to enable fast mode, and 'FALSE' to disable it.
This option is retained for compatibility with previous versions of
'GDBM'. Its effect is the reverse of 'GDBM_SETSYNCMODE'.
-- Option: GDBM_SETSYNCMODE
-- Option: GDBM_SYNCMODE
Turn on or off file system synchronization operations. This
setting defaults to off. The VALUE should point to an integer:
'TRUE' to turn synchronization on, and 'FALSE' to turn it off.
Note, that this option is a reverse of 'GDBM_FASTMODE', i.e.
calling 'GDBM_SETSYNCMODE' with 'TRUE' has the same effect as
calling 'GDBM_FASTMODE' with 'FALSE'.
The 'GDBM_SYNCMODE' option is provided for compatibility with
earlier versions.
-- Option: GDBM_GETSYNCMODE
Return the current synchronization status. The VALUE should point
to an 'int' where the status will be stored.
-- Option: GDBM_SETCENTFREE
-- Option: GDBM_CENTFREE
_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 'GDBM' handled free blocks.
If set, this option causes all subsequent free blocks to be placed
in the _global_ pool, allowing (in theory) more file space to be
reused more quickly. The VALUE should point to an integer: 'TRUE'
to turn central block pool on, and 'FALSE' to turn it off.
The 'GDBM_CENTFREE' option is provided for compatibility with
earlier versions.
-- Option: GDBM_SETCOALESCEBLKS
-- Option: GDBM_COALESCEBLKS
_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 'GDBM' 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 GDBM_CENTFREE. The VALUE should point to
an integer: 'TRUE' to turn free block merging on, and 'FALSE' to
turn it off.
-- Option: GDBM_GETCOALESCEBLKS
Return the current status of free block merging. The VALUE should
point to an 'int' where the status will be stored.
-- Option: GDBM_SETMAXMAPSIZE
Sets maximum size of a memory mapped region. The VALUE should
point to a value of type 'size_t', 'unsigned long' or 'unsigned'.
The actual value is rounded to the nearest page boundary (the page
size is obtained from 'sysconf(_SC_PAGESIZE)').
-- Option: GDBM_GETMAXMAPSIZE
Return the maximum size of a memory mapped region. The VALUE
should point to a value of type 'size_t' where to return the data.
-- Option: GDBM_SETMMAP
Enable or disable memory mapping mode. The VALUE should point to
an integer: 'TRUE' to enable memory mapping or 'FALSE' to disable
it.
-- Option: GDBM_GETMMAP
Check whether memory mapping is enabled. The VALUE should point to
an integer where to return the status.
-- Option: GDBM_GETDBNAME
Return the name of the database disk file. The VALUE should point
to a variable of type 'char**'. 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. For
example:
char *name;
if (gdbm_setopt (dbf, GDBM_GETDBNAME, &name, sizeof (name)))
{
fprintf (stderr, "gdbm_setopt failed: %s\n",
gdbm_strerror (gdbm_errno));
}
else
{
printf ("database name: %s\n", name);
free (name);
}
-- Option: GDBM_GETBLOCKSIZE
Return the block size in bytes. The VALUE should point to 'int'.
File: gdbm.info, Node: Locking, Next: Variables, Prev: Options, Up: Top
19 File Locking
***************
With locking disabled (if 'gdbm_open' was called with 'GDBM_NOLOCK'),
the user may want 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 'gdbm_fdesc' routine is provided.
-- gdbm interface: int gdbm_fdesc (GDBM_FILE DBF)
Returns the file descriptor of the database DBF. This value can be
used as an argument to 'flock', 'lockf' or similar calls.
File: gdbm.info, Node: Variables, Next: Additional functions, Prev: Locking, Up: Top
20 Useful global variables
**************************
The following global variables and constants are available:
-- Variable: gdbm_error gdbm_errno
This variable contains error code from the last failed 'GDBM' call.
*Note Error codes::, for a list of available error codes and their
descriptions.
Use 'gdbm_strerror' (*note Errors::) to convert it to a descriptive
text.
-- Variable: const char * gdbm_errlist[]
This variable is an array of error descriptions, which is used by
'gdbm_strerror' to convert error codes to human-readable text
(*note Errors::). You can access it directly, if you wish so. It
contains '_GDBM_MAX_ERRNO + 1' elements and can be directly indexed
by the error code to obtain a corresponding descriptive text.
-- Variable: int const gdbm_syserr[]
Array of boolean values indicating, for each 'GDBM' error code,
whether the value of 'errno'(3) variable is meaningful for this
error code. *Note gdbm_check_syserr::.
-- Constant: _GDBM_MIN_ERRNO
The minimum error code used by 'GDBM'.
-- Constant: _GDBM_MAX_ERRNO
The maximum error code used by 'GDBM'.
-- Variable: const char * gdbm_version
A string containing the version information.
-- Variable: int const gdbm_version_number[3]
This variable contains the 'GDBM' version numbers:
Index Meaning
-------------------------------------------------------------------
0 Major number
1 Minor number
2 Patchlevel number
Additionally, the following constants are defined in the 'gdbm.h'
file:
GDBM_VERSION_MAJOR
Major number.
GDBM_VERSION_MINOR
Minor number.
GDBM_VERSION_PATCH
Patchlevel number.
These can be used to verify whether the header file matches the
library.
To compare two split-out version numbers, use the following function:
-- gdbm interface: int gdbm_version_cmp (int const A[3], int const
B[3])
Compare two version numbers. Return '-1' if A is less than B, '1'
if A is greater than B and '0' if they are equal.
Comparison is done from left to right, so that:
a = { 1, 8, 3 };
b = { 1, 8, 3 };
gdbm_version_cmp (a, b) => 0
a = { 1, 8, 3 };
b = { 1, 8, 2 };
gdbm_version_cmp (a, b) => 1
a = { 1, 8, 3 };
b = { 1, 9. 0 };
gdbm_version_cmp (a, b) => -1
File: gdbm.info, Node: Additional functions, Next: Error codes, Prev: Variables, Up: Top
21 Additional functions
***********************
-- gdbm interface: int gdbm_avail_verify (GDBM_FILE DBF)
Verify if the available block stack is in consistent state. On
success, returns 0. If any errors are encountered, sets the
'gdbm_errno' to 'GDBM_BAD_AVAIL', marks the database as needing
recovery (*note Recovery::) and return -1.
File: gdbm.info, Node: Error codes, Next: Compatibility, Prev: Additional functions, Up: Top
22 Error codes
**************
This chapter summarizes error codes which can be set by the functions in
'GDBM' library.
-- Error Code: GDBM_NO_ERROR
No error occurred.
-- Error Code: GDBM_MALLOC_ERROR
Memory allocation failed. Not enough memory.
-- Error Code: GDBM_BLOCK_SIZE_ERROR
This error is set by the 'gdbm_open' function (*note Open::), if
the value of its BLOCK_SIZE argument is incorrect and the
'GDBM_BSEXACT' flag is set.
-- Error Code: GDBM_FILE_OPEN_ERROR
The library was not able to open a disk file. This can be set by
'gdbm_open' (*note Open::), 'gdbm_dump' ('gdbm_export') and
'gdbm_load' ('gdbm_import') functions (*note Flat files::).
Inspect the value of the system 'errno' variable to get more
detailed diagnostics.
-- Error Code: GDBM_FILE_WRITE_ERROR
Writing to a disk file failed. This can be set by 'gdbm_open'
(*note Open::), 'gdbm_dump' ('gdbm_export') and 'gdbm_load'
('gdbm_import') functions.
Inspect the value of the system 'errno' variable to get more
detailed diagnostics.
-- Error Code: GDBM_FILE_SEEK_ERROR
Positioning in a disk file failed. This can be set by 'gdbm_open'
(*note Open::) function.
Inspect the value of the system 'errno' variable to get a more
detailed diagnostics.
-- Error Code: GDBM_FILE_READ_ERROR
Reading from a disk file failed. This can be set by 'gdbm_open'
(*note Open::), 'gdbm_dump' ('gdbm_export') and 'gdbm_load'
('gdbm_import') functions.
Inspect the value of the system 'errno' variable to get a more
detailed diagnostics.
-- Error Code: GDBM_BAD_MAGIC_NUMBER
The file given as argument to 'gdbm_open' function is not a valid
'GDBM' file: it has a wrong magic number.
-- Error Code: GDBM_EMPTY_DATABASE
The file given as argument to 'gdbm_open' function is not a valid
'GDBM' file: it has zero length.
-- Error Code: GDBM_CANT_BE_READER
This error code is set by the 'gdbm_open' function if it is not
able to lock file when called in 'GDBM_READER' mode (*note
GDBM_READER: Open.).
-- Error Code: GDBM_CANT_BE_WRITER
This error code is set by the 'gdbm_open' function if it is not
able to lock file when called in writer mode (*note Open::).
-- Error Code: GDBM_READER_CANT_DELETE
Set by the 'gdbm_delete' (*note Delete::) if it attempted to
operate on a database that is open in read-only mode (*note
GDBM_READER: Open.).
-- Error Code: GDBM_READER_CANT_STORE
Set by the 'gdbm_store' (*note Store::) if it attempted to operate
on a database that is open in read-only mode (*note GDBM_READER:
Open.).
-- Error Code: GDBM_READER_CANT_REORGANIZE
Set by the 'gdbm_reorganize' (*note Reorganization::) if it
attempted to operate on a database that is open in read-only mode
(*note GDBM_READER: Open.).
-- Error Code: GDBM_ITEM_NOT_FOUND
Requested item was not found. This error is set by 'gdbm_delete'
(*note Delete::) and 'gdbm_fetch' (*note Fetch::) when the
requested KEY value is not found in the database.
-- Error Code: GDBM_REORGANIZE_FAILED
The 'gdbm_reorganize' function is not able to create a temporary
database. *Note Reorganization::.
-- Error Code: GDBM_CANNOT_REPLACE
Cannot replace existing item. This error is set by the
'gdbm_store' if the requested KEY value is found in the database
and the FLAG parameter is not 'GDBM_REPLACE'. *Note Store::, for a
detailed discussion.
-- Error Code: GDBM_MALFORMED_DATA
-- Error Code: GDBM_ILLEGAL_DATA
Input data was malformed in some way. When returned by
'gdbm_load', this means that the input file was not a valid 'GDBM'
dump file (*note gdbm_load function::). When returned by
'gdbm_store', this means that either KEY or CONTENT parameter had
its 'dptr' field set to 'NULL' (*note Store::).
The 'GDBM_ILLEGAL_DATA' is an alias for this error code, maintained
for backward compatibility. Its use in modern applications is
discouraged.
-- Error Code: GDBM_OPT_ALREADY_SET
Requested option can be set only once and was already set. As of
version 1.23, this error code is no longer used. In prior versions
it could have been returned by the 'gdbm_setopt' function when
setting the 'GDBM_CACHESIZE' value.
-- Error Code: GDBM_OPT_BADVAL
-- Error Code: GDBM_OPT_ILLEGAL
The OPTION argument is not valid or the VALUE argument points to an
invalid value in a call to 'gdbm_setopt' function. *Note
Options::.
'GDBM_OPT_ILLEGAL' is an alias for this error code, maintained for
backward compatibility. Modern applications should not use it.
-- Error Code: GDBM_BYTE_SWAPPED
The 'gdbm_open' function (*note Open::) attempts to open a database
which is created on a machine with different byte ordering.
-- Error Code: GDBM_BAD_FILE_OFFSET
The 'gdbm_open' function (*note Open::) sets this error code if the
file it tries to open has a wrong magic number.
-- Error Code: GDBM_BAD_OPEN_FLAGS
Set by the 'gdbm_dump' ('gdbm_export') function if supplied an
invalid FLAGS argument. *Note Flat files::.
-- Error Code: GDBM_FILE_STAT_ERROR
Getting information about a disk file failed. The system 'errno'
will give more details about the error.
This error can be set by the following functions: 'gdbm_open',
'gdbm_reorganize'.
-- Error Code: GDBM_FILE_EOF
End of file was encountered where more data was expected to be
present. This error can occur when fetching data from the database
and usually means that the database is truncated or otherwise
corrupted.
This error can be set by any 'GDBM' function that does I/O. Some of
these functions are: 'gdbm_delete', 'gdbm_exists', 'gdbm_fetch',
'gdbm_dump', 'gdbm_load', 'gdbm_export', 'gdbm_import',
'gdbm_reorganize', 'gdbm_firstkey', 'gdbm_nextkey', 'gdbm_store'.
-- Error Code: GDBM_NO_DBNAME
Output database name is not specified. This error code is set by
'gdbm_load' (*note gdbm_load: gdbm_load function.) if the first
argument points to 'NULL' and the input file does not specify the
database name.
-- Error Code: GDBM_ERR_FILE_OWNER
This error code is set by 'gdbm_load' if it is unable to restore
database file owner. It is a mild error condition, meaning that
the data have been restored successfully, only changing the target
file owner failed. Inspect the system 'errno' variable to get a
more detailed diagnostics.
-- Error Code: GDBM_ERR_FILE_MODE
This error code is set by 'gdbm_load' if it is unable to restore
database file mode. It is a mild error condition, meaning that the
data have been restored successfully, only changing the target file
owner failed. Inspect the system 'errno' variable to get a more
detailed diagnostics.
-- Error Code: GDBM_NEED_RECOVERY
Database is in inconsistent state and needs recovery. Call
'gdbm_recover' if you get this error. *Note Recovery::, for a
detailed description of recovery functions.
-- Error Code: GDBM_BACKUP_FAILED
The GDBM engine is unable to create backup copy of the file.
-- Error Code: GDBM_DIR_OVERFLOW
Bucket directory would overflow the size limit during an attempt to
split hash bucket. This error can occur while storing a new key.
-- Error Code: GDBM_BAD_BUCKET
Invalid index bucket is encountered in the database. Database
recovery is needed (*note Recovery::).
-- Error Code: GDBM_BAD_HEADER
This error is set by 'gdbm_open' and 'gdbm_fd_open', if the first
block read from the database file does not contain a valid 'GDBM'
header.
-- Error Code: GDBM_BAD_AVAIL
The available space stack is invalid. This error can be set by
'gdbm_open' and 'gdbm_fd_open', if the extended database
verification was requested ('GDBM_XVERIFY'). It is also set by the
'gdbm_avail_verify' function (*note Additional functions::).
Database recovery is needed (*note Recovery::).
-- Error Code: GDBM_BAD_HASH_TABLE
Hash table in a bucket is invalid. This error can be set by the
following functions: 'gdbm_delete', 'gdbm_exists', 'gdbm_fetch',
'gdbm_firstkey', 'gdbm_nextkey', and 'gdbm_store'.
Database recovery is needed (*note Recovery::).
-- Error Code: GDBM_BAD_DIR_ENTRY
Bad directory entry found in the bucket. The database recovery is
needed (*note Recovery::).
-- Error Code: GDBM_FILE_CLOSE_ERROR
The 'gdbm_close' function was unable to close the database file
descriptor. The system 'errno' variable contains the corresponding
error code.
-- Error Code: GDBM_FILE_SYNC_ERROR
Cached content couldn't be synchronized to disk. Examine the
'errno' variable to get more info,
Database recovery is needed (*note Recovery::).
-- Error Code: GDBM_FILE_TRUNCATE_ERROR
File cannot be truncated. Examine the 'errno' variable to get more
info.
This error is set by 'gdbm_open' and 'gdbm_fd_open' when called
with the 'GDBM_NEWDB' flag.
-- Error Code: GDBM_BUCKET_CACHE_CORRUPTED
The bucket cache structure is corrupted. Database recovery is
needed (*note Recovery::).
-- Error Code: GDBM_BAD_HASH_ENTRY
This error is set during sequential access (*note Sequential::), if
the next hash table entry does not contain the expected key. This
means that the bucket is malformed or corrupted and the database
needs recovery (*note Recovery::).
-- Error Code: GDBM_ERR_SNAPSHOT_CLONE
Set by the 'gdbm_failure_atomic' function if it was unable to clone
the database file into a snapshot. Inspect the system 'errno'
variable for the underlying cause of the error. If 'errno' is
'EINVAL' or 'ENOSYS', crash tolerance settings will be removed from
the database.
*Note Crash Tolerance API::.
-- Error Code: GDBM_ERR_REALPATH
Set by the 'gdbm_failure_atomic' function if the call to 'realpath'
function failed. 'realpath' is used to determine actual path names
of the snapshot files. Examine the system 'errno' variable for
details.
*Note Crash Tolerance API::.
-- Error Code: GDBM_ERR_USAGE
Function usage error. That includes invalid argument values, and
the like.
File: gdbm.info, Node: Compatibility, Next: gdbmtool, Prev: Error codes, Up: Top
23 Compatibility with standard 'dbm' and 'ndbm'
***********************************************
'Gdbm' includes a compatibility layer, which provides traditional 'ndbm'
and older 'dbm' functions. The layer is compiled and installed if the
'--enable-libgdbm-compat' option is used when configuring the package.
The compatibility layer consists of two header files: 'ndbm.h' and
'dbm.h' and the 'libgdbm_compat' library.
Older programs using 'ndbm' or 'dbm' interfaces can use
'libgdbm_compat' without any changes. To link a program with the
compatibility library, add the following two options to the 'cc'
invocation: '-lgdbm -lgdbm_compat'. The '-L' option may also be
required, depending on where 'GDBM' is installed, e.g.:
cc ... -lgdbm -lgdbm_compat
Databases created and manipulated by the compatibility interfaces
consist of two different files: 'FILE.dir' and 'FILE.pag'. This is
required by the POSIX specification and corresponds to the traditional
usage. Note, however, that despite the similarity of the naming
convention, actual data stored in these files has not the same format as
in the databases created by other 'dbm' or 'ndbm' libraries. In other
words, you cannot access a standard UNIX 'dbm' file with GNU 'dbm'!
Compatibility interface includes only functions required by POSIX
(*note ndbm::) or present in the traditional DBM implementation (*note
dbm::). Advanced 'GDBM' features, such as crash tolerance, cannot be
used with such databases.
GNU 'dbm' files are not 'sparse'. You can copy them with the usual
'cp' command and they will not expand in the copying process.
* Menu:
* ndbm:: NDBM interface functions.
* dbm:: DBM interface functions.
File: gdbm.info, Node: ndbm, Next: dbm, Up: Compatibility
23.1 NDBM interface functions
=============================
The functions below implement the POSIX 'ndbm' interface:
-- ndbm: DBM * dbm_open (char *FILE, int FLAGS, int MODE)
Opens a database. The FILE argument is the full name of the
database file to be opened. The function opens two files:
'FILE.pag' and 'FILE.dir'. The FLAGS and MODE arguments have the
same meaning as the second and third arguments of 'open' (*note
(open(2))open::), except that a database opened for write-only
access opens the files for read and write access and the behavior
of the 'O_APPEND' flag is unspecified.
The function returns a pointer to the 'DBM' structure describing
the database. This pointer is used to refer to this database in
all operations described below.
Any error detected will cause a return value of 'NULL' and an
appropriate value will be stored in 'gdbm_errno' (*note
Variables::).
-- ndbm: void dbm_close (DBM *DBF)
Closes the database. The DBF argument must be a pointer returned
by an earlier call to 'dbm_open'.
-- ndbm: datum dbm_fetch (DBM *DBF, datum KEY)
Reads a record from the database with the matching key. The KEY
argument supplies the key that is being looked for.
If no matching record is found, the 'dptr' member of the returned
datum is 'NULL'. Otherwise, the 'dptr' member of the returned
datum points to the memory managed by the compatibility library.
The application should never free it.
-- ndbm: int dbm_store (DBM *DBF, datum KEY, datum CONTENT, int MODE)
Writes a key/value pair to the database. The argument DBF is a
pointer to the 'DBM' structure returned from a call to 'dbm_open'.
The KEY and CONTENT provide the values for the record key and
content. The MODE argument controls the behavior of 'dbm_store' in
case a matching record already exists in the database. It can have
one of the following two values:
'DBM_REPLACE'
Replace existing record with the new one.
'DBM_INSERT'
The existing record is left unchanged, and the function
returns '1'.
If no matching record exists in the database, new record will be
inserted no matter what the value of the MODE is.
-- ndbm: int dbm_delete (DBM *DBF, datum KEY)
Deletes the record with the matching key from the database. If the
function succeeds, '0' is returned. Otherwise, if no matching
record is found or if an error occurs, '-1' is returned.
-- ndbm: datum dbm_firstkey (DBM *DBF)
Initializes iteration over the keys from the database and returns
the first key. Note, that the word 'first' does not imply any
specific ordering of the keys.
If there are no records in the database, the 'dptr' member of the
returned datum is 'NULL'. Otherwise, the 'dptr' member of the
returned datum points to the memory managed by the compatibility
library. The application should never free it.
-- ndbm: datum dbm_nextkey (DBM *DBF)
Continues the iteration started by 'dbm_firstkey'. Returns the
next key in the database. If the iteration covered all keys in the
database, the 'dptr' member of the returned datum is 'NULL'.
Otherwise, the 'dptr' member of the returned datum points to the
memory managed by the compatibility library. The application
should never free it.
The usual way of iterating over all the records in the database is:
for (key = dbm_firstkey (dbf); key.ptr; key = dbm_nextkey (dbf))
{
/* do something with the key */
}
The loop above should not try to delete any records from the
database, otherwise the iteration is not guaranteed to cover all
the keys. *Note Sequential::, for a detailed discussion of this.
-- ndbm: int dbm_error (DBM *DBF)
Returns the error condition of the database: '0' if no errors
occurred so far while manipulating the database, and a non-zero
value otherwise.
-- ndbm: void dbm_clearerr (DBM *DBF)
Clears the error condition of the database.
-- ndbm: int dbm_dirfno (DBM *DBF)
Returns the file descriptor of the 'dir' file of the database. It
is guaranteed to be different from the descriptor returned by the
'dbm_pagfno' function (see below).
The application can lock this descriptor to serialize accesses to
the database.
-- ndbm: int dbm_pagfno (DBM *DBF)
Returns the file descriptor of the 'pag' file of the database. See
also 'dbm_dirfno'.
-- ndbm: int dbm_rdonly (DBM *DBF)
Returns '1' if the database DBF is open in a read-only mode and '0'
otherwise.
File: gdbm.info, Node: dbm, Prev: ndbm, Up: Compatibility
23.2 DBM interface functions
============================
The functions below are provided for compatibility with the old UNIX
'DBM' interface. Only one database at a time can be manipulated using
them.
-- dbm: int dbminit (char *FILE)
Opens a database. The FILE argument is the full name of the
database file to be opened. The function opens two files:
'FILE.pag' and 'FILE.dir'. If any of them does not exist, the
function fails. It never attempts to create the files.
The database is opened in the read-write mode, if its disk
permissions permit.
The application must ensure that the functions described below in
this section are called only after a successful call to 'dbminit'.
-- dbm: int dbmclose (void)
Closes the database opened by an earlier call to 'dbminit'.
-- dbm: datum fetch (datum KEY)
Reads a record from the database with the matching key. The KEY
argument supplies the key that is being looked for.
If no matching record is found, the 'dptr' member of the returned
datum is 'NULL'. Otherwise, the 'dptr' member of the returned
datum points to the memory managed by the compatibility library.
The application should never free it.
-- dbm: int store (datum KEY, datum CONTENT)
Stores the key/value pair in the database. If a record with the
matching key already exists, its content will be replaced with the
new one.
Returns '0' on success and '-1' on error.
-- dbm: int delete (datum KEY)
Deletes a record with the matching key.
If the function succeeds, '0' is returned. Otherwise, if no
matching record is found or if an error occurs, '-1' is returned.
-- dbm: datum firstkey (void)
Initializes iteration over the keys from the database and returns
the first key. Note, that the word 'first' does not imply any
specific ordering of the keys.
If there are no records in the database, the 'dptr' member of the
returned datum is 'NULL'. Otherwise, the 'dptr' member of the
returned datum points to the memory managed by the compatibility
library. The application should never free it.
-- dbm: datum nextkey (datum KEY)
Continues the iteration started by a call to 'firstkey'. Returns
the next key in the database. If the iteration covered all keys in
the database, the 'dptr' member of the returned datum is 'NULL'.
Otherwise, the 'dptr' member of the returned datum points to the
memory managed by the compatibility library. The application
should never free it.
File: gdbm.info, Node: gdbmtool, Next: gdbm_dump, Prev: Compatibility, Up: Top
24 Examine and modify a GDBM database
*************************************
The 'gdbmtool' utility allows you to view and modify an existing 'GDBM'
database or to create a new one.
When invoked without arguments, it tries to open a database file
called 'junk.gdbm', located in the current working directory. You can
change this default by supplying the name of the database as argument to
the program, e.g.:
$ gdbmtool file.db
The database will be opened in read-write mode, unless the '-r'
('--read-only') option is specified, in which case it will be opened
only for reading.
If the database does not exist, 'gdbmtool' will create it. There is
a special option '-n' ('--newdb'), which instructs the utility to create
a new database. If it is used and if the database already exists, it
will be deleted, so use it sparingly.
* Menu:
* invocation::
* shell::
File: gdbm.info, Node: invocation, Next: shell, Up: gdbmtool
24.1 gdbmtool invocation
========================
When started without additional arguments, 'gdbmtool' operates on the
default database 'junk.gdbm'. Otherwise, the first argument supplies
the name of the database to operate upon. If neither any additional
arguments nor the '-f' ('--file') option are given, 'gdbmtool' opens
starts interactive shell and receives commands directly from the human
operator.
If more than one argument is given, all arguments past the database
name are parsed as 'gdbmtool' commands (*note shell::, for a description
of available commands) and executed in turn. All commands, except the
last one, should be terminated with semicolons. Semicolon after the
last command is optional. Note, that semicolons should be escaped in
order to prevent them from being interpreted by the shell.
Finally, if the '-f' ('--file') option is supplied, its argument
specifies the name of the disk file with 'gdbmtool' script. The program
will open that file and read commands from it.
The following table summarizes all 'gdbmtool' command line options:
'-b SIZE'
'--block-size=SIZE'
Set block size.
'-c SIZE'
'--cache-size=SIZE'
Set cache size.
'-d FD'
'--db-descriptor=FD'
Use the database referred to by the file descriptor FD. This must
be a valid open file descriptor, obtained by a call to 'open'
(*note open a file: (open(2))open.), 'creat' or a similar function.
The database will be opened using 'gdbm_fd_open' (*note
gdbm_fd_open::).
This option is intended for use by automatic test suites.
'-f FILE'
'--file FILE'
Read commands from FILE, instead of the standard input.
'-h'
'--help'
Print a concise help summary.
'-N'
'--norc'
Don't read startup files (*note startup files::).
'-n'
'--newdb'
Create the database.
'-l'
'--no-lock'
Disable file locking.
'-m'
'--no-mmap'
Disable memory mapping.
'-T'
'--timing'
Print time spent in each command. This is equivalent to setting
the 'timing' variable. *Note timing: variables.
'-t'
'--trace'
Enable command tracing. This is equivalent to setting the 'trace'
variable. *Note trace: variables.
'-q'
'--quiet'
Don't print the usual welcome banner at startup. This is the same
as setting the variable 'quiet' in the startup file. *Note
quiet::.
'-r'
'--read-only'
Open the database in read-only mode.
'-s'
'--synchronize'
Synchronize to the disk after each write.
'-V'
'--version'
Print program version and licensing information and exit.
'--usage'
Print a terse invocation syntax summary along with a list of
available command line options.
'-x'
'--extended'
'--numsync'
Create new database in extended (numsync) format (*note Numsync::).
This option sets the 'format' variable to 'numsync'. *Note format
variable::.
File: gdbm.info, Node: shell, Prev: invocation, Up: gdbmtool
24.2 gdbmtool interactive mode
==============================
After successful startup, 'gdbmtool' starts a loop, in which it reads
commands from the standard input, executes them and prints results on
the standard output. If the standard input is attached to a console,
'gdbmtool' runs in interactive mode, which is indicated by its "prompt":
gdbmtool> _
The utility finishes when it reads the 'quit' command (see below) or
detects end-of-file on its standard input, whichever occurs first.
A 'gdbmtool' command consists of a "command verb", optionally
followed by "arguments", separated by any amount of white space and
terminated with a newline or semicolon. A command verb can be entered
either in full or in an abbreviated form, as long as that abbreviation
does not match any other verb. For example, 'co' can be used instead of
'count' and 'ca' instead of 'cache'.
Any sequence of non-whitespace characters appearing after the command
verb forms an argument. If the argument contains whitespace or
unprintable characters it must be enclosed in double quotes. Within
double quotes the usual "escape sequences" are understood, as shown in
the table below:
Sequence Replaced with
\a Audible bell character (ASCII 7)
\b Backspace character (ASCII 8)
\f Form-feed character (ASCII 12)
\n Newline character (ASCII 10)
\r Carriage return character (ASCII
13)
\t Horizontal tabulation character
(ASCII 9)
\v Vertical tabulation character
(ASCII 11)
\\ Single slash
\" Double quote
Table 24.1: Backslash escapes
In addition, a backslash immediately followed by the end-of-line
character effectively removes that character, allowing to split long
arguments over several input lines.
Command parameters may be optional or mandatory. If the number of
actual arguments is less than the number of mandatory parameters,
'gdbmtool' will prompt you to supply missing arguments. For example,
the 'store' command takes two mandatory parameters, so if you invoked it
with no arguments, you would be prompted twice to supply the necessary
data, as shown in example below:
gdbmtool> store
key? three
data? 3
However, such prompting is possible only in interactive mode. In
non-interactive mode (e.g. when running a script), all arguments must be
supplied with each command, otherwise 'gdbmtool' will report an error
and exit immediately.
If the package is compiled with GNU Readline, the input line can be
edited (*note Command Line Editing: (readline)Command Line Editing.).
* Menu:
* variables:: shell variables.
* commands:: shell commands.
* definitions:: how to define structured data.
* startup files::
File: gdbm.info, Node: variables, Next: commands, Up: shell
24.2.1 Shell Variables
----------------------
A number of 'gdbmtool' parameters is kept in its internal variables. To
examine or modify variables, use the 'set' command (*note set::).
-- gdbmtool variable: bool confirm
Whether to ask for confirmation before certain destructive
operations, such as truncating the existing database.
Default is 'true'.
-- gdbmtool variable: string delim1
A string used to delimit fields of a structured datum on output
(*note definitions::).
Default is ',' (a comma). This variable cannot be unset.
-- gdbmtool variable: string delim2
A string used to delimit array items when printing a structured
datum (*note definitions::).
Default is ',' (a comma). This variable cannot be unset.
-- gdbmtool variable: string errorexit
-- gdbmtool variable: bool errorexit
Comma-delimited list of 'GDBM' error codes which cause program
termination. Error codes are specified via their canonical names
(*note Error codes::). The 'GDBM_' prefix can be omitted. Code
name comparison is case-insensitive. Each error code can
optionally be prefixed with minus sign, to indicate that it should
be removed from the resulting list, or with plus sign (which is
allowed for symmetry). A special code 'all' stands for all
available error codes.
In boolean context, the 'true' value is equivalent to 'all', and
'false' (i.e. variable unset) is equivalent to '-all'.
-- gdbmtool variable: string errormask
-- gdbmtool variable: bool errormask
Comma-delimited list of '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 'errorexit'.
-- gdbmtool variable: string pager
The name and command line of the pager program to pipe output to.
This program is used in interactive mode when the estimated number
of output lines is greater then the number of lines on your screen.
The default value is inherited from the environment variable
'PAGER'. Unsetting this variable disables paging.
-- gdbmtool variable: string ps1
Primary prompt string. Its value can contain "conversion
specifiers", consisting of the '%' character followed by another
character. These specifiers are expanded in the resulting prompt
as follows:
Sequence Expansion
-------------------------------------------------------------------
%f name of the current database file
%p program invocation name
%P package name ('GDBM')
%v program version
%_ single space character
%% %
The default value is '%p>%_', i.e. the program name, followed by a
"greater than" sign, followed by a single space.
-- gdbmtool variable: string ps2
Secondary prompt. See 'ps1' for a description of its value. This
prompt is displayed before reading the second and subsequent lines
of a multi-line command.
The default value is '%_>%_'.
-- gdbmtool variable: bool timing
When each command terminates, print an additional line listing
times spent in that command. The line is formatted as follows:
[reorganize r=0.070481 u=0.000200 s=0.000033]
Here, 'reorganize' is the name of the command that finished, the
number after 'r=' is real time spent executing the command, the
number after 'u=' is the user CPU time used and the number after
's=' is the system CPU time used.
-- gdbmtool variable: bool trace
Enable command tracing. This is similar to the shell '-t' option:
before executing each command, 'gdbmtool' will print on standard
error a line starting with a plus sign and followed by the command
name and its arguments.
-- gdbmtool variable: bool quiet
Whether to display a welcome banner at startup. To affect
'gdbmtool', this variable should be set in a startup script file
(*note startup files::). *Note -q option::.
The following variables control how the database is opened:
-- gdbmtool variable: numeric blocksize
Sets the block size. *Note block_size: Open. Unset by default.
-- gdbmtool variable: numeric cachesize
Sets the cache size. *Note GDBM_SETCACHESIZE: Options.
This variable affects the currently opened database immediately.
It is also used by 'open' command.
To enable automatic cache size selection, unset this variable.
This is the default.
-- gdbmtool variable: string filename
Name of the database file. If the 'open' command is called without
argument (e.g. called implicitly), this variable names the
database file to open. If 'open' is called with file name
argument, upon successful opening of the database the 'filename'
variable is initialized with its file name.
This variable cannot be unset.
-- gdbmtool variable: number fd
File descriptor of the database file to open. If this variable is
set, its value must be an open file descriptor referring to a
'GDBM' database file. The 'open' command will use 'gdbm_fd_open'
function to use this file (*note gdbm_fd_open::). When this
database is closed, the descriptor will be closed as well and the
'fd' variable will be unset.
See also the '-d' ('--db-descriptor') command line option in *note
invocation::.
-- gdbmtool variable: string format
Defines the format in which new databases will be created. Allowed
values are:
'standard'
Databases will be created in standard format. This is the
format used by all 'GDBM' versions prior to 1.21. This value
is the default.
'numsync'
Extended format, best for crash-tolerant applications. *Note
Numsync::, for a discussion of this format.
-- gdbmtool variable: string open
Open mode. The following values are allowed:
newdb
Truncate the database if it exists or create a new one. Open
it in read-write mode.
Technically, this sets the 'GDBM_NEWDB' flag in call to
'gdbm_open'. *Note GDBM_NEWDB: Open.
wrcreat
rw
Open the database in read-write mode. Create it if it does
not exist. This is the default.
Technically speaking, it sets the 'GDBM_WRCREAT' flag in call
to 'gdbm_open'. *Note GDBM_WRCREAT: Open.
reader
readonly
Open the database in read-only mode. Signal an error if it
does not exist.
This sets the 'GDBM_READER' flag (*note GDBM_READER: Open.).
Attempting to set any other value or to unset this variable results
in error.
-- gdbmtool variable: number filemode
File mode (in octal) for creating new database files and database
dumps.
-- gdbmtool variable: bool lock
Lock the database. This is the default.
Setting this variable to false or unsetting it results in passing
'GDBM_NOLOCK' flag to 'gdbm_open' (*note GDBM_NOLOCK: Open.).
-- gdbmtool variable: bool mmap
Use memory mapping. This is the default.
Setting this variable to false or unsetting it results in passing
'GDBM_NOMMAP' flag to 'gdbm_open' (*note GDBM_NOMMAP: Open.).
-- gdbmtool variable: bool sync
Flush all database writes on disk immediately. Default is false.
*Note GDBM_SYNC: Open.
-- gdbmtool variable: bool coalesce
Enables the _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 'gdbm_delete'. *Note
GDBM_SETCOALESCEBLKS: Options.
This variable affects the currently opened database immediately and
will be used by 'open' command, when it is invoked.
-- gdbmtool variable: bool centfree
Set to 'true', enables the use of central free block pool in newly
opened databases. *Note GDBM_SETCENTFREE: Options.
This variable affects the currently opened database immediately and
will be used by 'open' command, when it is invoked.
The following commands are used to list or modify the variables:
-- command verb: set [ASSIGNMENTS]
When used without arguments, lists all variables and their values.
Unset variables are shown after a comment sign ('#'). For string
and numeric variables, values are shown after an equals sign. For
boolean variables, only the variable name is displayed if the
variable is 'true'. If it is 'false', its name is prefixed with
'no'.
For example:
# blocksize is unset
# cachesize is unset
nocentfree
nocoalesce
confirm
delim1=","
delim2=","
# fd is unset
filemode=644
filename="junk.gdbm"
format="standard"
lock
mmap
open="wrcreat"
pager="less"
ps1="%p>%_"
ps2="%_>%_"
# quiet is unset
nosync
If used with arguments, the 'set' command alters the specified
variables. In this case, arguments are variable assignments in the
form 'NAME=VALUE'. For boolean variables, the VALUE is interpreted
as follows: if it is numeric, '0' stands for 'false', any non-zero
value stands for 'true'. Otherwise, the values 'on', 'true', and
'yes' denote 'true', and 'off', 'false', 'no' stand for 'false'.
Alternatively, only the name of a boolean variable can be supplied
to set it to 'true', and its name prefixed with 'no' can be used to
set it to false. For example, the following command sets the
'delim2' variable to ';' and the 'confirm' variable to 'false':
set delim2=";" noconfirm
-- command verb: unset VARIABLES
Unsets the listed variables. The effect of unsetting depends on
the variable. Unless explicitly described in the discussion of the
variables above, unsetting a boolean variable is equivalent to
setting it to 'false'. Unsetting a string variable is equivalent
to assigning it an empty string.
File: gdbm.info, Node: commands, Next: definitions, Prev: variables, Up: shell
24.2.2 Gdbmtool Commands
------------------------
-- command verb: avail
Print the "avail list".
-- command verb: bucket NUM
Print the bucket number NUM and set it as the current one.
-- command verb: cache
Print the bucket cache.
-- command verb: close
Close the currently open database.
-- command verb: count
Print the number of entries in the database.
-- command verb: current
Print the current bucket.
-- command verb: debug [[+-]TOKEN...]
If 'GDBM' is configured with additional debugging, this statement
queries or sets 'GDBM' internal debugging level. This is intended
for debugging and testing purposes and requires good knowledge of
'GDBM' internals. The use of this command is not recommended.
-- command verb: delete KEY
Delete record with the given KEY
-- command verb: dir
Print hash directory.
-- command verb: downgrade
Downgrade the database from extended to the standard database
format. *Note Numsync::.
-- command verb: export FILE-NAME [truncate] [binary|ascii]
Export the database to the flat file FILE-NAME. *Note Flat
files::, for a description of the flat file format and its
purposes. This command will not overwrite an existing file, unless
the 'truncate' parameter is also given. Another optional argument
determines the type of the dump (*note Flat files::). By default,
ASCII dump is created.
The global variable 'filemode' specifies the permissions to use for
the created output file.
-- command verb: fetch KEY
Fetch and display the record with the given KEY.
-- command verb: first
Fetch and display the first record in the database. Subsequent
records can be fetched using the 'next' command (see below). *Note
Sequential::, for more information on sequential access.
-- command verb: hash KEY
Compute and display the hash value for the given KEY.
-- command verb: header
Print file header.
-- command verb: help
-- command verb: ?
Print a concise command summary, showing each command verb with its
parameters and a short description of what it does. Optional
arguments are enclosed in square brackets.
-- command verb: import FILE-NAME [replace] [nometa]
Import data from a flat dump file FILE-NAME (*note Flat files::).
If the word 'replace' is given as an argument, any records with the
same keys as the already existing ones will replace them. The word
'nometa' turns off restoring meta-information from the dump file.
-- command verb: history
-- command verb: history COUNT
-- command verb: history N COUNT
Shows the command history list with line numbers. When used
without arguments, shows entire history. When used with one
argument, displays COUNT last commands from the history. With two
arguments, displays COUNT commands starting from Nth command.
Command numbering starts with 1.
This command is available only if 'GDBM' was compiled with GNU
Readline. The history is saved in 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 'gdbmtool' invocations.
-- command verb: list
List the contents of the database.
-- command verb: next [KEY]
Sequential access: fetch and display the next record. If the KEY
is given, the record following the one with this key will be
fetched.
Issuing several 'next' commands in row is rather common. A
shortcut is provided to facilitate such use: if the last entered
command was 'next', hitting the 'Enter' key repeats it without
arguments.
See also 'first', above.
*Note Sequential::, for more information on sequential access.
-- command verb: open FILENAME
-- command verb: open
Open the database file FILENAME. If used without arguments, the
database name is taken from the variable 'filename'.
If successful, any previously open database is closed and the
'filename' variable is updated. Otherwise, if the operation fails,
the currently opened database remains unchanged.
This command takes additional information from the following
variables:
'filename'
Name of the database to open, if no argument is given.
'fd'
File descriptor to use. If set, this must be an open file
descriptor referring to a valid database file. The database
will be opened using 'gdbm_fd_open' (*note gdbm_fd_open::).
The file descriptor will be closed and the variable unset upon
closing the database.
'filemode'
Specifies the permissions to use in case a new file is
created.
'open'
The database access mode. *Note The OPEN variable: openvar,
for a list of its values.
'lock'
Whether or not to lock the database. Default is 'on'.
'mmap'
Use the memory mapping. Default is 'on'.
'sync'
Synchronize after each write. Default is 'off'.
*Note open parameters::, for a detailed description of these
variables.
-- command verb: perror [CODE]
Describe the given 'GDBM' error code.
The description occupies one or two lines. The second line is
present if the system error number should be checked when handling
this code. In this case, the second line states 'Examine errno'.
If CODE is omitted, the latest error that occurred in the current
database is described. Second line of the output (if present),
contains description of the latest system error.
Example:
gdbmtool> perror 3
GDBM error code 3: "File open error"
Examine errno.
-- command verb: quit
Close the database and quit the utility.
-- command verb: recover [OPTIONS]
Recover the database from structural inconsistencies. *Note
Database consistency::.
The following OPTIONS are understood:
'backup'
Create a backup copy of the original database.
'max-failed-buckets=N'
Abort recovery process if N buckets could not be recovered.
'max-failed-keys=N'
Abort recovery process if N keys could not be recovered.
'max-failures=N'
Abort recovery process after N failures. A "failure" in this
context is either a key or a bucket that failed to be
recovered.
'summary'
Print the recovery statistics at the end of the run. The
statistics includes number of successfully recovered, failed
and duplicate keys and the number of recovered and failed
buckets.
'verbose'
Verbosely list each error encountered.
-- command verb: reorganize
Reorganize the database (*note Reorganization::).
-- command verb: shell COMMAND
-- command verb: ! COMMAND
Execute COMMAND via current shell. If COMMAND is empty, shell is
started without additional arguments. Otherwise, it is run as
'$SHELL -c COMMAND'.
For convenience, COMMAND is not parsed as 'gdbmtool' command line.
It is passed to the shell verbatim. It can include newline
characters if these are preceded by a backslash or appear within
singly or doubly quoted strings.
When using '!' form, be sure to separate it from COMMAND by
whitespace, otherwise it will be treated as readline "event
specifier".
-- command verb: snapshot FILENAME FILENAME
Analyze two snapshot files and select the most recent of them. In
case of error, display a detailed diagnostics and meta-information
of both snapshots.
*Note Manual crash recovery::, for a detailed discussion.
-- command verb: source FILENAME
Read 'gdbmtool' commands from the file FILENAME.
-- command verb: status
Print current program status. The following example shows the
information displayed:
Database file: junk.gdbm
Database is open
define key string
define content string
The two 'define' strings show the defined formats for key and
content data. *Note definitions::, for a detailed discussion of
their meaning.
-- command verb: store KEY DATA
Store the DATA with KEY in the database. If KEY already exists,
its data will be replaced.
-- command verb: sync
Synchronize the database with the disk storage (*note Sync::).
-- command verb: upgrade
Upgrade the database from standard to extended database format.
*Note Numsync::.
-- command verb: version
Print the version of 'gdbm'.
File: gdbm.info, Node: definitions, Next: startup files, Prev: commands, Up: shell
24.2.3 Data Definitions
-----------------------
'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. 'Gdbmtool'
provides a mechanism for handling such kind of records.
The 'define' command defines a record structure. The general syntax
is:
define WHAT DEFINITION
where WHAT is 'key' to defining the structure of key data and 'content'
to define the structure of the content records.
The DEFINITION can be of two distinct formats. In the simplest case
it is a single data type. For example,
define content int
defines content records consisting of a single integer field. Supported
data types are:
char
Single byte (signed).
short
Signed short integer.
ushort
Unsigned short integer.
int
Signed integer.
unsigned
uint
Unsigned integer.
long
Signed long integer.
ulong
Unsigned long integer.
llong
Signed long long integer.
ullong
Unsigned long long integer.
float
A floating point number.
double
Double-precision floating point number.
string
Array of bytes.
stringz
Null-terminated string, trailing null being part of the string.
All numeric data types (integer as well as floating point) have the
same respective widths as in C language on the host where the database
file resides.
The 'string' and 'stringz' are special. Both define a string of
bytes, similar to 'char x[]' in C. The former defines an array of bytes,
the latter - a null-terminated string. This makes a difference, in
particular, when the string is the only part of datum. Consider the
following two definitions:
1. 'define key string'
2. 'define key stringz'
Now, suppose we want to store the string "ab" in the key. Using the
definition (1), the 'dptr' member of 'GDBM' 'datum' will contain two
bytes: 'a', and 'b'. Consequently, the 'dsize' member will have the
value 2. Using the definition (2), the 'dptr' member will contain three
bytes: 'a', 'b', and ASCII 0. The 'dsize' member will have the value 3.
The definition (1) is the default for both key and content.
The second form of the 'define' statement is similar to the C
'struct' statement and allows for defining structural data. In this
form, the DEFINITION part is a comma-separated list of data types and
variables enclosed in curly braces. In contrast to the rest of 'gdbm'
commands, this command is inherently multiline and is terminated with
the closing curly brace. For example:
define content {
int status,
pad 8,
char id[3],
string name
}
This defines a structure consisting of three members: an integer
'status', an array of 3 bytes 'id', and an array of bytes 'name'.
Notice the 'pad' statement: it allows to introduce padding between
structure members. Another useful statement is 'offset': it specifies
that the member following it begins at the given offset in the
structure. Assuming the size of 'int' is 8 bytes, the above definition
can also be written as
define content {
int status,
offset 16,
char id[3],
string name
}
_NOTE_: The 'string' type can reasonably be used only if it is the
last or the only member of the data structure. That's because it
provides no information about the number of elements in the array, so it
is interpreted to contain all bytes up to the end of the datum.
When displaying the structured data, 'gdbmtool' precedes each value
with the corresponding field name and delimits parts of the structure
with the string defined in the 'delim1' variable (*note variables::).
Array elements are delimited using the string from 'delim2'. For
example:
gdbmtool> fetch foo
status=2,id={ a, u, x },name="quux"
To supply a structured datum as an argument to a 'gdbmtool' command,
use the same notation, e.g.:
gdbmtool> store newkey { status=2, id={a,u,x}, name="quux" }
The order in which the fields are listed is not significant. The
above command can as well be written as:
gdbmtool> store newkey { id={a,u,x}, status=2, name="quux" }
You are not required to supply all defined fields. Any number of
them can be omitted, provided that at least one remains. The omitted
fields are filled with 0:
gdbmtool> store newkey { name="bar" }
gdbmtool> fetch newkey
status=0,id={ ,, },name=bar
Yet another way to supply structured data to a command is by listing
the value for each field in the order they are defined, without field
names:
gdbmtool> store newkey { 2, {a,u,x}, "quux" }
File: gdbm.info, Node: startup files, Prev: definitions, Up: shell
24.2.4 Startup Files
--------------------
Upon startup 'gdbmtool' looks for a file named '.gdbmtoolrc' first in
the current working directory and, if not found, in the home directory
of the user who started the command.
If found, this file is read and interpreted as a list of 'gdbmtool'
commands. This allows you to customize the program behavior.
Following is an example startup file which disables the welcome
banner, sets command line prompt to contain the name of the database
file in parentheses and defines the structure of the database content
records:
set quiet
set ps1="(%f) "
define key stringz
define content {
int time,
pad 4,
int status
}
File: gdbm.info, Node: gdbm_dump, Next: gdbm_load, Prev: gdbmtool, Up: Top
25 The 'gdbm_dump' utility
**************************
The 'gdbm_dump' utility creates a flat file dump of a 'GDBM' database
(*note 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, 'gdbm_dump' will produce the dump on
the standard output.
For example, the following invocation creates a dump of the database
'file.db' in the file 'file.dump':
$ gdbm_dump file.db file.dump
By default the utility creates dumps in ASCII format (*note ASCII:
Flat files.). Another format can be requested using the '--format'
('-H') option.
The 'gdbm_dump' utility understands the following command line
options:
'-H FMT'
'--format=FMT'
Select output format. Valid values for FMT are: 'binary' or '0' to
select binary dump format, and 'ascii' or '1' to select ASCII
format.
'-h'
'--help'
Print a concise help summary.
'-V'
'--version'
Print program version and licensing information and exit.
'--usage'
Print a terse invocation syntax summary along with a list of
available command line options.
File: gdbm.info, Node: gdbm_load, Next: Exit codes, Prev: gdbm_dump, Up: Top
26 The 'gdbm_load' utility
**************************
The 'gdbm_load' utility restores a 'GDBM' database from a flat file.
The utility requires at least one argument: the name of the input flat
file. If it is '-', the standard input will be read. The format of the
input file is detected automatically.
By default the utility attempts to restore the database under its
original name, as stored in the input file. It will fail to do so if
the input is in binary format. In that case, the name of the database
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.
The utility understands the following command line arguments:
'-b NUM'
'--block-size=NUM'
Sets block size. *Note block_size: Open.
'-c NUM'
'--cache-size=NUM'
Sets cache size. *Note GDBM_SETCACHESIZE: Options.
'-M'
'--mmap'
Use memory mapping.
'-m MODE'
'--mode=MODE'
Sets the file mode. The argument is the desired file mode in
octal.
'-n'
'--no-meta'
Do not restore file meta-data (ownership and mode) from the flat
file.
'-r'
'--replace'
Replace existing keys.
'-u USER[:GROUP]'
'--user=USER[:GROUP]'
Set file owner. The USER can be either a valid user name or UID.
Similarly, the GROUP is either a valid group name or GID. If GROUP
is not given, the main group of USER is used.
User and group parts can be separated by a dot, instead of the
colon.
'-h'
'--help'
Print a concise help summary.
'-V'
'--version'
Print program version and licensing information and exit.
'--usage'
Print a terse invocation syntax summary along with a list of
available command line options.
File: gdbm.info, Node: Exit codes, Next: Bugs, Prev: gdbm_load, Up: Top
27 Exit codes
*************
All 'GDBM' utilities return uniform exit codes. These are summarized in
the table below:
Code Meaning
--------------------------------------------------------------------------
0 Successful termination.
1 A fatal error occurred.
2 Program was unable to restore file ownership or
mode.
3 Command line usage error.
File: gdbm.info, Node: Bugs, Next: Resources, Prev: Exit codes, Up: Top
28 Problems and bugs
********************
If you have problems with GNU 'dbm' or think you've found a bug, please
report it. Before reporting a bug, make sure you've actually found a
real bug. Carefully reread the documentation and see if it really says
you can do what you're trying to do. If it's not clear whether you
should be able to do something or not, report that too; it's 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 'GDBM' gave you. Also
say what you expected to occur; this will help us decide whether the
problem was really in the documentation.
Once you've got a precise problem, send e-mail to .
Please include the version number of GNU 'dbm' you are using. You
can get this information by printing the variable 'gdbm_version' (*note
Variables::).
Non-bug suggestions are always welcome as well. If you have
questions about things that are unclear in the documentation or are just
obscure features, please report them too.
You may contact the authors and maintainers by e-mail: Philip Nelson
, Jason Downs , Sergey Poznyakoff
or .
Crash tolerance support written by Terence Kelly ,
, or .
File: gdbm.info, Node: Resources, Next: GNU Free Documentation License, Prev: Bugs, Up: Top
29 Additional resources
***********************
For the latest updates and pointers to additional resources, visit
.
In particular, a copy of 'GDBM' documentation in various formats is
available online at .
Latest versions of 'GDBM' can be downloaded from anonymous FTP:
, or via HTTP from
, or via HTTPS from
, or from any GNU mirror worldwide. See
, for a list of mirrors.
To track 'GDBM' development, visit
.
File: gdbm.info, Node: GNU Free Documentation License, Next: Index, Prev: Resources, Up: Top
Appendix A GNU Free Documentation License
*****************************************
Version 1.3, 3 November 2008
Copyright (C) 2000-2002, 2007-2008, 2011, 2017-2022 Free
Software Foundation, Inc.
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or
noncommercially. Secondarily, this License preserves for the
author and publisher a way to get credit for their work, while not
being considered responsible for modifications made by others.
This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense.
It complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for
free software, because free software needs free documentation: a
free program should come with manuals providing the same freedoms
that the software does. But this License is not limited to
software manuals; it can be used for any textual work, regardless
of subject matter or whether it is published as a printed book. We
recommend this License principally for works whose purpose is
instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium,
that contains a notice placed by the copyright holder saying it can
be distributed under the terms of this License. Such a notice
grants a world-wide, royalty-free license, unlimited in duration,
to use that work under the conditions stated herein. The
"Document", below, refers to any such manual or work. Any member
of the public is a licensee, and is addressed as "you". You accept
the license if you copy, modify or distribute the work in a way
requiring permission under copyright law.
A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section
of the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall
subject (or to related matters) and contains nothing that could
fall directly within that overall subject. (Thus, if the Document
is in part a textbook of mathematics, a Secondary Section may not
explain any mathematics.) The relationship could be a matter of
historical connection with the subject or with related matters, or
of legal, commercial, philosophical, ethical or political position
regarding them.
The "Invariant Sections" are certain Secondary Sections whose
titles are designated, as being those of Invariant Sections, in the
notice that says that the Document is released under this License.
If a section does not fit the above definition of Secondary then it
is not allowed to be designated as Invariant. The Document may
contain zero Invariant Sections. If the Document does not identify
any Invariant Sections then there are none.
The "Cover Texts" are certain short passages of text that are
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
that says that the Document is released under this License. A
Front-Cover Text may be at most 5 words, and a Back-Cover Text may
be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed
of pixels) generic paint programs or (for drawings) some widely
available drawing editor, and that is suitable for input to text
formatters or for automatic translation to a variety of formats
suitable for input to text formatters. A copy made in an otherwise
Transparent file format whose markup, or absence of markup, has
been arranged to thwart or discourage subsequent modification by
readers is not Transparent. An image format is not Transparent if
used for any substantial amount of text. A copy that is not
"Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format,
SGML or XML using a publicly available DTD, and standard-conforming
simple HTML, PostScript or PDF designed for human modification.
Examples of transparent image formats include PNG, XCF and JPG.
Opaque formats include proprietary formats that can be read and
edited only by proprietary word processors, SGML or XML for which
the DTD and/or processing tools are not generally available, and
the machine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the
material this License requires to appear in the title page. For
works in formats which do not have any title page as such, "Title
Page" means the text near the most prominent appearance of the
work's title, preceding the beginning of the body of the text.
The "publisher" means any person or entity that distributes copies
of the Document to the public.
A section "Entitled XYZ" means a named subunit of the Document
whose title either is precisely XYZ or contains XYZ in parentheses
following text that translates XYZ in another language. (Here XYZ
stands for a specific section name mentioned below, such as
"Acknowledgements", "Dedications", "Endorsements", or "History".)
To "Preserve the Title" of such a section when you modify the
Document means that it remains a section "Entitled XYZ" according
to this definition.
The Document may include Warranty Disclaimers next to the notice
which states that this License applies to the Document. These
Warranty Disclaimers are considered to be included by reference in
this License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and
has no effect on the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License
applies to the Document are reproduced in all copies, and that you
add no other conditions whatsoever to those of this License. You
may not use technical measures to obstruct or control the reading
or further copying of the copies you make or distribute. However,
you may accept compensation in exchange for copies. If you
distribute a large enough number of copies you must also follow the
conditions in section 3.
You may also lend copies, under the same conditions stated above,
and you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly
have printed covers) of the Document, numbering more than 100, and
the Document's license notice requires Cover Texts, you must
enclose the copies in covers that carry, clearly and legibly, all
these Cover Texts: Front-Cover Texts on the front cover, and
Back-Cover Texts on the back cover. Both covers must also clearly
and legibly identify you as the publisher of these copies. The
front cover must present the full title with all words of the title
equally prominent and visible. You may add other material on the
covers in addition. Copying with changes limited to the covers, as
long as they preserve the title of the Document and satisfy these
conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto
adjacent pages.
If you publish or distribute Opaque copies of the Document
numbering more than 100, you must either include a machine-readable
Transparent copy along with each Opaque copy, or state in or with
each Opaque copy a computer-network location from which the general
network-using public has access to download using public-standard
network protocols a complete Transparent copy of the Document, free
of added material. If you use the latter option, you must take
reasonably prudent steps, when you begin distribution of Opaque
copies in quantity, to ensure that this Transparent copy will
remain thus accessible at the stated location until at least one
year after the last time you distribute an Opaque copy (directly or
through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of
the Document well before redistributing any large number of copies,
to give them a chance to provide you with an updated version of the
Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document
under the conditions of sections 2 and 3 above, provided that you
release the Modified Version under precisely this License, with the
Modified Version filling the role of the Document, thus licensing
distribution and modification of the Modified Version to whoever
possesses a copy of it. In addition, you must do these things in
the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title
distinct from that of the Document, and from those of previous
versions (which should, if there were any, be listed in the
History section of the Document). You may use the same title
as a previous version if the original publisher of that
version gives permission.
B. List on the Title Page, as authors, one or more persons or
entities responsible for authorship of the modifications in
the Modified Version, together with at least five of the
principal authors of the Document (all of its principal
authors, if it has fewer than five), unless they release you
from this requirement.
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license
notice giving the public permission to use the Modified
Version under the terms of this License, in the form shown in
the Addendum below.
G. Preserve in that license notice the full lists of Invariant
Sections and required Cover Texts given in the Document's
license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title,
and add to it an item stating at least the title, year, new
authors, and publisher of the Modified Version as given on the
Title Page. If there is no section Entitled "History" in the
Document, create one stating the title, year, authors, and
publisher of the Document as given on its Title Page, then add
an item describing the Modified Version as stated in the
previous sentence.
J. Preserve the network location, if any, given in the Document
for public access to a Transparent copy of the Document, and
likewise the network locations given in the Document for
previous versions it was based on. These may be placed in the
"History" section. You may omit a network location for a work
that was published at least four years before the Document
itself, or if the original publisher of the version it refers
to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications",
Preserve the Title of the section, and preserve in the section
all the substance and tone of each of the contributor
acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document, unaltered
in their text and in their titles. Section numbers or the
equivalent are not considered part of the section titles.
M. Delete any section Entitled "Endorsements". Such a section
may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled
"Endorsements" or to conflict in title with any Invariant
Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no
material copied from the Document, you may at your option designate
some or all of these sections as invariant. To do this, add their
titles to the list of Invariant Sections in the Modified Version's
license notice. These titles must be distinct from any other
section titles.
You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text
has been approved by an organization as the authoritative
definition of a standard.
You may add a passage of up to five words as a Front-Cover Text,
and a passage of up to 25 words as a Back-Cover Text, to the end of
the list of Cover Texts in the Modified Version. Only one passage
of Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document
already includes a cover text for the same cover, previously added
by you or by arrangement made by the same entity you are acting on
behalf of, you may not add another; but you may replace the old
one, on explicit permission from the previous publisher that added
the old one.
The author(s) and publisher(s) of the Document do not by this
License give permission to use their names for publicity for or to
assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under
this License, under the terms defined in section 4 above for
modified versions, provided that you include in the combination all
of the Invariant Sections of all of the original documents,
unmodified, and list them all as Invariant Sections of your
combined work in its license notice, and that you preserve all
their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name
but different contents, make the title of each such section unique
by adding at the end of it, in parentheses, the name of the
original author or publisher of that section if known, or else a
unique number. Make the same adjustment to the section titles in
the list of Invariant Sections in the license notice of the
combined work.
In the combination, you must combine any sections Entitled
"History" in the various original documents, forming one section
Entitled "History"; likewise combine any sections Entitled
"Acknowledgements", and any sections Entitled "Dedications". You
must delete all sections Entitled "Endorsements."
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other
documents released under this License, and replace the individual
copies of this License in the various documents with a single copy
that is included in the collection, provided that you follow the
rules of this License for verbatim copying of each of the documents
in all other respects.
You may extract a single document from such a collection, and
distribute it individually under this License, provided you insert
a copy of this License into the extracted document, and follow this
License in all other respects regarding verbatim copying of that
document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other
separate and independent documents or works, in or on a volume of a
storage or distribution medium, is called an "aggregate" if the
copyright resulting from the compilation is not used to limit the
legal rights of the compilation's users beyond what the individual
works permit. When the Document is included in an aggregate, this
License does not apply to the other works in the aggregate which
are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half
of the entire aggregate, the Document's Cover Texts may be placed
on covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic
form. Otherwise they must appear on printed covers that bracket
the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section
4. Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also
include the original English version of this License and the
original versions of those notices and disclaimers. In case of a
disagreement between the translation and the original version of
this License or a notice or disclaimer, the original version will
prevail.
If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to
Preserve its Title (section 1) will typically require changing the
actual title.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense, or distribute it is void,
and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the
copyright holder fails to notify you of the violation by some
reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from
that copyright holder, and you cure the violation prior to 30 days
after your receipt of the notice.
Termination of your rights under this section does not terminate
the licenses of parties who have received copies or rights from you
under this License. If your rights have been terminated and not
permanently reinstated, receipt of a copy of some or all of the
same material does not give you any rights to use it.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of
the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
.
Each version of the License is given a distinguishing version
number. If the Document specifies that a particular numbered
version of this License "or any later version" applies to it, you
have the option of following the terms and conditions either of
that specified version or of any later version that has been
published (not as a draft) by the Free Software Foundation. If the
Document does not specify a version number of this License, you may
choose any version ever published (not as a draft) by the Free
Software Foundation. If the Document specifies that a proxy can
decide which future versions of this License can be used, that
proxy's public statement of acceptance of a version permanently
authorizes you to choose that version for the Document.
11. RELICENSING
"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works. A
public wiki that anybody can edit is an example of such a server.
A "Massive Multiauthor Collaboration" (or "MMC") contained in the
site means any set of copyrightable works thus published on the MMC
site.
"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
license published by Creative Commons Corporation, a not-for-profit
corporation with a principal place of business in San Francisco,
California, as well as future copyleft versions of that license
published by that same organization.
"Incorporate" means to publish or republish a Document, in whole or
in part, as part of another Document.
An MMC is "eligible for relicensing" if it is licensed under this
License, and if all works that were first published under this
License somewhere other than this MMC, and subsequently
incorporated in whole or in part into the MMC, (1) had no cover
texts or invariant sections, and (2) were thus incorporated prior
to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the
site under CC-BY-SA on the same site at any time before August 1,
2009, provided the MMC is eligible for relicensing.
ADDENDUM: How to use this License for your documents
====================================================
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:
Copyright (C) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:
with the Invariant Sections being LIST THEIR TITLES, with
the Front-Cover Texts being LIST, and with the Back-Cover Texts
being LIST.
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of free
software license, such as the GNU General Public License, to permit
their use in free software.
File: gdbm.info, Node: Index, Prev: GNU Free Documentation License, Up: Top
Index
*****
[index ]
* Menu:
* !: commands. (line 204)
* (*errfun) of gdbm_recovery: Recovery. (line 52)
* --newdb, gdbmtool option: gdbmtool. (line 20)
* --read-only, gdbmtool option: gdbmtool. (line 16)
* -n, gdbmtool option: gdbmtool. (line 20)
* -r, gdbmtool option: gdbmtool. (line 16)
* .gdbmtoolrc: startup files. (line 6)
* ?: commands. (line 66)
* _GDBM_MAX_ERRNO: Variables. (line 31)
* _GDBM_MIN_ERRNO: Variables. (line 28)
* avail: commands. (line 6)
* backup_name of gdbm_recovery: Recovery. (line 99)
* blocksize: variables. (line 104)
* bucket: commands. (line 9)
* cache: commands. (line 12)
* cachesize: variables. (line 107)
* centfree: variables. (line 205)
* close: commands. (line 15)
* close-on-exec: Open. (line 49)
* closing database: Close. (line 6)
* coalesce: variables. (line 195)
* command line options, gdbmtool: invocation. (line 6)
* compatibility layer: Compatibility. (line 6)
* confirm: variables. (line 9)
* consistency, database: Database consistency.
(line 6)
* count: commands. (line 18)
* creating a database, gdbmtool: gdbmtool. (line 20)
* current: commands. (line 21)
* data of gdbm_recovery: Recovery. (line 62)
* database options: Options. (line 6)
* database reorganization: Reorganization. (line 6)
* database synchronization: Sync. (line 6)
* database, closing: Close. (line 6)
* database, opening or creating: Open. (line 6)
* datum: Intro. (line 12)
* DBM functions: dbm. (line 6)
* dbm.h: Compatibility. (line 10)
* dbmclose: dbm. (line 22)
* dbminit: dbm. (line 10)
* dbm_clearerr: ndbm. (line 95)
* dbm_close: ndbm. (line 25)
* dbm_delete: ndbm. (line 56)
* dbm_dirfno: ndbm. (line 98)
* dbm_error: ndbm. (line 90)
* dbm_fetch: ndbm. (line 29)
* dbm_firstkey: ndbm. (line 61)
* DBM_INSERT: ndbm. (line 49)
* dbm_nextkey: ndbm. (line 71)
* dbm_open: ndbm. (line 8)
* dbm_pagfno: ndbm. (line 106)
* dbm_rdonly: ndbm. (line 110)
* DBM_REPLACE: ndbm. (line 46)
* dbm_store: ndbm. (line 38)
* debug: commands. (line 24)
* default database, gdbmtool: gdbmtool. (line 9)
* delete: dbm. (line 41)
* delete <1>: commands. (line 30)
* deleting records: Delete. (line 6)
* deletion in iteration loops: Sequential. (line 60)
* delim1: variables. (line 15)
* delim2: variables. (line 21)
* dir: commands. (line 33)
* dir file: Compatibility. (line 21)
* downgrade: commands. (line 36)
* error code, most recent: Errors. (line 21)
* error codes: Error codes. (line 6)
* error strings: Errors. (line 6)
* errorexit: variables. (line 27)
* errorexit <1>: variables. (line 28)
* errormask: variables. (line 41)
* errormask <1>: variables. (line 42)
* exit code: Exit codes. (line 6)
* export: Flat files. (line 6)
* export <1>: commands. (line 40)
* failed_buckets of gdbm_recovery: Recovery. (line 96)
* failed_keys of gdbm_recovery: Recovery. (line 93)
* fd: variables. (line 125)
* fetch: dbm. (line 25)
* fetch <1>: commands. (line 51)
* fetching records: Fetch. (line 6)
* filemode: variables. (line 175)
* filename: variables. (line 116)
* first: commands. (line 54)
* firstkey: dbm. (line 47)
* Flat file format: Flat files. (line 6)
* format: variables. (line 136)
* gdbm.h: Intro. (line 45)
* gdbmtool: gdbmtool. (line 6)
* gdbm_avail_verify: Additional functions.
(line 6)
* GDBM_BACKUP_FAILED: Error codes. (line 180)
* GDBM_BAD_AVAIL: Error codes. (line 196)
* GDBM_BAD_BUCKET: Error codes. (line 187)
* GDBM_BAD_DIR_ENTRY: Error codes. (line 211)
* GDBM_BAD_FILE_OFFSET: Error codes. (line 129)
* GDBM_BAD_HASH_ENTRY: Error codes. (line 237)
* GDBM_BAD_HASH_TABLE: Error codes. (line 204)
* GDBM_BAD_HEADER: Error codes. (line 191)
* GDBM_BAD_MAGIC_NUMBER: Error codes. (line 51)
* GDBM_BAD_OPEN_FLAGS: Error codes. (line 133)
* GDBM_BLOCK_SIZE_ERROR: Error codes. (line 15)
* GDBM_BSEXACT: Open. (line 109)
* GDBM_BSEXACT <1>: Error codes. (line 16)
* GDBM_BUCKET_CACHE_CORRUPTED: Error codes. (line 233)
* gdbm_bucket_count: Count. (line 12)
* GDBM_BYTE_SWAPPED: Error codes. (line 125)
* GDBM_CACHESIZE: Options. (line 31)
* GDBM_CANNOT_REPLACE: Error codes. (line 92)
* GDBM_CANT_BE_READER: Error codes. (line 59)
* GDBM_CANT_BE_WRITER: Error codes. (line 64)
* GDBM_CENTFREE: Options. (line 135)
* gdbm_check_syserr: Errors. (line 52)
* gdbm_clear_error: Errors. (line 67)
* GDBM_CLOERROR: Open. (line 162)
* GDBM_CLOEXEC: Open. (line 48)
* gdbm_close: Close. (line 10)
* GDBM_COALESCEBLKS: Options. (line 149)
* gdbm_convert: Database format. (line 18)
* gdbm_copy_meta: Open. (line 165)
* gdbm_count: Count. (line 6)
* gdbm_db_strerror: Errors. (line 59)
* gdbm_delete: Delete. (line 8)
* gdbm_delete and sequential access: Sequential. (line 60)
* GDBM_DIR_OVERFLOW: Error codes. (line 183)
* gdbm_dump: gdbm_dump. (line 6)
* gdbm_dump <1>: Flat files. (line 56)
* gdbm_dump_to_file: Flat files. (line 163)
* GDBM_EMPTY_DATABASE: Error codes. (line 55)
* gdbm_errlist[]: Variables. (line 16)
* gdbm_errno: Errors. (line 6)
* gdbm_errno <1>: Variables. (line 8)
* GDBM_ERR_FILE_MODE: Flat files. (line 151)
* GDBM_ERR_FILE_MODE <1>: Error codes. (line 168)
* GDBM_ERR_FILE_OWNER: Flat files. (line 148)
* GDBM_ERR_FILE_OWNER <1>: Error codes. (line 161)
* GDBM_ERR_REALPATH: Error codes. (line 252)
* GDBM_ERR_SNAPSHOT_CLONE: Error codes. (line 243)
* GDBM_ERR_USAGE: Error codes. (line 260)
* gdbm_exists: Fetch. (line 42)
* gdbm_export: Flat files. (line 186)
* gdbm_export_to_file: Flat files. (line 194)
* gdbm_failure_atomic: Crash Tolerance API. (line 6)
* GDBM_FAST: Open. (line 100)
* GDBM_FASTMODE: Options. (line 109)
* gdbm_fdesc: Locking. (line 13)
* gdbm_fd_open: Open. (line 148)
* gdbm_fetch: Fetch. (line 6)
* GDBM_FILE: Intro. (line 48)
* GDBM_FILE_CLOSE_ERROR: Error codes. (line 215)
* GDBM_FILE_EOF: Error codes. (line 144)
* GDBM_FILE_OPEN_ERROR: Error codes. (line 20)
* GDBM_FILE_READ_ERROR: Error codes. (line 43)
* GDBM_FILE_SEEK_ERROR: Error codes. (line 36)
* GDBM_FILE_STAT_ERROR: Error codes. (line 137)
* GDBM_FILE_SYNC_ERROR: Error codes. (line 220)
* GDBM_FILE_TRUNCATE_ERROR: Error codes. (line 226)
* GDBM_FILE_WRITE_ERROR: Error codes. (line 28)
* gdbm_firstkey: Sequential. (line 13)
* GDBM_GETBLOCKSIZE: Options. (line 203)
* GDBM_GETBUCKETSIZE: Options. (line 105)
* GDBM_GETCACHEAUTO: Options. (line 77)
* GDBM_GETCACHESIZE: Options. (line 60)
* GDBM_GETCOALESCEBLKS: Options. (line 160)
* GDBM_GETDBFORMAT: Options. (line 91)
* GDBM_GETDBNAME: Options. (line 183)
* GDBM_GETDIRDEPTH: Options. (line 97)
* GDBM_GETFLAGS: Options. (line 83)
* GDBM_GETMAXMAPSIZE: Options. (line 170)
* GDBM_GETMMAP: Options. (line 179)
* GDBM_GETSYNCMODE: Options. (line 130)
* GDBM_ILLEGAL_DATA: Error codes. (line 99)
* gdbm_import: Flat files. (line 198)
* gdbm_import_from_file: Flat files. (line 211)
* GDBM_INSERT: Store. (line 20)
* GDBM_ITEM_NOT_FOUND: Error codes. (line 83)
* gdbm_last_errno: Errors. (line 21)
* gdbm_last_syserr: Errors. (line 32)
* gdbm_latest_snapshot: Crash Tolerance API. (line 66)
* gdbm_load: gdbm_load. (line 6)
* gdbm_load <1>: Flat files. (line 85)
* gdbm_load_from_file: Flat files. (line 179)
* GDBM_MALFORMED_DATA: Error codes. (line 98)
* GDBM_MALLOC_ERROR: Error codes. (line 12)
* gdbm_needs_recovery: Errors. (line 79)
* GDBM_NEED_RECOVERY: Error codes. (line 175)
* GDBM_NEWDB: Open. (line 30)
* gdbm_nextkey: Sequential. (line 25)
* GDBM_NOLOCK: Open. (line 53)
* GDBM_NOLOCK <1>: Locking. (line 6)
* GDBM_NOMMAP: Open. (line 57)
* GDBM_NO_DBNAME: Error codes. (line 155)
* GDBM_NO_ERROR: Error codes. (line 9)
* GDBM_NUMSYNC: Database format. (line 25)
* GDBM_NUMSYNC <1>: Open. (line 116)
* gdbm_open: Open. (line 6)
* GDBM_OPT_ALREADY_SET: Error codes. (line 110)
* GDBM_OPT_BADVAL: Error codes. (line 116)
* GDBM_OPT_ILLEGAL: Error codes. (line 117)
* GDBM_PREREAD: Open. (line 61)
* GDBM_RCVR_BACKUP: Recovery. (line 100)
* GDBM_RCVR_ERRFUN: Recovery. (line 54)
* GDBM_RCVR_FORCE: Recovery. (line 106)
* GDBM_RCVR_MAX_FAILED_BUCKETS: Recovery. (line 72)
* GDBM_RCVR_MAX_FAILED_KEYS: Recovery. (line 66)
* GDBM_RCVR_MAX_FAILURES: Recovery. (line 79)
* GDBM_READER: Open. (line 30)
* GDBM_READER_CANT_DELETE: Error codes. (line 68)
* GDBM_READER_CANT_REORGANIZE: Error codes. (line 78)
* GDBM_READER_CANT_STORE: Error codes. (line 73)
* gdbm_recover: Recovery. (line 16)
* gdbm_reorganize: Reorganization. (line 8)
* GDBM_REORGANIZE_FAILED: Error codes. (line 88)
* GDBM_REPLACE: Store. (line 20)
* GDBM_SETCACHEAUTO: Options. (line 64)
* GDBM_SETCACHESIZE: Options. (line 30)
* GDBM_SETCENTFREE: Options. (line 134)
* GDBM_SETCOALESCEBLKS: Options. (line 148)
* GDBM_SETMAXMAPSIZE: Options. (line 164)
* GDBM_SETMMAP: Options. (line 174)
* gdbm_setopt: Options. (line 9)
* GDBM_SETSYNCMODE: Options. (line 117)
* GDBM_SNAPSHOT_BAD: Crash Tolerance API. (line 68)
* GDBM_SNAPSHOT_BAD <1>: Crash recovery. (line 38)
* GDBM_SNAPSHOT_ERR: Crash Tolerance API. (line 68)
* GDBM_SNAPSHOT_ERR <1>: Crash recovery. (line 43)
* GDBM_SNAPSHOT_OK: Crash Tolerance API. (line 68)
* GDBM_SNAPSHOT_SAME: Crash Tolerance API. (line 68)
* GDBM_SNAPSHOT_SAME <1>: Crash recovery. (line 78)
* GDBM_SNAPSHOT_SUSPICIOUS: Crash Tolerance API. (line 79)
* GDBM_SNAPSHOT_SUSPICIOUS <1>: Crash recovery. (line 83)
* gdbm_store: Store. (line 6)
* gdbm_strerror: Errors. (line 12)
* GDBM_SYNC: Open. (line 91)
* GDBM_SYNC <1>: Sync. (line 36)
* gdbm_sync: Sync. (line 13)
* GDBM_SYNCMODE: Options. (line 118)
* gdbm_syserr[]: Variables. (line 23)
* gdbm_version: Variables. (line 34)
* gdbm_version_cmp: Variables. (line 63)
* GDBM_VERSION_MAJOR: Variables. (line 49)
* GDBM_VERSION_MINOR: Variables. (line 52)
* gdbm_version_number[3]: Variables. (line 37)
* GDBM_VERSION_PATCH: Variables. (line 55)
* GDBM_WRCREAT: Open. (line 30)
* GDBM_WRITER: Open. (line 30)
* GDBM_XVERIFY: Open. (line 78)
* global error state: Errors. (line 6)
* GNU Readline: shell. (line 65)
* hash: commands. (line 59)
* header: commands. (line 62)
* help: commands. (line 65)
* history: commands. (line 77)
* history <1>: commands. (line 78)
* history <2>: commands. (line 79)
* import: Flat files. (line 6)
* import <1>: commands. (line 71)
* init file, gdbmtool: startup files. (line 6)
* interactive mode, gdbmtool: shell. (line 6)
* iterating over records: Sequential. (line 6)
* iteration and gdbm_delete: Sequential. (line 60)
* iteration loop: Sequential. (line 40)
* iteration loop, using NDBM: ndbm. (line 79)
* junk.gdbm: gdbmtool. (line 9)
* libgdbm_compat: Compatibility. (line 10)
* list: commands. (line 92)
* lock: variables. (line 179)
* locking: Locking. (line 6)
* logical consistency: Database consistency.
(line 17)
* looking up records: Fetch. (line 6)
* max_failed_buckets of gdbm_recovery: Recovery. (line 71)
* max_failed_keys of gdbm_recovery: Recovery. (line 65)
* max_failures of gdbm_recovery: Recovery. (line 78)
* mmap: variables. (line 185)
* most recent error code: Errors. (line 21)
* NDBM functions: ndbm. (line 6)
* ndbm.h: Compatibility. (line 10)
* next: commands. (line 95)
* nextkey: dbm. (line 57)
* number of records: Count. (line 6)
* open: commands. (line 109)
* open <1>: commands. (line 110)
* open <2>: variables. (line 149)
* opening the database: Open. (line 6)
* options, database: Options. (line 6)
* pag file: Compatibility. (line 21)
* pager: variables. (line 47)
* perror: commands. (line 151)
* ps1: variables. (line 55)
* ps2: variables. (line 73)
* quiet: variables. (line 97)
* quit: commands. (line 168)
* read-only mode, gdbmtool: gdbmtool. (line 16)
* readline: shell. (line 65)
* record, deleting: Delete. (line 6)
* record, fetching: Fetch. (line 6)
* records, iterating over: Sequential. (line 6)
* records, storing: Store. (line 6)
* records, testing existence: Fetch. (line 40)
* recover: commands. (line 171)
* recovered_buckets of gdbm_recovery: Recovery. (line 90)
* recovered_keys of gdbm_recovery: Recovery. (line 87)
* reorganization, database: Reorganization. (line 6)
* reorganize: commands. (line 200)
* sequential access: Sequential. (line 6)
* sequential access, using NDBM: ndbm. (line 79)
* set: variables. (line 214)
* shell: commands. (line 203)
* snapshot: commands. (line 218)
* source: commands. (line 225)
* startup file, gdbmtool: startup files. (line 6)
* status: commands. (line 228)
* store: dbm. (line 34)
* store <1>: commands. (line 241)
* storing records: Store. (line 6)
* structural consistency: Database consistency.
(line 11)
* sync: commands. (line 245)
* sync <1>: variables. (line 191)
* synchronization, database: Sync. (line 6)
* timing: variables. (line 80)
* trace: variables. (line 91)
* unset: variables. (line 257)
* upgrade: commands. (line 248)
* variables, gdbmtool: variables. (line 6)
* version: commands. (line 252)
* version number: Variables. (line 34)
Tag Table:
Node: Top969
Node: Copying3675
Node: Intro5462
Node: Open10910
Ref: gdbm_fd_open18080
Ref: Open-Footnote-118991
Node: Close19062
Node: Count19720
Node: Store20439
Node: Fetch23720
Node: Delete25524
Node: Sequential26277
Node: Reorganization29592
Node: Sync30600
Node: Database format32904
Node: Flat files34267
Ref: gdbm_load function38391
Node: Errors44092
Ref: gdbm_check_syserr46113
Node: Database consistency47957
Node: Recovery49608
Node: Crash Tolerance54611
Node: Filesystems supporting crash tolerance56763
Node: Enabling crash tolerance58425
Node: Synchronizing the Database60063
Node: Crash recovery61348
Ref: Crash recovery-Footnote-165813
Node: Manual crash recovery66122
Node: Performance Impact69063
Node: Availability69795
Node: Numsync70470
Node: Crash Tolerance API72939
Node: Options77070
Node: Locking85192
Node: Variables85784
Node: Additional functions88446
Node: Error codes88902
Node: Compatibility99466
Node: ndbm101264
Node: dbm106061
Node: gdbmtool108719
Node: invocation109689
Ref: -q option111944
Node: shell112630
Ref: backslash-interpretation113883
Node: variables115632
Ref: quiet119673
Ref: open parameters119892
Ref: format variable121282
Ref: openvar121736
Ref: filemode122598
Ref: set124134
Node: commands126090
Ref: gdbmtool export127194
Ref: gdbmtool import128415
Node: definitions134911
Node: startup files139721
Node: gdbm_dump140523
Node: gdbm_load141766
Node: Exit codes143646
Node: Bugs144195
Node: Resources145732
Node: GNU Free Documentation License146501
Node: Index171657
End Tag Table
Local Variables:
coding: utf-8
End:
gdbm-1.23/doc/gdbm_load.1 0000644 0001750 0001750 00000006377 14164261602 012047 0000000 0000000 .\" This file is part of GDBM. -*- nroff -*-
.\" Copyright (C) 2011-2022 Free Software Foundation, Inc.
.\"
.\" GDBM is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
.\" GDBM is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with GDBM. If not, see . */
.TH GDBM_LOAD 1 "December 25, 2013" "GDBM" "GDBM User Reference"
.SH NAME
gdbm_load \- re-create a GDBM database from a dump file.
.SH SYNOPSIS
\fBgdbm_load\fR [\fB\-Mnr\fR] [\fB\-b\fR \fINUM\fR] [\fB\-c\fR \fINUM]\
[\fB\-m\fR \fIMODE\fR]\
[\fB\-u\fR \fINAME\fR|\fIUID\fR[:\fINAME\fR|\fIGID\fR]]
[\fB\-\-block\-size\fR=\fINUM\fR] [\fB\-\-cache\-size\fR=\fINUM\fR]\
[\fB\-\-mmap\fR=\fINUM\fR]
[\fB\-\-mode\fR=\fIMODE\fR]\
[\fB\-\-no\-meta\fR] [\fB\-\-replace\fR]
[\fB\-\-user\fR=\fINAME\fR|\fIUID\fR[:\fINAME\fR|\fIGID\fR]]\
\fIFILE\fR [\fIDB_FILE\fR]
.sp
\fBgdbm_load\fR [\fB\-Vh\fR] [\fB\-\-help\fR] [\fB\-\-usage\fR] [\fB\-\-version\fR]
.SH DESCRIPTION
Create a
.B gdbm
database file
.I DB_FILE
from the dump file
.IR FILE .
If the
.I FILE
argument is not supplied, output the created database to the standard error.
.PP
If the input file is in ASCII dump format, the mode and ownership of
the created database are restored from the information in the dump.
This can be overridden using the command line options (see below).
.SH OPTIONS
.TP
\fB\-b\fR, \fB\-\-block\-size\fR=\fINUM\fR
Sets block size.
.TP
\fB\-c\fR, \fB\-\-cache\-size\fR=\fINUM\fR
Sets cache size.
.TP
\fB\-M\fR, \fB\-\-mmap\fR
Use memory mapping.
.TP
\fB\-m\fR, \fB\-\-mode\fR=\fIMODE\fR
Set database file mode (octal number).
.TP
\fB\-n\fR, \fB\-\-no\-meta\fR
Do not attempt to restore database meta-data (mode and ownership).
.TP
\fB\-r\fR, \fB\-\-replace\fR
If the database exists, replace records in it.
.TP
\fB\-u\fR, \fB\-\-user\fR=\fINAME\fR|\fIUID\fR[:\fINAME\fR|\fIGID\fR]
Set file ownership.
.TP
\fB\-h\fR, \fB\-\-help\fR
Print a short usage summary.
.TP
\fB\-\-usage\fR
Print a list of available options.
.TP
\fB\-V\fR, \fB\-\-version\fR
Print program version
.SH "SEE ALSO"
.BR gdbm_dump (1),
.BR gdbmtool (1),
.BR gdbm (3).
.PP
For a detailed description of
.B gdbm_load
and other
.B gdbm
utilities, refer to the \fBGDBM Manual\fR available in
Texinfo format. To access it, run:
\fBinfo gdbm\fR
.SH "REPORTING BUGS"
Report bugs to .
.SH COPYRIGHT
Copyright \(co 2013-2021 Free Software Foundation, Inc
.br
.na
License GPLv3+: GNU GPL version 3 or later
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH GDBM[A-Z_-]* 1 \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end:
gdbm-1.23/po/ 0000755 0001750 0001750 00000000000 14177231731 007775 5 0000000 0000000 gdbm-1.23/po/da.gmo 0000644 0001750 0001750 00000026705 14177231176 011022 0000000 0000000 Þ• ¨ \ ã œ
( ) . : K i µ Í á þ - F ] y – š ¬ Ä Ó ä õ ! 1 A P a f y Ž Ÿ · Ï Ü ë ð
) F L \ l | ¤ Å Ô Ø Ý s ê ^ r v ” › &