,I#Berkeley DB: db_open[P

db_open





#include <db.h>

int7db_open(const char *file, DBTYPE type, u_int32_t flags,9 int mode, DB_ENV *dbenv, DB_INFO *dbinfo, DB **dbpp);





Description



KThe currently supported Berkeley DB file formats (or access methods)Kare B+tree, Extended Linear Hashing, and Fixed and Variable-length records.AGenerally, these are referred to as the btree, hash and recno access methods.JThe btree format is a representation of a sorted, balanced tree structure.;The hashed format is an extensible, dynamic hashing scheme.FThe recno format supports fixed or variable length records (optionally!retrieved from a flat text file).

NStorage and retrieval for the Berkeley DB access methods are based on key/data@pairs, or DBT structures.

6The db_open function opens the database represented by)file for both reading and writing.HFiles never intended to be shared or preserved on disk may be created by#setting the file parameter to NULL.

HNote, while most of the access methods use file as the name of an0underlying file on disk, this is not guaranteed.:Also, calling db_open is a reasonably expensive operation.H(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.)

EThe type argument is of type DBTYPE, and must be set to one ofIDB_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.

KThe flags and mode arguments specify how files will be opened,and/or created if they do not already exist.SThe flags value is specified by logically OR'ing together one or more of thefollowing values:

[

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

DB_NOMMAP
Do not map this file (see memp_open for further information).7

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

DB_THREAD
Cause the m4_reg(DB) handle returned by db_open to be useable>by multiple threads within a single address space, i.e., to befree-threaded.Z

DB_TRUNCATE
Logically truncate the database if it exists, i.e., behave as if the=database were just created, discarding any previous contents.


WAll files created by the access methods are created with mode mode (as describedHin chmod(2)) and modified by the process' umask value at the time$of creation (see umask(2)))).IThe group ownership of created files is based on the system and directory6defaults, and is not further specified by Berkeley DB.

IWhen sharing a database environment with other processes, it is necessaryIto provide the access methods with database environment information. TheCdb_env argument to db_openis intended for this purpose.

EAdditionally, there is access method specific information that may be$specified when calling db_open. TheFdb_info argument to db_openis intended for this purpose.

?Before returning, the db_open function copies a pointer to a DB>structure, into the memory location referenced by dbpp.HThis structure describes a database type and includes a set of functions$to perform various database actions.GEach of these functions takes a pointer to a DB structure, and may takeAa pointer to one or more DBT structures and a flag value as well.AThe set of functions are described in the following manual pages:2DB->close,4DB->cursor,.DB->del,,DB->fd,.DB->get,-DB->putand0DB->sync.

=In addition, the returned DB structure includes the followingfields:

R

DBTYPE type;
The type of the underlying access method (and file format).,Set to one of DB_BTREE, DB_HASH or DB_RECNO.KThis field may be used to determine the type of the database after a return=from db_open with the type argument set to DB_UNKNOWN.d

int byteswapped;
Set to 0 if the underlying database files were created on an architectureHof the same byte order as the current one, and 1 if they were not (i.e.,5big-endian on a little-endian machine or vice-versa).CThis field may be used to determine if application data needs to be&adjusted for this architecture or not.


The db_openHfunction returns the value of errno on failure, and 0 on success.

Environment Variables





DB_HOME
=If the dbenv argument to db_open was initialized usingcdb_appinit the environment variable DB_HOME mayBbe used as the path of the database home for the interpretation of9the dir. Specifically, db_open is affected by the*configuration string value of DB_DATA_DIR.




Errors

PIf a fatal error occurs in Berkeley DB, the db_open function may fail and returnFDB_RUNRECOVERY, at which point all subsequent database calls will alsoreturn DB_RUNRECOVERY.

The db_open)function may fail and return errnoKfor any of the errors specified for the following Berkeley DB and C library functions:4DB->cursor,0DB->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),6lock_get,4lock_id,3lock_put,6lock_vec,9log_compare,5log_flush,1log_put,>log_register,Blog_unregister, lseek(3), malloc(3), memcmp(3), memcpy(3), memmove(3),8memp_close,=memp_fclose,9memp_fget,;memp_fopen,9memp_fput,9memp_fset,;memp_fsync,6memp_open,Amemp_register, memset(3),mmap(3), munmap(3),open(3), pread(3),0pstat_getdynamic(3), pwrite(3),read(3), realloc(3),esigfillset(3),sigprocmask(3),rstat(3), strerror(3), strlen(3), sysconf(3),time(3), unlink(3), vfprintf(3), vsnprintf(3),eandt write(3).t

kIn addition, the db_open)function may fail and return errnoefor the following conditions:a

o

(

EAGAIN
A lock was unavailable.
a

s

Y

EINVAL
An invalid flag value or parameter was specified (e.g., unknown databaseaKtype, page size, hash function, recno pad byte, byte order) or a flag valuehMor parameter that is incompatible with the current file specification.*

oFThe DB_THREAD flag was specified and spinlocks are not implemented forthis architecture.

iEThere is a mismatch between the version number of file and theh software.x

dIA re_source file was specified with either the DB_THREAD flag or ae@non-NULL tx_info field in the DB_ENV argument to db_open.D

ENOENT
A non-existent re_source file was specified.
r

s

See Also

a8db_appexit,8db_appinit,8db_version,2DB->close,4DB->cursor,.DB->del,,DB->fd,.DB->get,0DB->join,db_open,.DB->put,0DB->stat,0DB->sync,;DBcursor->c_close,T7DBcursor->c_del,e6DBcursor->c_getando7DBcursor->c_put. 
boÿÿ ofIDB_BTREE, DB_HASH, DB_