int DB->open(DB *db, DB_TXN *txnid, const char *file, const char *database, DBTYPE type, u_int32_t flags, int mode);
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 sequentially or by logical record number. The Recno format supports fixed- or variable-length records, accessed sequentially or by logical record number, and optionally backed by 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 an underlying file that will be used to back the database. The database argument is optional, and allows applications to have multiple databases in a single file. Although 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. Further, the database argument is not supported by the Queue format. Finally, when opening multiple databases in the same physical file, it is important to consider locking and memory cache issues; see Opening multiple databases in a single file for more information.
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. 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.
If the operation is to be transaction-protected (other than by specifying the DB_AUTO_COMMIT flag), the txnid parameter is a transaction handle returned from DB_ENV->txn_begin; otherwise, NULL.
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:
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 database open 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)). If mode is 0, the database open will use a default mode of readable and writable by both owner and group. On Windows systems, the mode argument is ignored. The group ownership of created files is based on the system and directory defaults, and is not further specified by Berkeley DB.
Calling DB->open is a reasonably expensive operation, and maintaining a set of open databases will normally be preferable to repeatedly opening and closing the database for each new query.
The DB->open method returns a non-zero error value on failure and 0 on success. If DB->open fails, the DB->close method should be called to discard the DB handle.
DB->open is affected by any database directory specified using the DB_ENV->set_data_dir method, or by setting the "set_data_dir" string in the environment's DB_CONFIG file.
The DB->open method may fail and return a non-zero error for the following conditions:
The DB_THREAD flag was specified and fast mutexes are not available for this architecture.
The DB_THREAD flag was specified to DB->open, but was not specified to the DB_ENV->open call for the environment in which the DB handle was created.
A backing flat text file was specified with either the DB_THREAD flag or the provided database environment supports transaction processing.
The DB->open method may fail and return a non-zero error for errors specified for other Berkeley DB and C library or system functions. If a catastrophic error has occurred, the DB->open method may fail and return DB_RUNRECOVERY, in which case all subsequent Berkeley DB calls will fail in the same way.
Copyright Sleepycat Software