Db::open

APIRef

#include <db_cxx.h>

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

Description

The currently supported Berkeley DB file formats (or access methods) are B+tree, 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 name for both reading and writing. The argument name is used as the name of a single physical file on disk that will be used to back the database.

Files never intended to be shared or preserved on disk may be created by setting the name parameter to NULL.

The subname argument allows applications to have subdatabases, i.e., multiple databases inside of a single physical file. This is useful when the logical databases are both numerous and reasonably small, in order to avoid creating a large number of underlying files. It is an error to attempt to open a subdatabase in a database file that was not initially created using a subdatabase name. See the Opening a database section of the Reference Guide for more information.

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. 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 database already exists. Underlying filesystem primitives are used to implement this flag. For this reason it is only applicable to the physical database file and cannot be used to test if a subdatabase 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.

If the Db handle is opened within a threaded environment, it is not necessary to specify the DB_THREAD flag, the Db handle will always be free-threaded. For this reason, Db handles opened in threaded environments must be treated as if they are free-threaded (e.g., DB_DBT_MALLOC, DB_DBT_REALLOC or DB_DBT_USERMEM must be specified in Dbts used to retrieve key/data items), regardless of whether DB_THREAD was specified to Db::open.

DB_TRUNCATE
Physically truncate the underlying database file, discarding all previous subdatabases or databases. Underlying filesystem primitives are used to implement this flag. For this reason it is only applicable to the physical database file and cannot be used to discard subdatabases.

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 home for the interpretation of the dir. Specifically, Db::open is affected by the configuration string value of DB_DATA_DIR.

TMPDIR
If the name 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

If a fatal error occurs in Berkeley DB, the Db::open method will fail and either return DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY, at which point all subsequent database calls will fail in the same way.

In addition, 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 name database.

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

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.

In addition, 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.

Class

Db

See Also

Db::close, Db::cursor, Db::del, Db::err, Db::fd, Db::get, Db::get_byteswapped, Db::get_type, Db::join, Db::open, Db::put, Db::remove, Db::set_bt_compare, Db::set_bt_minkey, Db::set_bt_prefix, Db::set_cachesize, Db::set_dup_compare, Db::set_errcall, Db::set_errfile, Db::set_errpfx, Db::set_flags, Db::set_h_ffactor, Db::set_h_hash, Db::set_h_nelem, Db::set_lorder, Db::set_malloc, Db::set_pagesize, Db::set_paniccall, Db::set_realloc, Db::set_re_delim, Db::set_re_len, Db::set_re_pad, Db::set_re_source, Db::stat, Db::sync and Db::upgrade.

APIRef

Copyright Sleepycat Software