--- name: "db_appinit" section: "3db" platform: "linux" package: "libdb2-dev" version: "2.4.14-1" release: "Debian 2.1 (Slink)" platforms: ["linux"] url: "https://new.carta.tech/db_appinit" --- # db\_appinit(3db) initializing the DB environment ## NAME db\_appinit - initializing the DB environment ## SYNOPSIS ``` #include char * db_version(int *major, int *minor, int *patch); int db_appinit(char *db_home, char *db_config[], DB_ENV *dbenv, u_int32_t flags); int db_appexit(DB_ENV *dbenv); ``` ## DESCRIPTION The DB library is a family of groups of functions that provides a modular programming interface to transactions and record-oriented file access. The library includes support for transactions, locking, logging and file page caching, as well as various indexed access methods. Many of the functional groups (e.g., the file page caching functions) are useful independent of the other DB functions, although some functional groups are explicitly based on other functional groups (e.g., transactions and logging). For a general description of the DB package, see *db\_intro*(3). *db\_version* The *db\_version* function returns a pointer to a string containing DB version information. If *major* is non-NULL, the major version of the DB release is stored in the memory it references. If *minor* is non-NULL, the minor version of the DB release is stored in the memory it references. If *patch* is non-NULL, the patch version of the DB release is stored in the memory it references. *db\_appinit* The *db\_appinit* function provides a simple way to initialize and configure the DB environment. It is not necessary that it be called, but it provides a method of creating a consistent environment for processes using one or more of the features of DB. The *db\_home* and *db\_config* arguments to *db\_appinit* are described in the section below entitled \`\`FILE NAMING''. The *flags* argument specifies the subsystems that are initialized and how the environment affects DB file naming, among other things. The *flags* value is specified by **or**'ing together one or more of the following values: - DB\_CREATE Cause subsystems to create any underlying files, as necessary. (See *db\_lock*(3), *db\_log*(3), *db\_mpool*(3), *db\_open*(3) and *db\_txn*(3) for more information.) - DB\_INIT\_LOCK Initialize the lock subsystem; see *db\_lock*(3). This subsystem should be used when multiple processes or threads are going to be reading and writing a DB database, so that they do not interfere with each other. If all threads are accessing the database(s) read-only, then locking is unnecessary. When the DB\_INIT\_LOCK flag is specified, it is usually necessary to run the deadlock detector, [*db\_deadlock*(1)](/db_deadlock/1.md), as well. - DB\_INIT\_LOG Initialize the log subsystem; see *db\_log*(3). This subsystem is used when recovery from application or system failure is important. - DB\_INIT\_MPOOL Initialize the mpool subsystem; see *db\_mpool*(3). This subsystem is used whenever the application is using the DB access methods for any purpose. - DB\_INIT\_TXN Initialize the transaction subsystem; see *db\_txn*(3). This subsystem is used when atomicity of multiple operations and recovery are important. The DB\_INIT\_TXN flag implies the DB\_INIT\_LOG flag. - DB\_MPOOL\_PRIVATE Create a private memory pool (see *db\_mpool*(3) for further information). Ignored unless DB\_INIT\_MPOOL is also specified. - DB\_NOMMAP Do not map any files within this environment (see *db\_mpool*(3) for further information). Ignored unless DB\_INIT\_MPOOL is also specified. - DB\_RECOVER Run normal recovery on this environment before opening it for normal use. If this flag is set, the DB\_CREATE flag must also be set since the regions will be removed and recreated. The *db\_appinit* function returns successfully if DB\_RECOVER is specified and no log files exist, so it is necessary to ensure all necessary log files are present before running recovery. For further information, consult the man page for [*db\_archive*(1)](/db_archive/1.md) and [*db\_recover*(1)](/db_recover/1.md). - DB\_RECOVER\_FATAL Run catastrophic recovery on this environment before opening it for normal use. If this flag is set, the DB\_CREATE flag must also be set since the regions will be removed and recreated. The *db\_appinit* function returns successfully if DB\_RECOVER is specified and no log files exist, so it is necessary to ensure all necessary log files are present before running recovery. For further information, consult the man page for [*db\_archive*(1)](/db_archive/1.md) and [*db\_recover*(1)](/db_recover/1.md). - DB\_THREAD Ensure that handles returned by the DB subsystems are useable by multiple threads within a single process, i.e., that the system is \`\`free-threaded''. (See *db\_lock*(3), *db\_log*(3), *db\_mpool*(3), *db\_open*(3) and *db\_txn*(3) for more information.) - DB\_TXN\_NOSYNC On transaction commit, do not synchronously flush the log (see *db\_txn*(3) for further information). Ignored unless DB\_INIT\_TXN is also specified. - DB\_USE\_ENVIRON The DB process' environment may be permitted to specify information to be used when naming files (see the section entitled \`\`FILE NAMING'' below). As permitting users to specify which files are used can create security problems, environment information will be used in file naming for all users only if the DB\_USE\_ENVIRON flag is set. - DB\_USE\_ENVIRON\_ROOT The DB process' environment may be permitted to specify information to be used when naming files (see the section entitled \`\`FILE NAMING'' below). As permitting users to specify which files are used can create security problems, if the DB\_USE\_ENVIRON\_ROOT flag is set, environment information will be used for file naming only for users with a user-ID matching that of the superuser (specifically, users for whom the *getuid* system call returns the user-ID 0). The DB environment is configured based on the *dbenv* argument to *db\_appinit*, which is a pointer to a structure of type DB\_ENV (typedef'd in \). Applications will normally use the same DB\_ENV structure (initialized by *db\_appinit*(3)), as an argument to all of the subsystems in the DB package. References to the DB\_ENV structure are maintained by DB, so it may not be discarded until the last close function, corresponding to an open function for which it was an argument, has returned. In order to ensure compatibility with future releases of DB, all fields of the DB\_ENV structure that are not explicitly set should be initialized to 0 before the first time the structure is used. Do this by declaring the structure external or static, or by calling the C library routine [*bzero*(3)](/bzero/3.md) or [*memset*(3)](/memset/3.md). The fields of the DB\_ENV structure used by *db\_appinit* are described below. The *dbenv* argument may not be NULL. If any of the fields of the *dbenv* are set to 0, defaults appropriate for the system are used where possible. The following fields in the DB\_ENV structure may be initialized before calling *db\_appinit*: - void (\*db\_errcall)(char \*db\_errpfx, char \*buffer); When an error occurs in the DB package, an *errno* value is returned by the function. In some cases, however, the *errno* value may be insufficient to completely describe the cause of the error. - If *db\_errcall* is non-NULL, it may be called with additional error information. The *db\_errpfx* argument is the current environment's *db\_errpfx* field. The *buffer* argument contains a nul-terminated string with the additional information. This error logging facility should not be required for normal operation, but may be useful in debugging applications. - FILE \*db\_errfile; The *db\_errfile* field behaves similarly to the *db\_errcall* field, except that the error message is written to the file stream represented by *db\_errfile*. If *db\_errpfx* is non-NULL, the message will be preceded by the string referenced by *db\_errpfx*, a colon (\`\`:'') and a space. The message will be followed by a newline character. - const char \*db\_errpfx; A prefix to prepend to error messages. Because DB does not copy the memory referenced by the *db\_errpfx* field, the application may modify the error message prefix at any time. - int db\_verbose; Include informational and debugging messages as well as error messages in the *db\_errcall* and *db\_errfile* output. Each of the open functions that *db\_appinit* may call (*lock\_open*, *log\_open*, *memp\_open* and *txn\_open*) is called as follows, where the DB\_CREATE flag is optional: XXX\_open(NULL, DB\_CREATE, S\_IRUSR \| S\_IWUSR \| S\_IRGRP \| S\_IWGRP, dbenv) This call will cause each subsystem to construct pathnames as described in the section on \`\`FILE NAMING''. The subsystem has permission to read and write underlying files as necessary, and optionally to create files. (All created files will be created readable and writeable by the owner and the group. The group ownership of created files is based on the system and directory defaults, and is not further specified by DB.) In addition, the *dbenv* argument is passed to the open functions of any subsystems initialized by *db\_appinit*. For this reason the fields of the DB\_ENV structure relevant to the subsystems being initialized must themselves be initialized before *db\_appinit* is called. See the manual page for each subsystem for a list of these fields and their uses. The return value from each of these calls is placed in the appropriate field of the DB\_ENV structure: - DB\_LOCKTAB \*lk\_info; The return value of the *lock\_open*(3) call. - DB\_LOG \*lg\_info; The return value of the [*log\_open*(3)](/log_open/3.md) call. - DB\_MPOOL \*mp\_info; The return value of the *memp\_open*(3) call. - DB\_TXNMGR \*tx\_info; The return value of the *txn\_open*(3) call. In general, these fields are not directly used by applications; subsystems of DB that use these fields will simply reference them using the DB\_ENV argument passed to the subsystem. For example, an application using the DB hash access method functions to access a database will first call *db\_open* passing it the DB\_ENV argument filled in by the initial call to *db\_appinit*. Then, all future calls to the hash access method functions for that database will automatically use the underlying shared memory buffer pool that was specified by the *mp\_info* field of that DB\_ENV argument. The single exception to this rule is the *tx\_info* field, which applications must explicitly specify to the *txn\_begin*, *txn\_checkpoint* and *txn\_close* functions. Once the DB environment has been initialized by a call to *db\_appinit*, no fields other than *db\_errpfx* should be modified. The *db\_appinit* function returns the value of *errno* on failure and 0 on success. *db\_appexit* The *db\_appexit* function closes the initialized DB subsystems, freeing any allocated resources and closing any underlying subsystems. When multiple threads are using the DB\_ENV handle concurrently, only a single thread may call the *db\_appexit* function. The *db\_appexit* function returns the value of *errno* on failure and 0 on success. ## FILE NAMING The most important task of *db\_appinit* is to structure file naming within DB. Each of the locking, logging, memory pool and transaction subsystems of DB require shared memory regions, backed by the filesystem. Further, cooperating applications (or multiple invocations of the same application) must agree on the location of the shared memory regions and other files used by the DB subsystems, the log files used by the logging subsystem, and, of course, the data files. Although it is possible to specify full pathnames to all DB functions, this is cumbersome and requires that applications be recompiled when database files are moved. The *db\_appinit* function makes it possible to place database files in a single directory, or in multiple directories, grouped by their function within the database. Applications are normally expected to specify a single directory home for their database. This can be done easily in the call to *db\_appinit* by specifying a value for the *db\_home* argument. There are more complex configurations where it may be desirable to override *db\_home* or provide supplementary path information. The following describes the possible ways in which file naming information may be specified to the DB library. The specific circumstances and order in which these ways are applied are described in a subsequent paragraph. - *db\_home* If the *db\_home* argument to *db\_appinit* is non-NULL, its value may be used as the database home, and files named relative to its path. - DB\_HOME If the DB\_HOME environment variable is set when *db\_appinit* is called, its value may be used as the database home, and files named relative to its path. - *db\_config* The *db\_config* argument to *db\_appinit* may be used to specify an array of character strings of the format \`\`NAME VALUE'', that specify file name information for the process' DB environment. The whitespace delimiting the two parts of the entry may be one or more \ or \ characters. (Leading or trailing \ and \ characters are discarded.) Each entry must specify both the NAME and the VALUE of the pair. All entries with unrecognized NAME values will be ignored. The *db\_config* array must be NULL terminated. - DB\_CONFIG The same information specified to the *db\_config* argument to *db\_appinit* may be specified using a configuration file. If a database home directory has been specified (either by the application specifying a non-NULL *db\_home* argument to *db\_appinit*, or by the application setting the DB\_USE\_ENVIRON or DB\_USE\_ENVIRON\_ROOT flags and the DB\_HOME environment variable being set), any file named \`\`DB\_CONFIG'' in the database home directory will be read for lines of the format \`\`NAME VALUE''. The whitespace delimiting the two parts of the line may be one or more \ or \ characters. (Leading or trailing \ and \ characters are discarded.) All empty lines or lines whose first non-whitespace character is a hash character (\`\`#'') will be ignored. Each line must specify both the NAME and the VALUE of the pair. All lines with unrecognized NAME values will be ignored. The following \`\`NAME VALUE'' pairs in the *db\_config* argument and the DB\_CONFIG file are currently supported by DB. - DB\_DATA\_DIR The path of a directory to be used as the location of the access method data files, e.g., paths specified to the *db\_open*(3) function will be relative to this path. - The DB\_DATA\_DIR paths are additive, and specifying more than one will result in each specified directory being searched for database data files. If multiple paths are specified, created data files will always be created in the **first** directory specified. - DB\_LOG\_DIR The path of a directory to be used as the location of logging files, e.g., files created by the *db\_log*(3) subsystem will be relative to this directory. If specified, this is the directory name that will be passed to [*log\_open*(3)](/log_open/3.md). - DB\_TMP\_DIR The path of a directory to be used as the location of temporary files, e.g., files created to back in-memory access method databases will be created relative to this path. Note, these temporary files can potentially be quite large, depending on the size of the database. If DB\_TMP\_DIR is not specified, the following environment variables are checked in order: \`\`TMPDIR'', \`\`TEMP'', \`\`TMP'' and \`\`TempFolder''. If one of them is set, temporary files are created relative to the directory it specifies. If DB\_TMP\_DIR is not specified and none of the above environment variables are set, the first possible one of the following directories is used: */var/tmp*, */usr/tmp*, */temp*, */tmp*, *C:/temp* and *C:/tmp*. The following describes the specific circumstances and order in which the different ways of specifying file naming information are applied. Specifically, DB file name processing proceeds sequentially through the following steps: - \`\`/'' If any file name specified to any DB function begins with a leading slash, that file name is used without modification by DB. - DB\_CONFIG If a relevant configuration string (e.g., DB\_DATA\_DIR), is specified in the DB\_CONFIG configuration file, the VALUE from the \`\`NAME VALUE'' pair is prepended to the current file name. If the resulting file name begins with a leading slash, the file name is used without further modification by DB. The DB\_CONFIG configuration file is intended to permit systems to customize file location for a database independent of applications using that database. For example, a database administrator can move the database log and data files to a different location without application recompilation. - *db\_config* If a relevant configuration string (e.g., DB\_DATA\_DIR), is specified in the *db\_config* argument and is not specified in the DB\_CONFIG file, the VALUE from the \`\`NAME VALUE'' pair is prepended to the current file name. If the resulting file name begins with a leading slash, the file name is used without further modification by DB. The *db\_config* argument is intended to permit applications to customize file location for a database. For example, an application writer can place data files and log files in different directories, or instantiate a new log directory each time the application runs. - DB\_HOME If the DB\_HOME environment variable was set, (and the application has set the appropriate DB\_USE\_ENVIRON or DB\_USE\_ENVIRON\_ROOT environment variable), its value is prepended to the current file name. If the resulting file name begins with a leading slash, the file name is used without further modification by DB. The DB\_HOME environment variable is intended to permit users and system administrators to override application and installation defaults, e.g., env DB\_HOME=/database/my\_home application Alternatively, application writers are encouraged to support the **-h** option found in the supporting DB utilities to let users specify a database home. - *db\_home* If the application specified a non-NULL *db\_home* argument to *db\_appinit* (and the database home was not already specified using the DB\_HOME environment variable) its value is prepended to the current file name. If the resulting file name begins with a leading slash, the file name is used without further modification by DB. - (nothing) Finally, all file names are interpreted relative to the current working directory of the process. The common model for a DB environment is one where only the DB\_HOME environment variable, or the *db\_home* argument, is specified. In this case, all data files will be presumed to be relative to that directory, and all files created by the DB subsystems will be created in that directory. The more complex model for a transaction environment might be one where a database home is specified, using either the DB\_HOME environment variable or the *db\_home* argument to *db\_appinit*, and then DB\_DATA\_DIR and DB\_LOG\_DIR are set to the relative path names of directories underneath the home directory using the *db\_config* argument to *db\_appinit* or the DB\_CONFIG file. ## EXAMPLES Store all files in the directory */a/database*: ``` db_appinit("/a/database", NULL, ...); ``` Create temporary backing files in */b/temporary*, and all other files in */a/database*: ``` char *config[] = { "DB_TMP_DIR /b/temporary", NULL }; db_appinit("/a/database", config, ...); ``` Store data files in */a/database/datadir*, log files in */a/database/logdir*, and all other files in the directory */a/database*: ``` char *config[] = { "DB_DATA_DIR datadir", "DB_LOG_DIR logdir", NULL }; db_appinit("/a/database", config, ...); ``` Store data files in */a/database/data1* and */b/data2*, and all other files in the directory */a/database*. Any data files that are created will be created in */b/data2*: ``` char *config[] = { "DB_DATA_DIR /b/data2", "DB_DATA_DIR data1", NULL }; db_appinit("/a/database", config, ...); ``` See the file *examples/ex\_appinit.c* in the DB source distribution for a C language code example of how an application might use *db\_appinit* to configure its DB environment. ## ERRORS The *db\_appinit* function may fail and return *errno* for any of the errors specified for the following DB and library functions: DB-\>close(3), [calloc(3)](/calloc/3.md), db\_appexit(3), [fclose(3)](/fclose/3.md), [fcntl(2)](/fcntl/2.md), [fflush(3)](/fflush/3.md), [fgets(3)](/fgets/3.md), [fopen(3)](/fopen/3.md), lock\_open(3), lock\_unlink(3), log\_compare(3), log\_get(3), [log\_open(3)](/log_open/3.md), log\_unlink(3), [malloc(3)](/malloc/3.md), [memcpy(3)](/memcpy/3.md), memp\_open(3), memp\_unlink(3), [memset(3)](/memset/3.md), [realloc(3)](/realloc/3.md), [stat(2)](/stat/2.md), [strchr(3)](/strchr/3.md), [strcmp(3)](/strcmp/3.md), [strcpy(3)](/strcpy/3.md), [strdup(3)](/strdup/3.md), [strerror(3)](/strerror/3.md), [strlen(3)](/strlen/3.md), [strsep(3)](/strsep/3.md), [time(3)](/time/3.md), txn\_checkpoint(3), txn\_open(3), and txn\_unlink(3). In addition, the *db\_appinit* function may fail and return *errno* for the following conditions: - \[EINVAL\] An invalid flag value or parameter was specified. The DB\_THREAD flag was specified and spinlocks are not implemented for this architecture. The DB\_RECOVER or DB\_RECOVER\_FATAL flag was specified, and no log files were found. The DB\_HOME or TMPDIR environment variables were set but empty. An incorrectly formatted \`\`NAME VALUE'' entry or line was found. - \[ENOSPC\] HP-UX only: a previously created DB environment for this process still exists. The *db\_appexit* function may fail and return *errno* for any of the errors specified for the following DB and library functions: lock\_close(3), [log\_close(3)](/log_close/3.md), memp\_close(3), and txn\_close(3). ## BUGS Due to the constraints of the PA-RISC memory architecture, HP-UX does not allow a process to map a file into its address space multiple times. For this reason, each DB environment may be opened only once by a process on HP-UX, i.e., calls to *appinit* will fail if the specified DB environment has been opened and not subsequently closed. On Windows/95, files that are opened by multiple processes do not share data correctly. To tell Berkeley DB to use the paging file to share memory among processes, use the DB\_REGION\_NAME flag of the *db\_value\_set* function. Obviously, you do not need to do this if only a single process will be accessing database files. ## SEE ALSO [*db\_archive*(1)](/db_archive/1.md), [*db\_checkpoint*(1)](/db_checkpoint/1.md), [*db\_deadlock*(1)](/db_deadlock/1.md), [*db\_dump*(1)](/db_dump/1.md), [*db\_load*(1)](/db_load/1.md), [*db\_recover*(1)](/db_recover/1.md), [*db\_stat*(1)](/db_stat/1.md), *db\_intro*(3), *db\_appinit*(3), *db\_cursor*(3), *db\_dbm*(3), *db\_internal*(3), *db\_lock*(3), *db\_log*(3), *db\_mpool*(3), *db\_open*(3), *db\_thread*(3), *db\_txn*(3)