int db_open(const char *file, DBTYPE type, u_int32_t flags, int mode, DB_ENV *dbenv, DB_INFO *dbinfo, DB **dbpp);
The currently supported Berkeley DB file formats (or access methods) are B+tree, Extended Linear Hashing, and Fixed and Variable-length records. Generally, these are referred to as the btree, hash and recno access methods. The btree format is a representation of a sorted, balanced tree structure. The hashed format is an extensible, dynamic hashing scheme. The recno format supports fixed or variable length records (optionally retrieved from a flat text file).
Storage and retrieval for the Berkeley DB access methods are based on key/data pairs, or DBT structures.
The db_open function opens the database represented by file for both reading and writing. Files never intended to be shared or 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. Also, calling db_open is a reasonably expensive operation. (This is based on a model where the DBMS keeps a set of files open for a long time rather than opening and closing them on each query.)
The type argument is of type DBTYPE, and must be set to one of DB_BTREE, DB_HASH, DB_RECNO or DB_UNKNOWN. If type is DB_UNKNOWN, the database must already exist and db_open will then determine if it is of type DB_BTREE, DB_HASH or DB_RECNO.
The flags and mode arguments specify how files will be opened and/or created if they do not already exist. The flags value is specified by logically OR'ing together one or more of the following values:
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.
When sharing a database environment with other processes, it is necessary to provide the access methods with database environment information. The db_env argument to db_open is intended for this purpose.
Additionally, there is access method specific information that may be specified when calling db_open. The db_info argument to db_open is intended for this purpose.
Before returning, the db_open function copies a pointer to a DB structure, into the memory location referenced by dbpp. This structure describes a database type and includes a set of functions to perform various database actions. Each of these functions takes a pointer to a DB structure, and may take a pointer to one or more DBT structures and a flag value as well. The set of functions are described in the following manual pages: DB->close, DB->cursor, DB->del, DB->fd, DB->get, DB->put and DB->sync.
In addition, the returned DB structure includes the following fields:
The db_open function returns the value of errno on failure, and 0 on success.
The db_open function may fail and return errno for any of the errors specified for the following Berkeley DB and C library functions: DB->cursor, DB->sync, DBcursor->c_close(3), DBmemp->pgin(3), DBmemp->pgout(3), __account_page(3), abort(3), close(3), dbenv->db_paniccall(3), dbp->h_hash(3), fcntl(3), fflush(3), fprintf(3), free(3), fstat(3), fsync(3), func(3), getenv(3), getpid(3), getuid(3), isdigit(3), lock_get, lock_id, lock_put, lock_vec, log_compare, log_flush, log_put, log_register, log_unregister, lseek(3), malloc(3), memcmp(3), memcpy(3), memmove(3), memp_close, memp_fclose, memp_fget, memp_fopen, memp_fput, memp_fset, memp_fsync, memp_open, memp_register, memset(3), mmap(3), munmap(3), open(3), pread(3), pstat_getdynamic(3), pwrite(3), read(3), realloc(3), sigfillset(3), sigprocmask(3), stat(3), strerror(3), strlen(3), sysconf(3), time(3), unlink(3), vfprintf(3), vsnprintf(3), and write(3).
In addition, the db_open function may fail and return errno for the following conditions:
The DB_THREAD flag was specified and spinlocks are not implemented for this architecture.
There is a mismatch between the version number of file and the software.
A re_source file was specified with either the DB_THREAD flag or a non-NULL tx_info field in the DB_ENV argument to db_open.