1<!--$Id: env_open.so,v 10.114 2008/04/29 22:42:03 mbrey Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB: DbEnv::open</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td> 13<b>DbEnv::open</b> 14</td> 15<td align=right> 16<a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a> 17<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td> 18</tr></table> 19<hr size=1 noshade> 20<tt> 21<b><pre> 22#include <db_cxx.h> 23<p> 24int 25DbEnv::open(const char *db_home, u_int32_t flags, int mode); 26<p> 27int 28DbEnv::get_home(const char **homep); 29<p> 30int 31DbEnv::get_open_flags(u_int32_t *flagsp); 32</pre></b> 33<hr size=1 noshade> 34<b>Description: DbEnv::open</b> 35<p>The DbEnv::open method opens a Berkeley DB environment. It provides a 36structure for creating a consistent environment for processes using one 37or more of the features of Berkeley DB.</p> 38<p>The DbEnv::open method 39either returns a non-zero error value 40or throws an exception that encapsulates a non-zero error value on 41failure, and returns 0 on success. 42If DbEnv::open fails, the <a href="../api_cxx/env_close.html">DbEnv::close</a> method must be called 43to discard the <a href="../api_cxx/env_class.html">DbEnv</a> handle. 44</p> 45<b>Parameters</b> <br> 46 <b>db_home</b><ul compact><li>The <b>db_home</b> parameter is the database environment's home 47directory. For more information on <b>db_home</b>, and filename 48resolution in general, see <a href="../ref/env/naming.html">Berkeley DB File 49Naming</a>. The environment variable <b>DB_HOME</b> may be used as 50the path of the database home, as described in 51<a href="../ref/env/naming.html">Berkeley DB File Naming</a>.</ul> 52<p>When using a Unicode build on Windows (the default), the <b>db_home</b> 53argument will be interpreted as a UTF-8 string, which is equivalent to 54ASCII for Latin characters.</p> 55 <b>flags</b><ul compact><li>The <b>flags</b> parameter specifies the subsystems that are initialized 56and how the application's environment affects Berkeley DB file naming, among 57other things. 58The <b>flags</b> parameter must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one 59or more of the following values: 60<p>Because there are a large number of flags that can be specified, they 61have been grouped together by functionality. The first group of flags 62indicates which of the Berkeley DB subsystems should be initialized.</p> 63<p>The choice of subsystems initialized for a Berkeley DB database environment 64is specified by the thread of control initially creating the 65environment. Any subsequent thread of control joining the environment 66will automatically be configured to use the same subsystems as were 67created in the environment (unless the thread of control requests a 68subsystem not available in the environment, which will fail). 69Applications joining an environment, able to adapt to whatever 70subsystems have been configured in the environment, should open the 71environment without specifying any subsystem flags. Applications 72joining an environment, requiring specific subsystems from their 73environments, should open the environment specifying those specific 74subsystem flags.</p> 75<br> 76<b><a name="DB_INIT_CDB">DB_INIT_CDB</a></b><ul compact><li>Initialize locking for the <a href="../ref/cam/intro.html">Berkeley DB Concurrent Data Store</a> 77product. In this mode, Berkeley DB provides multiple reader/single writer 78access. The only other subsystem that should be specified with the 79DB_INIT_CDB flag is DB_INIT_MPOOL.</ul> 80<b><a name="DB_INIT_LOCK">DB_INIT_LOCK</a></b><ul compact><li>Initialize the locking subsystem. This subsystem should be used when 81multiple processes or threads are going to be reading and writing a 82Berkeley DB database, so that they do not interfere with each other. If all 83threads are accessing the database(s) read-only, locking is unnecessary. 84When the DB_INIT_LOCK flag is specified, it is usually necessary 85to run a deadlock detector, as well. See <a href="../utility/db_deadlock.html">db_deadlock</a> and 86<a href="../api_cxx/lock_detect.html">DbEnv::lock_detect</a> for more information.</ul> 87<b><a name="DB_INIT_LOG">DB_INIT_LOG</a></b><ul compact><li>Initialize the logging subsystem. This subsystem should be used when 88recovery from application or system failure is necessary. If the log 89region is being created and log files are already present, the log files 90are reviewed; subsequent log writes are appended to the end of the log, 91rather than overwriting current log entries.</ul> 92<b><a name="DB_INIT_MPOOL">DB_INIT_MPOOL</a></b><ul compact><li>Initialize the shared memory buffer pool subsystem. This subsystem 93should be used whenever an application is using any Berkeley DB access 94method.</ul> 95<b><a name="DB_INIT_REP">DB_INIT_REP</a></b><ul compact><li>Initialize the replication subsystem. This subsystem 96should be used whenever an application plans on using replication. 97The DB_INIT_REP flag requires the DB_INIT_TXN and 98DB_INIT_LOCK flags also be configured.</ul> 99<b><a name="DB_INIT_TXN">DB_INIT_TXN</a></b><ul compact><li>Initialize the transaction subsystem. This subsystem should be used 100when recovery and atomicity of multiple operations are important. The 101DB_INIT_TXN flag implies the DB_INIT_LOG flag.</ul> 102<br> 103<p>The second group of flags govern what recovery, if any, is performed when 104the environment is initialized:</p> 105<br> 106<b><a name="DB_RECOVER">DB_RECOVER</a></b><ul compact><li>Run normal recovery on this environment before opening it for normal 107use. If this flag is set, the DB_CREATE and DB_INIT_TXN 108flags must also be set, because the regions will be removed and 109re-created, and transactions are required for application recovery.</ul> 110<b><a name="DB_RECOVER_FATAL">DB_RECOVER_FATAL</a></b><ul compact><li>Run catastrophic recovery on this environment before opening it for 111normal use. If this flag is set, the DB_CREATE and 112DB_INIT_TXN flags must also be set, because the regions will be 113removed and re-created, and transactions are required for application 114recovery.</ul> 115<br> 116<p>A standard part of the recovery process is to remove the existing Berkeley DB 117environment and create a new one in which to perform recovery. If the 118thread of control performing recovery does not specify the correct 119region initialization information (for example, the correct memory pool 120cache size), the result can be an application running in an environment 121with incorrect cache and other subsystem sizes. For this reason, the 122thread of control performing recovery should specify correct 123configuration information before calling the DbEnv::open method; or it 124should remove the environment after recovery is completed, leaving 125creation of the correctly sized environment to a subsequent call to 126DbEnv::open.</p> 127<p>All Berkeley DB recovery processing must be single-threaded; that is, only a 128single thread of control may perform recovery or access a Berkeley DB 129environment while recovery is being performed. Because it is not an 130error to specify DB_RECOVER for an environment for which no 131recovery is required, it is reasonable programming practice for the 132thread of control responsible for performing recovery and creating the 133environment to always specify the DB_CREATE and 134DB_RECOVER flags during startup.</p> 135<p>The DbEnv::open function returns successfully if DB_RECOVER 136or DB_RECOVER_FATAL is specified and no log files exist, so it 137is necessary to ensure that all necessary log files are present before 138running recovery. For further information, consult <a href="../utility/db_archive.html">db_archive</a> 139and <a href="../utility/db_recover.html">db_recover</a>.</p> 140<p>The third group of flags govern file-naming extensions in the environment:</p> 141<br> 142<a name="2"><!--meow--></a> 143<b><a name="DB_USE_ENVIRON">DB_USE_ENVIRON</a></b><ul compact><li>The Berkeley DB process' environment may be permitted to specify information 144to be used when naming files; see <a href="../ref/env/naming.html">Berkeley DB File Naming</a>. Because permitting users to specify which files 145are used can create security problems, environment information will be 146used in file naming for all users only if the DB_USE_ENVIRON 147flag is set.</ul> 148<b><a name="DB_USE_ENVIRON_ROOT">DB_USE_ENVIRON_ROOT</a></b><ul compact><li>The Berkeley DB process' environment may be permitted to specify information 149to be used when naming files; see <a href="../ref/env/naming.html">Berkeley DB File Naming</a>. Because permitting users to specify which files 150are used can create security problems, if the 151DB_USE_ENVIRON_ROOT flag is set, environment information will 152be used for file naming only for users with appropriate permissions (for 153example, users with a user-ID of 0 on UNIX systems).</ul> 154<br> 155<p>Finally, there are a few additional unrelated flags:</p> 156<br> 157<b><a name="DB_CREATE">DB_CREATE</a></b><ul compact><li>Cause Berkeley DB subsystems to create any underlying files, as necessary.</ul> 158<b><a name="DB_LOCKDOWN">DB_LOCKDOWN</a></b><ul compact><li>Lock shared Berkeley DB environment files and memory-mapped databases into 159memory.</ul> 160<b><a name="DB_PRIVATE">DB_PRIVATE</a></b><ul compact><li>Allocate region memory from the heap instead of from memory backed by 161the filesystem or system shared memory. 162<p>This flag implies the environment will only be accessed by a single 163process (although that process may be multithreaded). This flag has two 164effects on the Berkeley DB environment. First, all underlying data structures 165are allocated from per-process memory instead of from shared memory that 166is accessible to more than a single process. Second, mutexes are only 167configured to work between threads.</p> 168<p>This flag should not be specified if more than a single process is 169accessing the environment because it is likely to cause database 170corruption and unpredictable behavior. For example, if both a server 171application and Berkeley DB utilities (for example, <a href="../utility/db_archive.html">db_archive</a>, 172<a href="../utility/db_checkpoint.html">db_checkpoint</a> or <a href="../utility/db_stat.html">db_stat</a>) are expected to access the 173environment, the DB_PRIVATE flag should not be specified.</p> 174<p>See <a href="../ref/env/region.html">Shared Memory Regions</a> for more 175information.</p></ul> 176<b><a name="DB_REGISTER">DB_REGISTER</a></b><ul compact><li>Check to see if recovery needs to be performed before opening the 177database environment. (For this check to be accurate, all processes 178using the environment must specify DB_REGISTER when opening the 179environment.) If recovery needs to be performed for any reason 180(including the initial use of the DB_REGISTER flag), and 181DB_RECOVER is also specified, recovery will be performed and the 182open will proceed normally. If recovery needs to be performed and 183DB_RECOVER is not specified, <a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a> will be 184returned. If recovery does not need to be performed, the 185DB_RECOVER flag will be ignored. See 186<a href="../ref/transapp/app.html">Architecting Transactional Data Store 187applications</a> for more information.</ul> 188<b><a name="DB_SYSTEM_MEM">DB_SYSTEM_MEM</a></b><ul compact><li>Allocate region memory from system shared memory instead of from heap 189memory or memory backed by the filesystem. 190<p>See <a href="../ref/env/region.html">Shared Memory Regions</a> for more 191information.</p></ul> 192<b><a name="DB_THREAD">DB_THREAD</a></b><ul compact><li>Cause the <a href="../api_cxx/env_class.html">DbEnv</a> handle returned by DbEnv::open to be 193<i>free-threaded</i>; that is, concurrently usable by multiple 194threads in the address space. The DB_THREAD flag should be specified 195if the <a href="../api_cxx/env_class.html">DbEnv</a> handle will be concurrently used by more than one 196thread in the process, or if any <a href="../api_cxx/db_class.html">Db</a> handles opened in the scope 197of the <a href="../api_cxx/env_class.html">DbEnv</a> handle will be concurrently used by more than one 198thread in the process. 199<p>This flag is required when using the Replication Manager.</p></ul> 200<br></ul> 201 <b>mode</b><ul compact><li>On Windows systems, the mode parameter is ignored. 202<p>On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, files created by Berkeley DB 203are created with mode <b>mode</b> (as described in <b>chmod</b>(2)) 204and modified by the process' umask value at the time of creation (see 205<b>umask</b>(2)). Created files are owned by the process owner; the 206group ownership of created files is based on the system and directory 207defaults, and is not further specified by Berkeley DB. System shared memory 208segments created by Berkeley DB are created with mode <b>mode</b>, unmodified 209by the process' umask value. If <b>mode</b> is 0, Berkeley DB will use a 210default mode of readable and writable by both owner and group.</p></ul> 211<br> 212<a name="3"><!--meow--></a> 213<br><b>Errors</b> 214<p>The DbEnv::open method 215may fail and throw 216<a href="../api_cxx/except_class.html">DbException</a>, 217encapsulating one of the following non-zero errors, or return one of 218the following non-zero errors:</p> 219<br> 220<b>DB_RUNRECOVERY</b><ul compact><li>The DB_REGISTER flag was specified, a failure has occurred, and no 221recovery flag was specified.</ul> 222<br> 223<br> 224<b>DB_VERSION_MISMATCH</b><ul compact><li>The version of the Berkeley DB library doesn't match the version that created 225the database environment.</ul> 226<br> 227<br> 228<b>EAGAIN</b><ul compact><li>The shared memory region was locked and (repeatedly) unavailable.</ul> 229<br> 230<br> 231<b>EINVAL</b><ul compact><li>If the DB_THREAD flag was specified and fast mutexes are not 232available for this architecture; 233The DB_HOME or TMPDIR environment variables were set, but empty; 234An incorrectly formatted <b>NAME VALUE</b> entry or line was found; or if an 235invalid flag value or parameter was specified.</ul> 236<br> 237<br> 238<b>ENOSPC</b><ul compact><li>HP-UX only: 239Due to the constraints of the PA-RISC memory architecture, HP-UX does not 240allow a process to map a file into its address space multiple times. 241For this reason, each Berkeley DB environment may be opened only once by a 242process on HP-UX; that is, calls to DbEnv::open will fail if the 243specified Berkeley DB environment has been opened and not subsequently closed.</ul> 244<br> 245<br> 246<b>ENOENT</b><ul compact><li>The file or directory does not exist.</ul> 247<br> 248<hr size=1 noshade> 249<b>Description: DbEnv::get_home</b> 250<p>The DbEnv::get_home method returns the database environment home directory.</p> 251<p>The DbEnv::get_home method may be called at any time during the life of the 252application.</p> 253<hr size=1 noshade> 254<b>Description: DbEnv::get_open_flags</b> 255<p>The DbEnv::get_open_flags method returns the open method flags originally used to create the database environment.</p> 256<p>The DbEnv::get_open_flags method may not be called before the DbEnv::open method is called.</p> 257<p>The DbEnv::get_open_flags method 258either returns a non-zero error value 259or throws an exception that encapsulates a non-zero error value on 260failure, and returns 0 on success. 261</p> 262<b>Parameters</b> <br> 263 <b>flagsp</b><ul compact><li>The DbEnv::get_open_flags method returns the 264open method flags originally used to create the database environment in <b>flagsp</b>.</ul> 265<br> 266<hr size=1 noshade> 267<br><b>Class</b> 268<a href="../api_cxx/env_class.html">DbEnv</a> 269<br><b>See Also</b> 270<a href="../api_cxx/env_list.html">Database Environments and Related Methods</a> 271</tt> 272<table width="100%"><tr><td><br></td><td align=right> 273<a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> 274</td></tr></table> 275<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 276</body> 277</html> 278