NNAAMMEE DbEnv - Db initialization and environment options SSYYNNOOPPSSIISS ##iinncclluuddee <> DDbbEEnnvv::::DDbbEEnnvv((ccoonnsstt cchhaarr **ddbb__hhoommee,, cchhaarr **ccoonnsstt **ddbb__ccoonnffiigg,, uu__iinntt3322__tt ffllaaggss));; DDbbEEnnvv::::DDbbEEnnvv(());; DDbbEEnnvv::::~~DDbbEEnnvv(());; iinntt DDbbEEnnvv::::aappppiinniitt((ccoonnsstt cchhaarr **ddbb__hhoommee,, cchhaarr **ccoonnsstt **ddbb__ccoonnffiigg,, uu__iinntt3322__tt ffllaaggss));; iinntt DDbbEEnnvv::::ggeett__lloorrddeerr(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__lloorrddeerr((iinntt));; ttyyppeeddeeff vvooiidd ((**ddbb__eerrrrccaallll__ffccnn))((ccoonnsstt cchhaarr **,, cchhaarr **));; ddbb__eerrrrccaallll__ffccnn DDbbEEnnvv::::ggeett__eerrrrccaallll(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__eerrrrccaallll((ddbb__eerrrrccaallll__ffccnn));; FFIILLEE DDbbEEnnvv::::**ggeett__eerrrrffiillee(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__eerrrrffiillee((FFIILLEE **));; ccoonnsstt cchhaarr DDbbEEnnvv::::**ggeett__eerrrrppffxx(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__eerrrrppffxx((ccoonnsstt cchhaarr **));; iinntt DDbbEEnnvv::::ggeett__vveerrbboossee(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__vveerrbboossee((iinntt));; cchhaarr DDbbEEnnvv::::**ggeett__hhoommee(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__hhoommee((cchhaarr **));; cchhaarr DDbbEEnnvv::::**ggeett__lloogg__ddiirr(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__lloogg__ddiirr((cchhaarr **));; cchhaarr DDbbEEnnvv::::**ggeett__ttmmpp__ddiirr(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__ttmmpp__ddiirr((cchhaarr **));; cchhaarr DDbbEEnnvv::::****ggeett__ddaattaa__ddiirr(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__ddaattaa__ddiirr((cchhaarr ****));; DDbbLLoocckkTTaabb DDbbEEnnvv::::**ggeett__llkk__iinnffoo(()) ccoonnsstt;; uu__iinntt88__tt DDbbEEnnvv::::**ggeett__llkk__ccoonnfflliiccttss(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__llkk__ccoonnfflliiccttss((uu__iinntt88__tt **));; uu__iinntt3322__tt DDbbEEnnvv::::ggeett__llkk__mmooddeess(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__llkk__mmooddeess((uu__iinntt3322__tt));; uu__iinntt3322__tt DDbbEEnnvv::::ggeett__llkk__mmaaxx(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__llkk__mmaaxx((uu__iinntt3322__tt));; uu__iinntt3322__tt DDbbEEnnvv::::ggeett__llkk__ddeetteecctt(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__llkk__ddeetteecctt((uu__iinntt3322__tt));; DDbbLLoogg DDbbEEnnvv::::**ggeett__llgg__iinnffoo(()) ccoonnsstt;; uu__iinntt3322__tt DDbbEEnnvv::::ggeett__llgg__mmaaxx(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__llgg__mmaaxx((uu__iinntt3322__tt));; DDbbMMppooooll DDbbEEnnvv::::**ggeett__mmpp__iinnffoo(()) ccoonnsstt;; ssiizzee__tt DDbbEEnnvv::::ggeett__mmpp__mmmmaappssiizzee(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__mmpp__mmmmaappssiizzee((ssiizzee__tt));; ssiizzee__tt DDbbEEnnvv::::ggeett__mmpp__ssiizzee(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__mmpp__ssiizzee((ssiizzee__tt));; DDbbTTxxnnMMggrr DDbbEEnnvv::::**ggeett__ttxx__iinnffoo(()) ccoonnsstt;; uu__iinntt3322__tt DDbbEEnnvv::::ggeett__ttxx__mmaaxx(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__ttxx__mmaaxx((uu__iinntt3322__tt));; ttyyppeeddeeff iinntt ((**ttxx__rreeccoovveerr__ffccnn))((DDBB__LLOOGG **,, DDBBTT **,, DDBB__LLSSNN **,, iinntt,, vvooiidd **));; ttxx__rreeccoovveerr__ffccnn DDbbEEnnvv::::ggeett__ttxx__rreeccoovveerr(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__ttxx__rreeccoovveerr((ttxx__rreeccoovveerr__ffccnn));; uu__iinntt3322__tt DDbbEEnnvv::::ggeett__ffllaaggss(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__ffllaaggss((uu__iinntt3322__tt));; eennuumm EErrrroorrMMooddeell {{ EExxcceeppttiioonn,, EErrrroorrRReettuurrnn }};; vvooiidd DDbbEEnnvv::::sseett__eerrrroorr__mmooddeell((EErrrroorrMMooddeell));; EErrrroorrMMooddeell DDbbEEnnvv::::ggeett__eerrrroorr__mmooddeell(()) ccoonnsstt;; ccllaassss oossttrreeaamm** DDbbEEnnvv::::ggeett__eerrrroorr__ssttrreeaamm(()) ccoonnsstt;; vvooiidd DDbbEEnnvv::::sseett__eerrrroorr__ssttrreeaamm((ccllaassss oossttrreeaamm**));; DDEESSCCRRIIPPTTIIOONN The DB library is a family of classes that provides a mod- ular programming interface to transactions and record-ori- ented file access. The library includes support for transactions, locking, logging and file page caching, as well as various indexed access methods. Many of the classes (e.g., the file page caching class) are useful independent of the other DB classes, although some classes are explicitly based on other classes (e.g., transactions and logging). For a general description of the DB pack- age, see _d_b___i_n_t_r_o(3). The DbEnv class provides simple access to an underlying data structure, whose elements can be examined or changed using the _s_e_t__ or _g_e_t__ methods. The remainder of the man- ual page sometimes refers to these accesses using the underlying name, e.g., simply _l_o_r_d_e_r instead of _g_e_t___l_o_r_d_e_r and _s_e_t___l_o_r_d_e_r. The constructors set all elements of the underlying structure to zero. The constructor with three arguments has the effect of calling _D_b_E_n_v_:_:_a_p_p_i_n_i_t immedi- ately to initialize the application with default parame- ters. To delay the initialization, use the default con- structor. The various set_ methods can then be used to initialize the DbEnv, and finally, a call to _D_b_E_n_v_:_:_a_p_p_i_n_i_t should be made to initialize DB. Once the DB environment has been initialized by a call to _D_b_E_n_v_:_:_a_p_p_i_n_i_t, no set methods other than _s_e_t___e_r_r_p_f_x should be called. _a_p_p_i_n_i_t The _a_p_p_i_n_i_t method 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 consis- tent 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 _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(3), _D_b_L_o_c_k_T_a_b(3), _D_b_L_o_g(3), _D_b_M_- _p_o_o_l(3) and _D_b_T_x_n_M_g_r(3) for more information.) DB_INIT_LOCK Initialize the lock subsystem; see _D_b_L_o_c_k_T_a_b(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 fur- ther 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_E_n_v_:_:_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_E_n_v_:_:_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_T_a_b(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 which set meth- ods have been used. It is expected that applications will use a single DbEnv object as the argument to all of the subsystems in the DB package. The fields of the DbEnv object used by _a_p_p_i_n_i_t are described below. As references to the DbEnv object may be maintained by _a_p_p_i_n_i_t, it is necessary that the DbEnv object and memory it references be valid until the object is destroyed. The _d_b_e_n_v argu- ment 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 DbEnv object may be initial- ized, using the appropriate set method, before calling _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 method. In some cases, how- ever, 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. ostream* error_stream; The error_stream functions like the error file, allowing errors to be redirected to a C++ error stream. It is unwise to use both error_stream with nonzero values of either errcall or errfile. 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 _a_p_p_i_n_i_t may call (_D_b_L_o_c_k_- _T_a_b_:_:_o_p_e_n, _D_b_L_o_g_:_:_o_p_e_n, _D_b_M_p_o_o_l_:_:_o_p_e_n and _D_b_T_x_n_M_g_r_:_:_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 _a_p_p_i_n_i_t. For this reason the fields of the DbEnv object relevant to the subsystems being initialized must themselves be initial- ized before _a_p_p_i_n_i_t 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 DbEnv object: DbLockTab *lk_info; The return value of the _D_b_L_o_c_k_T_a_b_:_:_o_p_e_n(3) call. DbLog *lg_info; The return value of the _D_b_L_o_g_:_:_o_p_e_n(3) call. DbMpool *mp_info; The return value of the _D_b_M_p_o_o_l_:_:_o_p_e_n(3) call. DbTxnMgr *tx_info; The return value of the _D_b_T_x_n_M_g_r_:_:_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 DbEnv argument passed to the sub- system. 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 DbEnv argument filled in by the initial call to _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 DbEnv argument. The single exception to this rule is the _t_x___i_n_f_o field, which applications must explicitly specify to the _D_b_T_x_n_- _M_g_r_:_:_b_e_g_i_n, _D_b_T_x_n_M_g_r_:_:_c_h_e_c_k_p_o_i_n_t and _D_b_T_x_n_M_g_r_:_:_c_l_o_s_e func- tions. The _e_r_r_o_r___m_o_d_e_l field of DbEnv allows the user to config- ure the way errors are treated in DB. It can be changed at any time (e.g., after the call to _D_b_E_n_v_:_:_a_p_p_i_n_i_t). The error model is described in _D_b_E_x_c_e_p_t_i_o_n(3). FFIILLEE NNAAMMIINNGG The most important task of _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 _a_p_p_i_n_i_t method makes it possible to place database files in a single directory, or in multiple directories, grouped by their method 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 _a_p_p_i_n_i_t by specifying a value for the _d_b___h_o_m_e argument. There are more complex configurations 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 _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 _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 _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 _a_p_p_i_n_i_t may be specified using a configura- tion 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 _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) method 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 _D_b_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 method 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 _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 _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 _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: DbEnv::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 }; DbEnv::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 }; DbEnv::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 }; DbEnv::appinit("/a/database", config, ...); See the file _e_x_a_m_p_l_e_s___c_x_x_/_A_p_p_i_n_i_t_E_x_a_m_p_l_e_._c_p_p in the Db source distribution for a C++ language code example of how an application might use _a_p_p_i_n_i_t to configure its Db envi- ronment. EERRRROORRSS Methods marked as returning _e_r_r_n_o will, by default, throw an exception that encapsulates the error information. The default error behavior can be changed, see _D_b_E_x_c_e_p_t_i_o_n(3). The _a_p_p_i_n_i_t method may fail and throw a _D_b_E_x_c_e_p_t_i_o_n(3) or return _e_r_r_n_o for any of the errors specified for the following DB and library functions: Db::close(3), DbEnv::appexit(3), DbLock::unlink(3), DbLockTab::open(3), DbLog::compare(3), DbLog::get(3), DbLog::open(3), DbLog::unlink(3), DbMpool::open(3), DbMpool::unlink(3), DbTxnMgr::checkpoint(3), DbTxnMgr::open(3), DbTxn- Mgr::unlink(3), calloc(3), fclose(3), fcntl(2), fflush(3), fgets(3), fopen(3), malloc(3), memcpy(3), memset(3), real- loc(3), stat(2), strchr(3), strcmp(3), strcpy(3), strdup(3), strerror(3), strlen(3), strsep(3), and time(3). In addition, the _a_p_p_i_n_i_t method may fail and throw a _D_b_E_x_- _c_e_p_t_i_o_n(3) or 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_E_n_v_:_:_a_p_p_e_x_i_t method may fail and throw a _D_b_E_x_c_e_p_t_i_o_n(3) or return _e_r_r_n_o for any of the errors specified for the following DB and library functions: DbLockTab::close(3), DbLog::close(3), DbMpool::close(3), and DbTxn- Mgr::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___i_n_t_e_r_n_a_l(3), _d_b___t_h_r_e_a_d(3), _D_b(3), _D_b_c(3), _D_b_E_n_v(3), _D_b_E_x_c_e_p_t_i_o_n(3), _D_b_I_n_f_o(3), _D_b_L_o_c_k(3), _D_b_L_o_c_k_T_a_b(3), _D_b_L_o_g(3), _D_b_L_s_n(3), _D_b_M_p_o_o_l(3), _D_b_M_p_o_o_l_F_i_l_e(3), _D_b_t(3), _D_b_T_x_n(3), _D_b_T_x_n_M_g_r(3)