/I*Berkeley DB: DbEnv::appinit[P

DbEnv::appinit





#include <db_cxx.h>

'int DbEnv::appinit(const char *db_home,- char *const *db_config, u_int32_t flags);





Description



KThe DbEnv::appinit method provides a simple way to initialize and configureKthe Berkeley DB environment. It is not necessary that it be called, but itHprovides a structure for creating a consistent environment for processes1using one or more of the features of Berkeley DB.

CThe db_home and db_config arguments to DbEnv::appinitQare described in Berkeley DB File Naming.

GThe flags argument specifies the subsystems that are initializedLand how the environment affects Berkeley DB file naming, among other things.ZThe flags value is specified by logically OR'ing together one or more of thefollowing values:

R

DB_CREATE
Cause subsystems to create any underlying files, as necessary.ƒ

DB_INIT_CDB
Initialize locking for the Berkeley DB Concurrent Access Methods product. In this mode, Berkeley DB providesAmultiple reader/single writer access. No other locking should be{specified (e.g., do not set DB_INIT_LOCK). Access method callszare largely unchanged when using the DB_INIT_CDB flag, althougheany cursors through which update operations (e.g., Dbc::put,’Dbc::del) will be made, must have the DB_RMW value set inDthe flags parameter to the cursor call that creates the cursor. SeeKDb::cursor for more information.9

DB_INIT_LOCK
Initialize the lock subsystem; see5DbLock.JThis subsystem should be used when multiple processes or threads are goingOto be reading and writing a Berkeley DB database, so that they do not interfereIwith each other. If all threads are accessing the database(s) read-only,Ithen locking is unnecessary. When the DB_INIT_LOCK flag is specified, it@is usually necessary to run the deadlock detector, as well. See–db_deadlock and DbLockTab::detect for more information.7

DB_INIT_LOG
Initialize the log subsystem; see3DbLog.GThis subsystem is used when recovery from application or system failureis necessary.];

DB_INIT_MPOOL
Initialize the mpool subsystem; see7DbMpool.OThis subsystem is used whenever the application is using the Berkeley DB accessmethods for any purpose.]?

DB_INIT_TXN
Initialize the transaction subsystem; see3DbTxn.IThis subsystem is used when atomicity of multiple operations and recoveryBare important. The DB_INIT_TXN flag implies the DB_INIT_LOG flag.<

DB_MPOOL_PRIVATE
Create a private memory pool; see7DbMpool./Ignored unless DB_INIT_MPOOL is also specified.Q

DB_NOMMAP
Do not memory map database files within this environment; see7DbMpool./Ignored unless DB_INIT_MPOOL is also specified.^

DB_RECOVER
Run normal recovery on this environment before opening it for normal use.JIf this flag is set, the DB_CREATE flag must also be set since the regionswill be removed and recreated.

AThe DbEnv::appinit function returns successfully if DB_RECOVER isBspecified and no log files exist, so it is necessary to ensure all8necessary log files are present before running recovery.“For further information, consult db_archive and db_recover.^

DB_RECOVER_FATAL
Run catastrophic recovery on this environment before opening it forEnormal use. If this flag is set, the DB_CREATE flag must also be set0since the regions will be removed and recreated.

DThe DbEnv::appinit function returns successfully if DB_RECOVER_FATALEis specified and no log files exist, so it is necessary to ensure allEnecessary log files are present before running recovery. For further‡information, consult db_archive and db_recover.f

DB_THREAD
Ensure that handles returned by the Berkeley DB subsystems are useable by multiple9threads within a single process, i.e., that the system isfree-threaded.V

DB_TXN_NOSYNC
On transaction commit, do not synchronously flush the log; see3DbTxn.-Ignored unless DB_INIT_TXN is also specified.h

DB_USE_ENVIRON
The Berkeley DB process' environment may be permitted to specify information toNbe used when naming files; see Berkeley DBIFile Naming. As permitting users to specify which files are used canFcreate security problems, environment information will be used in file<naming for all users only if the DB_USE_ENVIRON flag is set.j

