.\" Copyright (c) 1990, 1993, 1994, 1995
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" @(#)db_open.3 8.15 (Berkeley) 8/1/95
.\"
.TH DB_OPEN 3 "August 1, 1995"
.UC 7
.SH NAME
db_open \- database access methods
.SH SYNOPSIS
.nf
.ft B
#include <db.h>
DB *
db_open(const char *file, int flags, int mode,
.ti +5
DBTYPE type, DBINFO *dbinfo, const void *openinfo);
.ft R
.fi
.SH DESCRIPTION
.so db.so
.GN
the overall structure of the available access methods.
.PP
The currently supported file formats are btree, hashed, log and recno
(i.e. flat-file oriented).
The btree format is a representation of a sorted, balanced tree structure.
The hashed format is an extensible, dynamic hashing scheme.
The log format is a general-purpose logging facility.
The recno format is a byte stream file with fixed or variable length
records.
The formats and other, format specific information are described in detail
in their respective manual pages:
.IR db_btree (3),
.IR db_hash (3),
.IR db_log (3),
and
.IR db_recno (3).
.PP
Db_open opens
.I file
for reading and/or writing.
Files never intended to be preserved on disk may be created by setting
the file parameter to NULL.
(Note, while most of the access methods use
.I file
as the name of an underlying file on disk, this is not guaranteed.
See the manual pages for the individual access methods for more
information.)
.PP
The
.I flags
and
.I mode arguments
are as specified to the
.IR open (2)
function, however, only the O_CREAT, O_EXCL, O_EXLOCK, O_NONBLOCK,
O_RDONLY, O_RDWR, O_SHLOCK and O_TRUNC flags are meaningful.
(Note, opening a database file O_WRONLY is not possible.)
.\"Three additional options may be specified by
.\".IR or 'ing
.\"them into the
.\".I flags
.\"argument.
.\".TP
.\"DB_LOCK
.\"Do the necessary locking in the database to support concurrent access.
.\"If concurrent access isn't needed or the database is read-only this
.\"flag should not be set, as it tends to have an associated performance
.\"penalty.
.\".TP
.\"DB_SHMEM
.\"Place the underlying memory pool used by the database in shared
.\"memory.
.\"Necessary for concurrent access.
.\".TP
.\"DB_TXN
.\"Support transactions in the database.
.\"The DB_LOCK and DB_SHMEM flags must be set as well.
.PP
The
.I type
argument is of type DBTYPE (as defined in the <db.h> include file) and
may be set to DB_BTREE, DB_HASH, DB_LOG or DB_RECNO.
.PP
The
.I dbinfo
argument is a pointer to a structure containing references to locking,
logging, transaction, and shared-memory buffer pool information.
If
.I dbinfo
is NULL, then the access method may still use these subsystems,
but the usage will be private to the application and managed by DB.
If
.I dbinfo
is non-NULL,
then the module referenced by each of the non-NULL fields is used by DB
as necessary.
The fields of the DBINFO structure are defined as follows:
.TP 5
const char *errpfx;
A prefix to prepend to error messages; used only if
.I errfile
is non-NULL.
.TP 5
FILE *errfile;
The
.IR stdio (3)
file stream to which error messages are logged.
.sp
When any error occurs in the
.I db_open
function, or in any function called using a field of the returned DB
structure, an error value is returned by the function,
and the global variable
.I errno
is set appropriately.
In some cases, however, the
.I errno
value may be insufficient to describe the cause of the error.
In these cases, if
.I errfile
is non-NULL, additional error information will be written to the file
stream it represents, preceded by the string, if any, specified by
.IR errpfx .
This error logging facility should not be required for normal operation,
but may be useful in debugging applications.
.TP 5
char *errbuf;
The buffer to which error messages are copied.
If non-NULL,
.I errbuf
behaves as described for
.IR errfile ,
except that the
.I errpfx
field is ignored and the error message is copied into the specified
buffer instead of being written to the FILE stream.
The DB routines assume that the associated buffer is at least 1024 bytes
in length.
.TP 5
LOCK_TABLE_T *lockinfo;
If locking is required for the file being opened (as in the case of
buffers being maintained in a shared memory buffer pool),
the
.I lockinfo
field contains a return value from the function
.I lock_open
that should be used
(see
.IR db_lock (3)).
If
.I lockinfo
is NULL, no locking is done.
.TP 5
DB *loginfo;
If modifications to the file being opened should be logged, the
.I loginfo
field contains a return value from the function
.IR dbopen ,
when opening a DB file of type DB_LOG.
If
.I loginfo
is NULL, no logging is done.
.TP 5
MPOOL *mpoolinfo;
If the cache for the file being opened should be maintained in a shared
buffer pool, the
.I mpoolinfo
field contains a return value from the function
.I mpool_open
that should be used
(see
.IR db_mpool (3)).
If
.I mpoolinfo
is NULL, a memory pool may still be created,
but it will be private to the application and managed by DB.
.TP 5
TXNMGR *txninfo;
If the accesses to the file being opened should take place in the context
of transactions (providing atomicity and complete error recovery), the
.I txninfo
field contains a return value from the function
.I txn_open
(see
.IR db_txn (3)).
If transactions are specified,
the application is responsible for making suitable calls to
.IR txn_begin ,
.IR txn_abort ,
and
.IR txn_commit .
If
.I txninfo
is NULL, no transaction support is done.
.PP
The
.I openinfo
argument is a pointer to an access method specific structure described
in the access method's manual page.
If
.I openinfo
is NULL, each access method will use defaults appropriate for the system
and the access method.
.SH "KEY/DATA PAIRS"
Access to all access methods is based on key/data pairs.
Both keys and data are represented by the following data structure:
.PP
typedef struct {
.RS
void *data;
.br
size_t size;
.RE
} DBT;
.PP
The elements of the DBT structure are defined as follows:
.TP 5
data
A pointer to a byte string.
.ns
.br
.TP 5
size
The length of
.IR data ,
in bytes.
.PP
Key and data byte strings may reference strings of essentially unlimited
length, although any two of them must fit into available memory at the
same time.
.PP
The access methods provide no guarantees about byte string alignment,
and applications are responsible for maintaining any necessary alignment.
.SH "DB OPERATIONS"
.I Db_open
returns a pointer to a DB structure (as defined in the <db.h> include file)
on success, and NULL on error.
The DB structure describes a database type, and includes a set of functions
to perform various actions, as described below.
Each of these functions takes a pointer to a DB structure, and may take
one or more DBT *'s and a flag value as well.
Individual access methods specify additional functions and flags which
are specific to the method.
The fields of the DB structure are as follows:
.TP 5
DBTYPE type;
The type of the underlying access method (and file format).
.TP 5
int (*close)(const DB *db);
A pointer to a function to flush any cached information to disk,
free any allocated resources, and close any underlying files.
Since key/data pairs are cached in memory, failing to sync the
file with the
.I close
or
.I sync
function may result in inconsistent or lost information.
.IP
The
.I close
functions return -1 on failure, setting
.IR errno ,
and 0 on success.
.TP 5
int (*del)(const DB *db, TXN *txnid,
.ti +5
const DBT *key, u_int flags);
.br
A pointer to a function to remove key/data pairs from the database.
The key/data pair associated with the specified
.I key
are discarded from the database.
.IP
The
.I txnid
parameter contains a transaction ID returned from
.IR txn_begin ,
if the file is being accessed under transaction protection,
or NULL if transactions are not in effect.
.IP
The parameter
.I flag
must be set to 0 or exactly one of the following values:
.RS
.TP 5
R_CURSOR
Delete the record referenced by the cursor.
The cursor must have previously been initialized.
.RE
.IP
The
.I delete
functions return -1 on error, setting
.IR errno ,
0 on success, and 1 if the specified
.I key
did not exist in the file.
.TP 5
int (*fd)(const DB *db);
A pointer to a function which returns a file descriptor representative
of the underlying database.
A file descriptor referencing the same file will be returned to all
processes which call
.I db_open
with the same
.I file
name.
This file descriptor may be safely used as an argument to the
.IR fcntl (2)
and
.IR 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.
.IP
The
.I fd
functions return -1 on error, setting
.IR errno ,
and the file descriptor on success.
.TP 5
int (*get)(const DB *db, TXN *txnid,
.ti +5
const DBT *key, DBT *data, u_int flags);
.br
A pointer to a function which is the interface for keyed retrieval from
the database.
The address and length of the data associated with the specified
.I key
are returned in the structure referenced by
.IR data .
.IP
The
.I txnid
parameter contains a transaction ID returned from
.IR txn_begin ,
if the file is being accessed under transaction protection,
or NULL if transactions are not in effect.
.IP
The
.I get
functions return -1 on error, setting
.IR errno ,
0 on success, and 1 if the
.I key
was not found.
.TP 5
int (*put)(const DB *db, TXN *txnid,
.ti +5
DBT *key, const DBT *data, u_int flags);
.br
A pointer to a function to store key/data pairs in the database.
.IP
The
.I txnid
parameter contains a transaction ID returned from
.IR txn_begin ,
if the file is being accessed under transaction protection,
or NULL if transactions are not in effect.
.IP
The parameter
.I flag
must be set to 0 or exactly one of the following values:
.RS
.TP 5
R_CURSOR
Replace the key/data pair referenced by the cursor.
The cursor must have previously been initialized.
.TP 5
R_NOOVERWRITE
Enter the new key/data pair only if the key does not previously exist.
.RE
.IP
The default behavior of the
.I put
functions is to enter the new key/data pair, replacing any previously
existing key.
.IP
The
.I put
functions return -1 on error, setting
.IR errno ,
0 on success, and 1 if the R_NOOVERWRITE
.I flag
was set and the key already exists in the file.
.TP 5
int (*seq)(const DB *db, TXN *txnid,
.ti +5
DBT *key, DBT *data, u_int flags);
.br
A pointer to a function which is the interface for sequential
retrieval from the database.
The address and length of the key are returned in the structure
referenced by
.IR key ,
and the address and length of the data are returned in the
structure referenced
by
.IR data .
.IP
The
.I txnid
parameter contains a transaction ID returned from
.IR txn_begin ,
if the file is being accessed under transaction protection,
or NULL if transactions are not in effect.
.IP
Sequential key/data pair retrieval may begin at any time, and the
logical position of the ``cursor'' is not affected by calls to the
.IR del ,
.IR get ,
.IR put ,
or
.I sync
functions.
Modifications to the database during a sequential scan will be reflected
in the scan, i.e. records inserted behind the cursor will not be returned
while records inserted in front of the cursor will be returned.
.IP
The parameter
.I flag
must be set to 0 or exactly one of the following values:
.RS
.TP 5
R_CURSOR
The data associated with the specified key is returned.
This differs from the
.I get
functions in that it sets or initializes the cursor to the location of
the key as well.
.TP 5
R_FIRST
The first key/data pair of the database is returned, and the cursor
is set or initialized to reference it.
.TP 5
R_NEXT
Retrieve the key/data pair immediately after the cursor.
If the cursor is not yet set, this is the same as the R_FIRST flag.
.RE
.IP
The
.I seq
functions return -1 on error, setting
.IR errno ,
0 on success,
and 1 if there are no key/data pairs less than or greater than the
specified or current key.
.TP 5
int (*sync)(const DB *db, u_int flags);
A pointer to a function to flush any cached information to disk.
If the database is in memory only, the
.I sync
function has no effect and will always succeed.
.IP
The parameter
.I flag
must be set to 0 or a value specified by an access method specific
manual page.
.IP
The
.I sync
functions return -1 on failure, setting
.IR errno ,
and 0 on success.
.SH ERRORS
The
.I db_open
function may fail and set
.I errno
for any of the errors specified for the library functions
.IR open (2),
.IR malloc (3)
or the following:
.TP 5
[EFTYPE]
A file is incorrectly formatted.
.TP 5
[EINVAL]
A parameter has been specified (hash function, recno pad byte etc.)
that is incompatible with the current file specification or, a flag
to a function which is not meaningful for the function (for example,
use of the cursor without prior initialization) or there is a mismatch
between the version number of file and the software.
.PP
The
.I close
functions may fail and set
.I errno
for any of the errors specified for the library functions
.IR close (2),
.IR read (2),
.IR write (2),
.IR free (3),
or
.IR fsync (2).
.PP
The
.IR del ,
.IR get ,
.I put
and
.I seq
functions may fail and set
.I errno
for any of the errors specified for the library functions
.IR read (2),
.IR write (2),
.IR free (3)
or
.IR malloc (3).
.PP
The
.I fd
functions will fail and set
.I errno
to ENOENT for in memory databases.
.PP
The
.I sync
functions may fail and set
.I errno
for any of the errors specified for the library function
.IR fsync (2).
.SH "SEE ALSO"
.IR db_btree (3),
.IR db_hash (3),
.IR db_lock (3),
.IR db_log (3),
.IR db_mpool (3),
.IR db_recno (3),
.IR db_txn (3)
.SH BUGS
The name DBT is a mnemonic for ``data base thang'', and was used
because noone could think of a reasonable name that wasn't already
in use somewhere else.
.PP
The
.I fd
function interface is a kluge,
and will be deleted in a future version of the interface.
.PP
Only big and little endian byte order is supported.