DB_OPEN(3)

NAME
db_open - database access methods

SYNOPSIS
#include <db.h>
DB *
db_open(const char *file, int flags, int mode,
DBTYPE type, DBINFO *dbinfo, const void *openinfo);

DESCRIPTION
the overall structure of the available access methods.

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: db_btree(3), db_hash(3), db_log(3), and db_recno(3).

Db_open opens 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 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.)

The flags and mode arguments are as specified to the 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.)

The 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.

The dbinfo argument is a pointer to a structure containing references to locking, logging, transaction, and shared-memory buffer pool information. If 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 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:

const char *errpfx;
    A prefix to prepend to error messages; used only if errfile is non-NULL.

FILE *errfile;
    The stdio(3) file stream to which error messages are logged.

    When any error occurs in the 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 errno is set appropriately. In some cases, however, the errno value may be insufficient to describe the cause of the error. In these cases, if errfile is non-NULL, additional error information will be written to the file stream it represents, preceded by the string, if any, specified by errpfx. This error logging facility should not be required for normal operation, but may be useful in debugging applications.

char *errbuf;
    The buffer to which error messages are copied. If non-NULL, errbuf behaves as described for errfile, except that the 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.

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 lockinfo field contains a return value from the function lock_open that should be used (see db_lock(3)). If lockinfo is NULL, no locking is done.

DB *loginfo;
    If modifications to the file being opened should be logged, the loginfo field contains a return value from the function dbopen, when opening a DB file of type DB_LOG. If loginfo is NULL, no logging is done.

MPOOL *mpoolinfo;
    If the cache for the file being opened should be maintained in a shared buffer pool, the mpoolinfo field contains a return value from the function mpool_open that should be used (see db_mpool(3)). If mpoolinfo is NULL, a memory pool may still be created, but it will be private to the application and managed by DB.

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 txninfo field contains a return value from the function txn_open (see db_txn(3)). If transactions are specified, the application is responsible for making suitable calls to txn_begin, txn_abort, and txn_commit. If txninfo is NULL, no transaction support is done.

The openinfo argument is a pointer to an access method specific structure 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.

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:

typedef struct {
    void *data;
    size_t size;
} DBT;

The elements of the DBT structure are defined as follows:

data
    A pointer to a byte string.

size
    The length of data, in bytes.

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.

The access methods provide no guarantees about byte string alignment, and applications are responsible for maintaining any necessary alignment.

DB OPERATIONS
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:

DBTYPE type;
    The type of the underlying access method (and file format).

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 close or sync function may result in inconsistent or lost information.

    The close functions return -1 on failure, setting errno, and 0 on success.

int (*del)(const DB *db, TXN *txnid,
    const DBT *key, u_int flags);
    A pointer to a function to remove key/data pairs from the database. The key/data pair associated with the specified key are discarded from the database.

    The txnid parameter contains a transaction ID returned from txn_begin, if the file is being accessed under transaction protection, or NULL if transactions are not in effect.

    The parameter flag must be set to 0 or exactly one of the following values:

    R_CURSOR
        Delete the record referenced by the cursor. The cursor must have previously been initialized.

    The delete functions return -1 on error, setting errno, 0 on success, and 1 if the specified key did not exist in the file.

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 db_open with the same file name. This file descriptor may 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 functions return -1 on error, setting errno, and the file descriptor on success.

int (*get)(const DB *db, TXN *txnid,
    const DBT *key, DBT *data, u_int flags);
    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 key are returned in the structure referenced by data.

    The txnid parameter contains a transaction ID returned from txn_begin, if the file is being accessed under transaction protection, or NULL if transactions are not in effect.

    The get functions return -1 on error, setting errno, 0 on success, and 1 if the key was not found.

int (*put)(const DB *db, TXN *txnid,
    DBT *key, const DBT *data, u_int flags);
    A pointer to a function to store key/data pairs in the database.

    The txnid parameter contains a transaction ID returned from txn_begin, if the file is being accessed under transaction protection, or NULL if transactions are not in effect.

    The parameter flag must be set to 0 or exactly one of the following values:

    R_CURSOR
        Replace the key/data pair referenced by the cursor. The cursor must have previously been initialized.

    R_NOOVERWRITE
        Enter the new key/data pair only if the key does not previously exist.

    The default behavior of the put functions is to enter the new key/data pair, replacing any previously existing key.

    The put functions return -1 on error, setting errno, 0 on success, and 1 if the R_NOOVERWRITE flag was set and the key already exists in the file.

int (*seq)(const DB *db, TXN *txnid,
    DBT *key, DBT *data, u_int flags);
    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 key, and the address and length of the data are returned in the structure referenced by data.

    The txnid parameter contains a transaction ID returned from txn_begin, if the file is being accessed under transaction protection, or NULL if transactions are not in effect.

    Sequential key/data pair retrieval may begin at any time, and the logical position of the ``cursor'' is not affected by calls to the del, get, put, or 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.

    The parameter flag must be set to 0 or exactly one of the following values:

    R_CURSOR
        The data associated with the specified key is returned. This differs from the get functions in that it sets or initializes the cursor to the location of the key as well.

    R_FIRST
        The first key/data pair of the database is returned, and the cursor is set or initialized to reference it.

    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.

    The seq functions return -1 on error, setting errno, 0 on success, and 1 if there are no key/data pairs less than or greater than the specified or current key.

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 sync function has no effect and will always succeed.

    The parameter flag must be set to 0 or a value specified by an access method specific manual page.

    The sync functions return -1 on failure, setting errno, and 0 on success.

ERRORS
The db_open function may fail and set errno for any of the errors specified for the library functions open(2), malloc(3) or the following:

[EFTYPE]
    A file is incorrectly formatted.

[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.

The close functions may fail and set errno for any of the errors specified for the library functions close(2), read(2), write(2), free(3), or fsync(2).

The del, get, put and seq functions may fail and set errno for any of the errors specified for the library functions read(2), write(2), free(3) or malloc(3).

The fd functions will fail and set errno to ENOENT for in memory databases.

The sync functions may fail and set errno for any of the errors specified for the library function fsync(2).

SEE ALSO
db_btree(3), db_hash(3), db_lock(3), db_log(3), db_mpool(3), db_recno(3), db_txn(3)

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.

The fd function interface is a kluge, and will be deleted in a future version of the interface.

Only big and little endian byte order is supported.