/I&Berkeley DB: db_appinit[P

db_appinit





#include <db.h>

intdb_appinit(char *db_home,5 char *db_config, DB_ENV *dbenv, u_int32_t flags);





Description



IThe db_appinit function 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.

?The db_home and db_config arguments to db_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 beyspecified (e.g., do not set DB_INIT_LOCK). Access method callsxare largely unchanged when using the DB_INIT_CDB flag, althoughjany cursors through which update operations (e.g., DBcursor->c_putDBcursor->c_del) will be made, must have the DB_RMW value set inDthe flags parameter to the cursor call that creates the cursor. SeeIDB->cursor for more information.9

DB_INIT_LOCK
Initialize the lock subsystem; see8lock_open.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 lock_detect for more information.7

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

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

DB_INIT_TXN
Initialize the transaction subsystem; see6txn_open.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; see6memp_open./Ignored unless DB_INIT_MPOOL is also specified.Q

DB_NOMMAP
Do not memory map database files within this environment; see6memp_open./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.

=The db_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.

@The db_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; see6txn_open.-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 configuredFbased on the dbenv argument to db_appinit which is a pointer toFa structure of type DB_ENV. Applications normally use the same DB_ENV>structure (initialized by db_appinit) as an argument to all of*the subsystems in the Berkeley DB package.

OReferences to the DB_ENV structure are maintained by Berkeley DB, so it may notDbe discarded until the last close function, corresponding to an open?function for which it was an argument, has returned. To ensureKcompatibility with future releases of Berkeley DB, all fields of the DB_ENVGstructure that are not explicitly set should be initialized to 0 beforeIthe first time the structure is used. Do this by declaring the structure?external or static, or by calling one of the C library routines$bzero(3) or memset(3).

JThe fields of the DB_ENV structure used by db_appinit are described below.CThe dbenv argument may not be NULL. If any of the fields ofEthe dbenv structure are set to 0, defaults appropriate for thesystem are used where possible.

FThe following fields in the DB_ENV structure may be initialized beforecalling db_appinit:

ˆ

void (*db_paniccall)(DB_ENV *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.)cIIn these cases, the value DB_RUNRECOVERY is returned by the function. ItaHis often simpler, however, to simply shut down the application when suchGerrors occur instead of attempting to gracefully return error values upc the stack.

aDIf 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 valuer*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 isCreturned by the function. In some cases, however, the errno Gvalue may be insufficient to completely describe the cause of the errord0especially during initial application debugging.

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

cFThis error logging facility does not slow performance or significantlyDincrease application size, and may be run during normal operation aswell as during debugging.em<except that the error message is written to the OutputStream#represented by error_stream.tallowing errors to bemHredirected to a C++ error stream. It is unwise to use both error_stream1with nonzero values of either errcall or errfile.ab

FILE *db_errfile;
The db_errfile field behaves similarly to the db_errcallfieldnn

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.m `

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

a3Each of the open functions that db_appinit may call §(lock_open, log_open, memp_open andsatxn_open), is called as follows, where the DB_CREATEeflag is optional: %



nGThis call will cause each subsystem to construct pathnames as describedsRin Berkeley DB File Naming. The subsystemChas permission to read and write underlying files as necessary, andaHoptionally to create files. (All created files will be created readableIand writeable by the owner and the group. The group ownership of created.Gfiles is based on the system and directory defaults, and is not furtherespecified by Berkeley DB.)

lFIn addition, the dbenv argument is passed to the open functionsAof any subsystems initialized by db_appinit. For this reason theo?fields of the DB_ENV structure relevant to the subsystems beingl?initialized must themselves be initialized before db_appinit is.Hcalled. See the appropriate subsystem documentation for a list of thesefields and their uses.

.FThe return value from each of these calls is placed in the appropriatefield of the DB_ENV structure:

q
DB_LOCKTAB *lk_info;
The return value of the lock_open call. h
DB_LOG *lg_info;
The return value of the log_open call.m
DB_MPOOL *mp_info;
The return value of the memp_open call.in
DB_TXNMGR *tx_info;
The return value of the txn_open call.
r

eJIn general, these fields are not directly used by applications; subsystemsKof Berkeley DB that use these fields simply reference them using the DB_ENV "structure passed to the subsystem.

t For example,Man application using the Berkeley DB hash access method functions to access aa]database will first call db_open passing it the DB_ENVt?argument initialized by a call to db_appinit. Then, all futurea@calls to the hash access method functions for that database willCautomatically use the underlying shared memory buffer pool that wasi?specified by the mp_info field of that DB_ENV structure. 

hDThe single exception to this rule is the tx_info field, whichdapplications must explicitly specify to the txn_begintxn_checkpoint and txn_close functions.

eAThe db_prefix field of DB_ENV allows the user to configure_Ithe error message prefix, and may be changed at any time, including afterathe call to db_appinit.t

HMOtherwise, once the Berkeley DB environment has been initialized by a call tob)db_appinit, no fields should be modified.,

,

Architecture Notes

-IDue to the constraints of the PA-RISC memory architecture, HP-UX does notcDallow 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 db_appinit will fail if theNspecified Berkeley DB environment has been opened and not subsequently closed.

eGOn 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.f

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

s

Errors

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

eThe db_appinit)function may fail and return errno(Kfor any of the errors specified for the following Berkeley DB and C librarym functions:2DB->close, abort(3),i ctime(3), 8db_appexit,dbenv->tx_recover(3),t fclose(3), fcntl(3),a fflush(3), fgets(3),t fopen(3),h fprintf(3),ifree(3), getenv(3), getpid(3), getuid(3), isspace(3),s8lock_open,<lock_unlink,9log_compare, 1log_get,e3log_open,a7log_unlink, malloc(3), memcpy(3),6memp_open,:memp_unlink, memset(3), realloc(3),estat(3), strcat(3), strchr(3), strcmp(3), strcpy(3), strlen(3),time(3),Btxn_checkpoint,6txn_open,:txn_unlink, vfprintf(3),ando vsnprintf(3).i

In addition, the db_appinita)function may fail and return errnopfor the following conditions:

B

EINVAL
An invalid flag value or parameter was specified.

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

a?The DB_HOME or TMPDIR environment variables were set but empty.u

eCAn incorrectly formatted NAME VALUE entry or line was found.O



n

`

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

t

See Also

8db_appexit, db_appinit,a8db_version,2DB->close,4DB->cursor,.DB->del,,DB->fd,.DB->get,/db_open,>.DB->put,0DB->stat,0DB->sync,;DBcursor->c_close,n7DBcursor->c_del,l6DBcursor->c_getanda7DBcursor->c_put.e
erm˙˙t contains a6nul-terminated string with the additional information.

cFThis error logging facility does not slow performance or significantlyDincrease application size, and may be run during normal operation aswell as during debugging.e