dbopen(3)dbopen(3)NAMEdbopen - database access methods
SYNOPSIS
#include <sys/types.h> #include <limits.h> #include <db.h>
DB *
dbopen(
const char *file,
int option,
int mode,
DBTYPE type,
const void *openinfo );
DESCRIPTION
The dbopen() function is the library interface to database files. The
supported file formats are btree, hashed, and UNIX file oriented. The
btree format is a representation of a sorted, balanced tree structure.
The hashed format is an extensible, dynamic hashing scheme. The flat-
file format is a byte stream file with fixed or variable length
records. The formats and file format specific information are described
in detail in their respective manual pages: btree(3), hash(3), and
recno(3).
The dbopen() function opens file for reading and/or writing. Files
never intended to be preserved on disk can be created by setting the
file parameter to NULL.
The option and mode arguments are as specified to the open(2) routine;
however, only the O_CREAT, O_EXCL, O_EXLOCK, O_NONBLOCK, O_RDONLY,
O_RDWR, O_SHLOCK, and O_TRUNC options are meaningful. (Note, opening a
database file O_WRONLY is not possible.)
The type argument is of type DBTYPE (as defined in the <db.h> include
file) and can be set to DB_BTREE, DB_HASH, or DB_RECNO.
The openinfo argument is a pointer to an access method specific struc‐
ture described in the access method's manual page. If openinfo is
NULL, each access method will use defaults appropriate for the system
and the access method.
The dbopen() function returns a pointer to a DB structure on success
and NULL on error. The DB structure is defined in the <db.h> include
file and contains at least the following fields:
typedef struct { DBTYPE type; int (*close)(const DB *db); int
(*del)(const DB *db, const DBT *key, u_int option); int (*fd)(const DB
*db); int (*get)(const DB *db, DBT *key, DBT *data, u_int option); int
(*put)(const DB *db, DBT *key, const DBT *data, u_int option); int
(*sync)(const DB *db, u_int option); int (*seq)(const DB *db, DBT *key,
DBT *data, u_int option); } DB;
These elements describe a database type and a set of functions perform‐
ing various actions. The functions take a pointer to a structure as
returned by dbopen(), and sometimes one or more pointers to key/data
structures and a option value. The type of the underlying access
method (and file format). A pointer to a routine to flush any cached
information to disk, free any allocated resources, and close the under‐
lying file(s). Because key/data pairs can be cached in memory, failing
to sync the file with a close or sync function may result in inconsis‐
tent or lost information. The close routines return -1 on error (set‐
ting errno) and 0 on success. A pointer to a routine to remove
key/data pairs from the database.
The parameter option can be set to the following value: Delete
the record referenced by the cursor. The cursor must have pre‐
viously been initialized.
The del routines return -1 on error (setting errno), 0 on suc‐
cess, and 1 if the specified key was not in the file. A pointer
to a routine that returns a file descriptor representative of
the underlying database. A file descriptor referencing the same
file will be returned to all processes that call dbopen() with
the same file name. This file descriptor can be safely used as
an argument to the fcntl(2) and flock(2) locking functions. The
file descriptor is not necessarily associated with any of the
underlying files used by the access method. No file descriptor
is available for in memory databases. The fd routines return -1
on error (setting errno), and the file descriptor on success. A
pointer to a routine that is the interface for keyed retrieval
from the database. The address and length of the data associated
with the specified key are returned in the structure referenced
by data. The get routines return -1 on error (setting errno), 0
on success, and 1 if the key was not in the file. A pointer to
a routine to store key/data pairs in the database.
The parameter option can be set to one of the following values:
Replace the key/data pair referenced by the cursor. The cursor
must have been previously initialized. Append the data immedi‐
ately after the data referenced by key, creating a new key/data
pair. The record number of the appended key/data pair is
returned in the key structure. (Applicable only to the DB_RECNO
access method.) Insert the data immediately before the data
referenced by key, creating a new key/data pair. The record num‐
ber of the inserted key/data pair is returned in the key struc‐
ture. (Applicable only to the DB_RECNO access method.) Enter
the new key/data pair only if the key did not previously exist.
Store the key/data pair, setting or initializing the position of
the cursor to reference it. (Applicable only to the DB_BTREE and
DB_RECNO access methods.)
R_SETCURSOR is available only for the DB_BTREE and DB_RECNO
access methods because it implies that the keys have an inherent
order that does not change.
R_IAFTER and R_IBEFORE are available only for the DB_RECNO
access method because they each imply that the access method is
able to create new keys. This is only true if the keys are
ordered and independent (for example, record numbers).
The default behavior of the put routines is to enter the new
key/data pair, replacing any previously existing key.
The put routines return -1 on error (setting errno), 0 on suc‐
cess, and 1 if the R_NOOVERWRITE option was set and the key
already exists in the file. A pointer to a routine that is the
interface for sequential retrieval from the database. The
address and length of the key are returned in the structure ref‐
erenced by key, and the address and length of the data are
returned in the structure referenced by data.
Sequential key/data pair retrieval can begin at any time, and
the position of the ``cursor'' is not affected by calls to the
del, get, put, or sync routines. Modifications to the database
during a sequential scan will be reflected in the scan, that is,
records inserted behind the cursor will not be returned and
records inserted in front of the cursor will be returned.
The option value must be set to one of the following values: The
data associated with the specified key is returned. This differs
from the get routines in that it sets or initializes the cursor
to the location of the key as well. (Note, for the DB_BTREE
access method, the returned key is not necessarily an exact
match for the specified key. The returned key is the smallest
key greater than or equal to the specified key, permitting par‐
tial key matches and range searches.) The first key/data pair
of the database is returned, and the cursor is set or initial‐
ized to reference it. The last key/data pair of the database is
returned, and the cursor is set or initialized to reference it.
(Applicable only to the DB_BTREE and DB_RECNO access methods.)
Retrieve the key/data pair immediately after the cursor. If the
cursor is not yet set, this is the same as the R_FIRST option.
Retrieve the key/data pair immediately before the cursor. If the
cursor is not yet set, this is the same as the R_LAST option.
(Applicable only to the DB_BTREE and DB_RECNO access methods.)
R_LAST and R_PREV are available only for the DB_BTREE and
DB_RECNO access methods because they each imply that the keys
have an inherent order that does not change.
The seq routines return -1 on error (setting errno), 0 on suc‐
cess, and 1 if there are no key/data pairs less than or greater
than the specified or current key. The seq routines return 2 if
the DB_RECNO access method is being used, the database file is a
character special file, and no complete key/data pairs are cur‐
rently available, A pointer to a routine to flush any cached
information to disk. If the database is in memory only, the sync
routine has no effect and will always succeed.
The option value can be set to the following value: If the
DB_RECNO access method is being used, this option causes the
sync routine to apply to the btree file that underlies the recno
file, not the recno file itself. (See the bfname field of the
recno(3) manual page for more information.)
The sync routines return -1 on error (setting errno) and 0 on
success.
KEY/DATA PAIRS
Access to all file types is based on key/data pairs. Both keys and data
are represented by the following data structure:
typedef struct { void *data; size_t size; } DBT;
The elements of the DBT structure are defined as follows: A pointer to
a byte string. The length of the byte string.
Key and data byte strings can reference strings of essentially unlim‐
ited length, although any two of them must be able to fit into avail‐
able memory at the same time. It should be noted that the access meth‐
ods provide no guarantees about byte string alignment.
RESTRICTIONS
The typedef DBT is a mnemonic for ``data base thing'', which was used
because no one could think of a reasonable name that was not already
used.
The file descriptor interface is a kluge and will be deleted in a
future version of the interface.
None of the access methods provide any form of concurrent access, lock‐
ing, or transactions.
ERRORS
The dbopen() routine may fail and set errno for any of the errors spec‐
ified for the library routines open(2) and malloc(3) or for any of the
following errors: A file is incorrectly formatted. A parameter had
been specified (hash function, pad byte, etc.) that is incompatible
with the current file specification or not meaningful for the function
(for example, use of the cursor without prior initialization), or a
mismatch exists between the version number of the file and the soft‐
ware.
The close routines may fail and set errno for any of the errors speci‐
fied for the library routines close(2), read(2), write(2), free(3), or
fsync(2).
The del, get, put, and seq routines may fail and set errno for any of
the errors specified for the library routines read(2), write(2),
free(3), ormalloc(3).
The fd routines will fail and set errno to ENOENT for in-memory data‐
bases.
The sync routines may fail and set errno for any of the errors speci‐
fied for the library routine fsync(2).
SEE ALSObtree(3), hash(3), mpool(3), recno(3)
LIBTP: Portable, Modular Transactions for UNIX, Margo Seltzer, Michael
Olson, USENIX proceedings, Winter 1992.
dbopen(3)