*I$Berkeley DB: Db::open[P

Db::open





#include <db_cxx.h>

static int9Db::open(const char *fname, DBTYPE type, u_int32_t flags,4 int mode, DbEnv *dbenv, DbInfo *dbinfo, Db **dbpp);





Description



7The 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.)

WThe 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.

DThe Btree access method is a sorted, balanced tree structure storingassociated key/data pairs.ESearches, insertions, and deletions in the btree will all complete in@O (lg base N) where base is the average number of keys per page.COften, inserting ordered data into btrees results in pages that are half-full.JThis implementation has been modified to make ordered (or inverse ordered)Linsertion the best case, resulting in nearly perfect page space utilization.

KSpace freed by deleting key/data pairs from the database is never reclaimed:from the filesystem, although it is reused where possible.9This means that the btree storage structure is grow-only.DIf sufficiently many keys are deleted from a tree that shrinking theBunderlying database file is desirable, this can be accomplished by4creating a new tree from a scan of the existing one.

@The Hash access method is an extensible, dynamic hashing scheme.

FThe Recno access method provides support for fixed and variable length=records, optionally backed by a flat text (byte stream) file.DBoth fixed and variable length records are accessed by their logicalrecord number.

CIt is valid to create a record whose record number is more than one7greater than the last record currently in the database.BFor example, the creation of record number 8, when records 6 and 7"do not yet exist, is not an error.EHowever, any attempt to retrieve such records (e.g., records 6 and 7)will return DB_KEYEMPTY.

BDeleting a record will not, by default, renumber records followingCthe deleted record (see the DB_RENUMBER flag for more information).@Any attempt to retrieve deleted records will return DB_KEYEMPTY.

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 DbMpool::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.R

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 necessaryDto provide the access methods with database environment information.fSee DbEnv for a description of the dbenv argument.

EAdditionally, there is access method specific information that may be specified when calling Db::open.jSee DbInfo for a description of the db_info argument.

The Db::open methodmcopies a pointer to a Db object into the memory location referencedby dbpp.IThe methods of this object allow you to perform various database actions.8The methods are described in the following manual pages:4Db::close,6Db::cursor,0Db::del,.Db::fd,0Db::get,:Db::get_type,/Db::putand2Db::sync.

Environment Variables





DB_HOME
>If the dbenv argument to Db::open was initialized usingiDbEnv::appinit the environment variable DB_HOME mayBbe 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.




Errors

OIf a fatal error occurs in Berkeley DB, the Db::open method may fail and eitherIreturn DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY,Gat which point all subsequent database calls will also fail in the sameFway. Methods marked as returning errno will, by default, throwHan exception that encapsulates the error information. The default error\behavior can be changed, see DbException.

The Db::open&method may fail and throw an exceptionKfor any of the errors specified for the following Berkeley DB and C library functions:6Db::cursor,2Db::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),>DbLockTab::get,<DbLockTab::id,8DbLock::put,>DbLockTab::vec,>DbLog::compare,:DbLog::flush,6DbLog::put,FDbLog::db_register,JDbLog::db_unregister, lseek(3), malloc(3), memcmp(3), memcpy(3), memmove(3),>DbMpool::close,FDbMpoolFile::close,BDbMpoolFile::get,DDbMpoolFile::open,BDbMpoolFile::put,BDbMpoolFile::set,DDbMpoolFile::sync,<DbMpool::open,JDbMpool::db_register, memset(3),mmap(3), munmap(3),open(3), pread(3),&pstat_getdynamic(3), pwrite(3),read(3), realloc(3),Esigfillset(3),sigprocmask(3),dstat(3), strerror(3), strlen(3), sysconf(3),rtime(3), unlink(3), vfprintf(3), vsnprintf(3),nandt write(3).h

aIn addition, the Db::openl&method may fail and throw an exceptionor return errnofor the following conditions:y

r

(

EAGAIN
A lock was unavailable.
l

t

Y

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

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

eEThere is a mismatch between the version number of file and thee software.U

NIA re_source file was specified with either the DB_THREAD flag or aiAnon-NULL tx_info field in the DB_ENV argument to Db::open.mD

ENOENT
A non-existent re_source file was specified.
.

r

Class

,Db



See Also

4Db::close,6Db::cursor,0Db::del,.Db::fd,0Db::get,HDb::get_byteswapped,:Db::get_type,2Db::join, Db::open,r0Db::put,1Db::statnandi2Db::sync.
a ÿÿom a scan of the existing one.

@The Hash access method is an extensible, dynamic hashing scheme.

FThe Recno access method provides support f