#include <db_cxx.h>

int
Db::open(const char *file,
    const char *database, DBTYPE type, u_int32_t flags, int mode);

Description

The currently supported Berkeley DB file formats (or access methods) are Btree, Hash, Queue and Recno. The Btree format is a representation of a sorted, balanced tree structure. The Hash format is an extensible, dynamic hashing scheme. The Queue format supports fast access to fixed-length records accessed by sequentially or logical record number. The Recno format supports fixed- or variable-length records, accessed sequentially or by logical record number, and optionally retrieved from a flat text file.

Storage and retrieval for the Berkeley DB access methods are based on key/data pairs, see Dbt for more information.

The Db::open interface opens the database represented by the file and database arguments for both reading and writing. The file argument is used as the name of a physical file on disk that will be used to back the database. The database argument is optional and allows applications to have multiple logical databases in a single physical file. While no database argument needs to be specified, it is an error to attempt to open a second database in a file that was not initially created using a database name. In-memory databases never intended to be preserved on disk may be created by setting both the file and database arguments to NULL. Note that in-memory databases can only ever be shared by sharing the single database handle that created them, in circumstances where doing so is safe.

The type argument is of type DBTYPE and must be set to one of DB_BTREE, DB_HASH, DB_QUEUE, DB_RECNO or DB_UNKNOWN, except that databases of type DB_QUEUE are restricted to one per file. If type is DB_UNKNOWN, the database must already exist and Db::open will automatically determine its type. The Db::get_type method may be used to determine the underlying type of databases opened using DB_UNKNOWN.

The flags and mode arguments specify how files will be opened and/or created if they do not already exist.

The flags value must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values.

DB_CREATE

Create any underlying files, as necessary. If the files do not already exist and the DB_CREATE flag is not specified, the call will fail.

DB_EXCL

Return an error if the file already exists. Underlying filesystem primitives are used to implement this flag. For this reason it is only applicable to the physical file and cannot be used to test if a database in a file already exists.

The DB_EXCL flag is only meaningful when specified with the DB_CREATE flag.

DB_NOMMAP

Do not map this database into process memory (see the description of the DbEnv::set_mp_mmapsize method for further information).

DB_RDONLY

Open the database for reading only. Any attempt to modify items in the database will fail regardless of the actual permissions of any underlying files.

DB_THREAD

Cause the Db handle returned by Db::open to be free-threaded, that is, useable by multiple threads within a single address space.

DB_TRUNCATE

Physically truncate the underlying file, discarding all previous databases it might have held. Underlying filesystem primitives are used to implement this flag. For this reason it is only applicable to the physical file and cannot be used to discard databases within a file.

The DB_TRUNCATE flag cannot be transaction protected, and it is an error to specify it in a transaction protected environment.

On UNIX systems, or in IEEE/ANSI Std 1003.1 (POSIX) environments, all files created by the access methods are created with mode mode (as described in chmod(2)) and modified by the process' umask value at the time of creation (see umask(2)). The group ownership of created files is based on the system and directory defaults, and is not further specified by Berkeley DB. If mode is 0, files are created readable and writeable by both owner and group. On Windows systems, the mode argument is ignored.

Calling Db::open is a reasonably expensive operation, and maintaining a set of open databases will normally be preferable to repeatedly open and closing the database for each new query.

The Db::open method either returns a non-zero error value or throws an exception that encapsulates a non-zero error value on failure, and returns 0 on success.

Environment Variables

DB_HOME

If the dbenv argument to db_create was initialized using DbEnv::open the environment variable DB_HOME may be used as the path of the database environment home. Specifically, Db::open is affected by the configuration value DB_DATA_DIR.

TMPDIR

If the file and dbenv arguments to Db::open are NULL, the environment variable TMPDIR may be used as a directory in which to create a temporary backing file.

Errors

The Db::open method may fail and throw an exception or return a non-zero error for the following conditions:

DB_OLD_VERSION

The database cannot be opened without being first upgraded.

EEXIST

DB_CREATE and DB_EXCL were specified and the file exists.

EINVAL

An invalid flag value or parameter was specified (e.g., unknown database type, page size, hash function, pad byte, byte order) or a flag value or parameter that is incompatible with the specified database.

The DB_THREAD flag was specified and spinlocks are not implemented for this architecture.

The DB_THREAD flag was specified to Db::open, but was not specified to the DbEnv::open call for the environment in which the Db handle was created.

A re_source file was specified with either the DB_THREAD flag or the provided database environment supports transaction processing.

ENOENT

A non-existent re_source file was specified.

The Db::open method may fail and throw an exception or return a non-zero error for errors specified for other Berkeley DB and C library or system methods. If a catastrophic error has occurred, the Db::open method may fail and either return DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY, in which case all subsequent Berkeley DB calls will fail in the same way.

Class

See Also