DB_USE_ENVIRON_ROOT
The Berkeley DB process' environment may be permitted to specify informationQto be used when naming files; see Berkeley DBIFile Naming. As permitting users to specify which files are used canAcreate security problems, if the DB_USE_ENVIRON_ROOT flag is set,Henvironment information will be used for file naming only for users withFa user-ID matching that of the superuser (specifically, users for whom8the getuid(2) system call returns the user-ID 0).


)The Berkeley DB environment is configuredEbased on the dbenv argument. It is expected that applicationsiwill use a single DbEnv object as the argument to all of thessubsystems in the Berkeley DB package. The fields of the DbEnv object+used by DbEnv::appinit are described below.pReferences to the DbEnv object are maintained by Berkeley DB, so itDis necessary that the object and memory it references be valid untilthe object is destroyed.mAny of the DbEnv fields that are not explicitly set will defaultto appropriate values.

oThe following fields in the DbEnv object may be initialized, using:the appropriate set method, before calling DbEnv::appinit:



void (*db_paniccall)(DbEnv *dbenv, int errno);
Errors can occur in the Berkeley DB library where the only solution is to shutNdown the application and run recovery. (For example, if Berkeley DB is unableGto write log records to disk because there is insufficient disk space.)IIn these cases, the value DB_RUNRECOVERY is returned by the function. It1His often simpler, however, to simply shut down the application when suchGerrors occur instead of attempting to gracefully return error values up: the stack.

DIf db_paniccall is non-NULL and such an error occurs, it will@called. The dbenv argument is a reference to the currentEenvironment, and the errval argument is the system errno valuen*that was returned when the error occurred.>†

void (*db_errcall)(char *db_errpfx, char *buffer);
When an error occurs in the Berkeley DB library, an errno value isAreturned by the method. In some cases, however, the errnoGvalue may be insufficient to completely describe the cause of the errorv0especially during initial application debugging.

kHIf db_errcall is non-NULL, it may be called with additional errorHinformation. The db_errpfx argument is the current environment's>db_errpfx field. The buffer argument contains a6nul-terminated string with the additional information.

rFThis error logging facility does not slow performance or significantlyDincrease application size, and may be run during normal operation aswell as during debugging.  <except that the error message is written to the OutputStream#represented by error_stream.RO

ostream* error_stream;
The error_stream functions like the error fileDn

