NNAAMMEE db_appinit - initializing the DB environment SSYYNNOOPPSSIISS ##iinncclluuddee <> cchhaarr ** ddbb__vveerrssiioonn((iinntt **mmaajjoorr,, iinntt **mmiinnoorr,, iinntt **ppaattcchh));; iinntt ddbb__aappppiinniitt((cchhaarr **ddbb__hhoommee,, cchhaarr **ddbb__ccoonnffiigg[[]],, DDBB__EENNVV **ddbbeennvv,, uu__iinntt3322__tt ffllaaggss));; iinntt ddbb__aappppeexxiitt((DDBB__EENNVV **ddbbeennvv));; DDEESSCCRRIIPPTTIIOONN 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 func- tions, 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 _d_b___i_n_t_r_o(3). _d_b___v_e_r_s_i_o_n The _d_b___v_e_r_s_i_o_n function returns a pointer to a string con- taining DB version information. If _m_a_j_o_r is non-NULL, the major version of the DB release is stored in the memory it references. If _m_i_n_o_r is non-NULL, the minor version of the DB release is stored in the memory it references. If _p_a_t_c_h is non-NULL, the patch version of the DB release is stored in the memory it references. _d_b___a_p_p_i_n_i_t The _d_b___a_p_p_i_n_i_t function provides a simple way to initial- ize 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 _d_b___h_o_m_e and _d_b___c_o_n_f_i_g arguments to _d_b___a_p_p_i_n_i_t are described in the section below entitled ``FILE NAMING''. The _f_l_a_g_s argument specifies the subsystems that are ini- tialized and how the environment affects DB file naming, among other things. The _f_l_a_g_s value is specified by oorr'ing together one or more of the following values: DB_CREATE Cause subsystems to create any underlying files, as necessary. (See _d_b___l_o_c_k(3), _d_b___l_o_g(3), _d_b___m_p_o_o_l(3), _d_b___o_p_e_n(3) and _d_b___t_x_n(3) for more information.) DB_INIT_LOCK Initialize the lock subsystem; see _d_b___l_o_c_k(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 neces- sary to run the deadlock detector, _d_b___d_e_a_d_l_o_c_k(1), as well. DB_INIT_LOG Initialize the log subsystem; see _d_b___l_o_g(3). This subsystem is used when recovery from application or system failure is important. DB_INIT_MPOOL Initialize the mpool subsystem; see _d_b___m_p_o_o_l(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 _d_b___t_x_n(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 _d_b___m_p_o_o_l(3) for further information). Ignored unless DB_INIT_MPOOL is also specified. DB_NOMMAP Do not map any files within this environment (see _d_b___m_p_o_o_l(3) for further information). Ignored unless DB_INIT_MPOOL is also specified. DB_RECOVER Run normal recovery on this environment before open- ing 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 _d_b___a_p_p_i_n_i_t 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 infor- mation, consult the man page for _d_b___a_r_c_h_i_v_e(1) and _d_b___r_e_c_o_v_e_r(1). 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 _d_b___a_p_p_i_n_i_t 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 infor- mation, consult the man page for _d_b___a_r_c_h_i_v_e(1) and _d_b___r_e_c_o_v_e_r(1). 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 _d_b___l_o_c_k(3), _d_b___l_o_g(3), _d_b___m_p_o_o_l(3), _d_b___o_p_e_n(3) and _d_b___t_x_n(3) for more information.) DB_TXN_NOSYNC On transaction commit, do not synchronously flush the log (see _d_b___t_x_n(3) for further information). Ignored unless DB_INIT_TXN is also specified. DB_USE_ENVIRON The DB process' environment may be permitted to spec- ify information to be used when naming files (see the section entitled ``FILE NAMING'' below). As permit- ting 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 spec- ify information to be used when naming files (see the section entitled ``FILE NAMING'' below). As permit- ting 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 _g_e_t_u_i_d system call returns the user-ID 0). The DB environment is configured based on the _d_b_e_n_v argu- ment to _d_b___a_p_p_i_n_i_t, which is a pointer to a structure of type DB_ENV (typedef'd in ). Applications will nor- mally use the same DB_ENV structure (initialized by _d_b___a_p_p_i_n_i_t(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 _b_z_e_r_o(3) or _m_e_m_s_e_t(3). The fields of the DB_ENV structure used by _d_b___a_p_p_i_n_i_t are described below. The _d_b_e_n_v argument may not be NULL. If any of the fields of the _d_b_e_n_v are set to 0, defaults appropriate for the system are used where possible. The following fields in the DB_ENV structure may be ini- tialized before calling _d_b___a_p_p_i_n_i_t: void (*db_errcall)(char *db_errpfx, char *buffer); When an error occurs in the DB package, an _e_r_r_n_o value is returned by the function. In some cases, however, the _e_r_r_n_o value may be insufficient to com- pletely describe the cause of the error. If _d_b___e_r_r_c_a_l_l is non-NULL, it may be called with additional error information. The _d_b___e_r_r_p_f_x argument is the current environment's _d_b___e_r_r_p_f_x field. The _b_u_f_f_e_r 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 _d_b___e_r_r_f_i_l_e field behaves similarly to the _d_b___e_r_r_c_a_l_l field, except that the error message is written to the file stream represented by _d_b___e_r_r_f_i_l_e. If _d_b___e_r_r_p_f_x is non-NULL, the message will be pre- ceded by the string referenced by _d_b___e_r_r_p_f_x, 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 _d_b___e_r_r_p_f_x 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 _d_b___e_r_r_c_a_l_l and _d_b___e_r_r_f_i_l_e output. Each of the open functions that _d_b___a_p_p_i_n_i_t may call (_l_o_c_k___o_p_e_n, _l_o_g___o_p_e_n, _m_e_m_p___o_p_e_n and _t_x_n___o_p_e_n) 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 sub- system has permission to read and write underlying files as necessary, and optionally to create files. (All cre- ated 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 _d_b_e_n_v argument is passed to the open functions of any subsystems initialized by _d_b___a_p_p_i_n_i_t. For this reason the fields of the DB_ENV structure rele- vant to the subsystems being initialized must themselves be initialized before _d_b___a_p_p_i_n_i_t is called. See the man- ual 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 _l_o_c_k___o_p_e_n(3) call. DB_LOG *lg_info; The return value of the _l_o_g___o_p_e_n(3) call. DB_MPOOL *mp_info; The return value of the _m_e_m_p___o_p_e_n(3) call. DB_TXNMGR *tx_info; The return value of the _t_x_n___o_p_e_n(3) call. In general, these fields are not directly used by applica- tions; 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 _d_b___o_p_e_n passing it the DB_ENV argument filled in by the initial call to _d_b___a_p_p_i_n_i_t. Then, all future calls to the hash access method functions for that database will auto- matically use the underlying shared memory buffer pool that was specified by the _m_p___i_n_f_o field of that DB_ENV argument. The single exception to this rule is the _t_x___i_n_f_o field, which applications must explicitly specify to the _t_x_n___b_e_g_i_n, _t_x_n___c_h_e_c_k_p_o_i_n_t and _t_x_n___c_l_o_s_e functions. Once the DB environment has been initialized by a call to _d_b___a_p_p_i_n_i_t, no fields other than _d_b___e_r_r_p_f_x should be modi- fied. The _d_b___a_p_p_i_n_i_t function returns the value of _e_r_r_n_o on failure and 0 on success. _d_b___a_p_p_e_x_i_t The _d_b___a_p_p_e_x_i_t function closes the initialized DB subsys- tems, freeing any allocated resources and closing any underlying subsystems. When multiple threads are using the DB_ENV handle concur- rently, only a single thread may call the _d_b___a_p_p_e_x_i_t func- tion. The _d_b___a_p_p_e_x_i_t function returns the value of _e_r_r_n_o on failure and 0 on success. FFIILLEE NNAAMMIINNGG The most important task of _d_b___a_p_p_i_n_i_t 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 appli- cations be recompiled when database files are moved. The _d_b___a_p_p_i_n_i_t 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 eas- ily in the call to _d_b___a_p_p_i_n_i_t by specifying a value for the _d_b___h_o_m_e argument. There are more complex configura- tions where it may be desirable to override _d_b___h_o_m_e 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. _d_b___h_o_m_e If the _d_b___h_o_m_e argument to _d_b___a_p_p_i_n_i_t 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 _d_b___a_p_p_i_n_i_t is called, its value may be used as the database home, and files named relative to its path. _d_b___c_o_n_f_i_g The _d_b___c_o_n_f_i_g argument to _d_b___a_p_p_i_n_i_t 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 trail- ing and characters are discarded.) Each entry must specify both the NAME and the VALUE of the pair. All entries with unrecognized NAME val- ues will be ignored. The _d_b___c_o_n_f_i_g array must be NULL terminated. DB_CONFIG The same information specified to the _d_b___c_o_n_f_i_g argu- ment to _d_b___a_p_p_i_n_i_t may be specified using a configu- ration file. If a database home directory has been specified (either by the application specifying a non-NULL _d_b___h_o_m_e argument to _d_b___a_p_p_i_n_i_t, or by the application setting the DB_USE_ENVIRON or DB_USE_ENV- IRON_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 _d_b___c_o_n_f_i_g argu- ment 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 _d_b___o_p_e_n(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 ffiirrsstt 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 _d_b___l_o_g(3) subsystem will be relative to this directory. If specified, this is the directory name that will be passed to _l_o_g___o_p_e_n(3). DB_TMP_DIR The path of a directory to be used as the location of temporary files, e.g., files created to back in-mem- ory access method databases will be created relative to this path. Note, these temporary files can poten- tially be quite large, depending on the size of the database. If DB_TMP_DIR is not specified, the following envi- ronment 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: _/_v_a_r_/_t_m_p, _/_u_s_r_/_t_m_p, _/_t_e_m_p, _/_t_m_p, _C_:_/_t_e_m_p and _C_:_/_t_m_p. The following describes the specific circumstances and order in which the different ways of specifying file nam- ing 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 configu- ration 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 per- mit 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. _d_b___c_o_n_f_i_g If a relevant configuration string (e.g., DB_DATA_DIR), is specified in the _d_b___c_o_n_f_i_g argument and is not specified in the DB_CONFIG file, the VALUE from the ``NAME VALUE'' pair is prepended to the cur- rent file name. If the resulting file name begins with a leading slash, the file name is used without further modification by DB. The _d_b___c_o_n_f_i_g argument is intended to permit applica- tions to customize file location for a database. For example, an application writer can place data files and log files in different directories, or instanti- ate 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 per- mit 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 --hh option found in the supporting DB utilities to let users specify a database home. _d_b___h_o_m_e If the application specified a non-NULL _d_b___h_o_m_e argu- ment to _d_b___a_p_p_i_n_i_t (and the database home was not already specified using the DB_HOME environment vari- able) its value is prepended to the current file name. If the resulting file name begins with a lead- ing slash, the file name is used without further mod- ification 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 _d_b___h_o_m_e argument, is specified. In this case, all data files will be pre- sumed to be relative to that directory, and all files cre- ated by the DB subsystems will be created in that direc- tory. 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 _d_b___h_o_m_e argument to _d_b___a_p_p_i_n_i_t, and then DB_DATA_DIR and DB_LOG_DIR are set to the relative path names of directories underneath the home directory using the _d_b___c_o_n_f_i_g argument to _d_b___a_p_p_i_n_i_t or the DB_CONFIG file. EEXXAAMMPPLLEESS Store all files in the directory _/_a_/_d_a_t_a_b_a_s_e: db_appinit("/a/database", NULL, ...); Create temporary backing files in _/_b_/_t_e_m_p_o_r_a_r_y, and all other files in _/_a_/_d_a_t_a_b_a_s_e: char *config[] = { "DB_TMP_DIR /b/temporary", NULL }; db_appinit("/a/database", config, ...); Store data files in _/_a_/_d_a_t_a_b_a_s_e_/_d_a_t_a_d_i_r, log files in _/_a_/_d_a_t_a_b_a_s_e_/_l_o_g_d_i_r, and all other files in the directory _/_a_/_d_a_t_a_b_a_s_e: char *config[] = { "DB_DATA_DIR datadir", "DB_LOG_DIR logdir", NULL }; db_appinit("/a/database", config, ...); Store data files in _/_a_/_d_a_t_a_b_a_s_e_/_d_a_t_a_1 and _/_b_/_d_a_t_a_2, and all other files in the directory _/_a_/_d_a_t_a_b_a_s_e. Any data files that are created will be created in _/_b_/_d_a_t_a_2: char *config[] = { "DB_DATA_DIR /b/data2", "DB_DATA_DIR data1", NULL }; db_appinit("/a/database", config, ...); See the file _e_x_a_m_p_l_e_s_/_e_x___a_p_p_i_n_i_t_._c in the DB source dis- tribution for a C language code example of how an applica- tion might use _d_b___a_p_p_i_n_i_t to configure its DB environment. EERRRROORRSS The _d_b___a_p_p_i_n_i_t function may fail and return _e_r_r_n_o for any of the errors specified for the following DB and library functions: DB->close(3), calloc(3), db_appexit(3), fclose(3), fcntl(2), fflush(3), fgets(3), fopen(3), lock_open(3), lock_unlink(3), log_compare(3), log_get(3), log_open(3), log_unlink(3), malloc(3), memcpy(3), memp_open(3), memp_unlink(3), memset(3), realloc(3), stat(2), strchr(3), strcmp(3), strcpy(3), strdup(3), str- error(3), strlen(3), strsep(3), time(3), txn_check- point(3), txn_open(3), and txn_unlink(3). In addition, the _d_b___a_p_p_i_n_i_t function may fail and return _e_r_r_n_o 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 speci- fied, 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 _d_b___a_p_p_e_x_i_t function may fail and return _e_r_r_n_o for any of the errors specified for the following DB and library functions: lock_close(3), log_close(3), memp_close(3), and txn_close(3). BBUUGGSS 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 _a_p_p_i_n_i_t will fail if the specified DB envi- ronment 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 _d_b___v_a_l_u_e___s_e_t function. Obvi- ously, you do not need to do this if only a single process will be accessing database files. SSEEEE AALLSSOO _d_b___a_r_c_h_i_v_e(1), _d_b___c_h_e_c_k_p_o_i_n_t(1), _d_b___d_e_a_d_l_o_c_k(1), _d_b___d_u_m_p(1), _d_b___l_o_a_d(1), _d_b___r_e_c_o_v_e_r(1), _d_b___s_t_a_t(1), _d_b___i_n_t_r_o(3), _d_b___a_p_p_i_n_i_t(3), _d_b___c_u_r_s_o_r(3), _d_b___d_b_m(3), _d_b___i_n_t_e_r_n_a_l(3), _d_b___l_o_c_k(3), _d_b___l_o_g(3), _d_b___m_p_o_o_l(3), _d_b___o_p_e_n(3), _d_b___t_h_r_e_a_d(3), _d_b___t_x_n(3)