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