const char *db_errpfx;
A prefix to prepend to error messages. Because Berkeley DB does not copy theHmemory referenced by the db_errpfx field, applications may modify%the error message prefix at any time.ii`

int db_verbose;
Include informational and debugging messages as well as error messages6in the db_errcall and db_errfile output.
m

7Each of the open functions that DbEnv::appinit may call.º(DbLockTab::open, DbLog::open, DbMpool::open andiDbTxnMgr::open), is called as follows, where the DB_CREATE_flag is optional:uB



GThis call will cause each subsystem to construct pathnames as describedrRin Berkeley DB File Naming. The subsystemChas permission to read and write underlying files as necessary, andhHoptionally to create files. (All created files will be created readableIand writeable by the owner and the group. The group ownership of createdfGfiles is based on the system and directory defaults, and is not further-specified by Berkeley DB.)

rFIn addition, the dbenv argument is passed to the open functionsEof any subsystems initialized by DbEnv::appinit. For this reason theehfields of the DbEnv object relevant to the subsystems beingCinitialized must themselves be initialized before DbEnv::appinit isaHcalled. See the appropriate subsystem documentation for a list of thesefields and their uses.

sFThe return value from each of these calls is placed in the appropriateGfield of the DbEnv object:y

x
DbLockTab *lk_info;
The return value of the DbLockTab::open call.l
DbLog *lg_info;
The return value of the DbLog::open call.r
DbMpool *mp_info;
The return value of the DbMpool::open call.u
DbTxnMgr *tx_info;
The return value of the DbTxnMgr::open call.a
.

aJIn general, these fields are not directly used by applications; subsystemswof Berkeley DB that use these fields simply reference them using the DbEnvobject passed to the subsystem.a

m For example,Man application using the Berkeley DB hash access method functions to access apŒdatabase will first call Db::open passing it the DbEnvCargument initialized by a call to DbEnv::appinit. Then, all future @calls to the hash access method functions for that database willCautomatically use the underlying shared memory buffer pool that wasehspecified by the mp_info field of that DbEnv object.

bDThe single exception to this rule is the tx_info field, whichlapplications must explicitly specify to the DbTxnMgr::begin,–DbTxnMgr::checkpoint and DbTxnMgr::close methods.

.eThe error_model field of DbEnv allows the user toiNconfigure the way errors are treated in Berkeley DB, and may be changed at anyEtime, including after the call to DbEnv::appinit. The error model is.Tfurther described in DbException.

cmThe db_prefix field of DbEnv allows the user to configuresIthe error message prefix, and may be changed at any time, including afterythe call to DbEnv::appinit.>

aMOtherwise, once the Berkeley DB environment has been initialized by a call toy-DbEnv::appinit, no fields should be modified.a

x

Architecture Notes

IDue to the constraints of the PA-RISC memory architecture, HP-UX does notDallow a process to map a file into its address space multiple times.JFor this reason, each Berkeley DB environment may be opened only once by a@process on HP-UX, i.e., calls to DbEnv::appinit will fail if theNspecified Berkeley DB environment has been opened and not subsequently closed.

mGOn Windows/95, files that are opened by multiple processes do not share_Ldata correctly. To cause Berkeley DB to use the paging file to share memorywamong processes, use the DB_REGION_NAME flag of the udb_value_set function. Obviously, you do not need to do this if 7only a single process will be accessing database files.T

The DbEnv::appinit>method either returns errno or throws an exception that:encapsulates an errno on failure, and 0 on success.



Errors

iUIf a fatal error occurs in Berkeley DB, the DbEnv::appinit method may fail and either Ireturn DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY,pGat which point all subsequent database calls will also fail in the sameEFway. Methods marked as returning errno will, by default, throwHan exception that encapsulates the error information. The default error\behavior can be changed, see DbException.

iThe DbEnv::appinit&method may fail and throw an exceptionKfor any of the errors specified for the following Berkeley DB and C libraryl functions:4Db::close, abort(3),l ctime(3),b>DbEnv::appexit,dbenv->tx_recover(3), fclose(3), fcntl(3), fflush(3), fgets(3),c fopen(3),a fprintf(3),vfree(3), getenv(3), getpid(3), getuid(3), isspace(3), @DbLockTab::open,DDbLockTab::unlink,>DbLog::compare,6DbLog::get,8DbLog::open,<DbLog::unlink, malloc(3), memcpy(3),<DbMpool::open,@DbMpool::unlink, memset(3), realloc(3),istat(3), strcat(3), strchr(3), strcmp(3), strcpy(3), strlen(3),time(3),JDbTxnMgr::checkpoint,>DbTxnMgr::open,BDbTxnMgr::unlink, vfprintf(3),ande vsnprintf(3)._

lIn addition, the DbEnv::appinith&method may fail and throw an exceptionor return errnofor the following conditions:b

B

EINVAL
An invalid flag value or parameter was specified.

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

c?The DB_HOME or TMPDIR environment variables were set but empty.b

lCAn incorrectly formatted NAME VALUE entry or line was found. 

c

t

`

ENOSPC
HP-UX only: a previously created Berkeley DB environment for this process stillexists. 
t



Class

2DbEnv

t

See Also

aDbEnv::appinit,y>DbEnv::appexit,>DbEnv::version,dbenv_get_data_dir,dbenv_get_errcall,dbenv_get_errfilepdbenv_get_error_model,dbenv_get_error_model dbenv_get_error_stream,fdbenv_get_errpfx,rdbenv_get_flags,dbenv_get_home,xFDbEnv::get_lg_info,dbenv_get_lg_max,rdbenv_get_lk_conflicts,rdbenv_get_lk_detect,FDbEnv::get_lk_info,dbenv_get_lk_modes,ddbenv_get_log_dir,dbenv_get_lorder, FDbEnv::get_mp_info,dbenv_get_mp_mmapsize,dbenv_get_mp_size,dbenv_get_tmp_dir,FDbEnv::get_tx_info,dbenv_get_tx_max,bdbenv_get_tx_recoverandadbenv_get_verbose.
oafÿÿ../../api_cxx/DbMpool/open.html">DbMpool::open andiDbTxnMgr::open), is called as follows, where the DB_CREATE_flag is optional:uB



GThis call will cause each subsystem to construct pathnames as describedrRin Berkeley DB File Naming. The subsystemChas permission to read and write underlyin