Import BSDDB 4.7.25 (as of svn r89086)
This commit is contained in:
Zachary Ware
174
docs/api_tcl/env_open.html
Normal file
174
docs/api_tcl/env_open.html
Normal file
@@ -0,0 +1,174 @@
|
||||
<!--$Id: env_open.html 63573 2008-05-23 21:43:21Z trent.nelson $-->
|
||||
<!--$Id: env_open.html 63573 2008-05-23 21:43:21Z trent.nelson $-->
|
||||
<!--Copyright (c) 1997,2008 Oracle. All rights reserved.-->
|
||||
<!--See the file LICENSE for redistribution information.-->
|
||||
<html>
|
||||
<head>
|
||||
<title>Berkeley DB: berkdb env</title>
|
||||
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
|
||||
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
|
||||
</head>
|
||||
<body bgcolor=white>
|
||||
<table width="100%"><tr valign=top>
|
||||
<td>
|
||||
<b><b>berkdb env</b></b>
|
||||
</td>
|
||||
<td align=right>
|
||||
<a href="../api_tcl/api_tcl.html"><img src="../images/api.gif" alt="API"></a>
|
||||
<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td>
|
||||
</tr></table>
|
||||
<hr size=1 noshade>
|
||||
<tt>
|
||||
<b><pre>berkdb env
|
||||
[-cachesize {gbytes bytes ncache}]
|
||||
[-create]
|
||||
[-data_dir dirname]
|
||||
[-encryptaes passwd]
|
||||
[-encryptany passwd]
|
||||
[-errfile filename]
|
||||
[-home directory]
|
||||
[-log_dir dirname]
|
||||
[-mode mode]
|
||||
[-private]
|
||||
[-recover]
|
||||
[-recover_fatal]
|
||||
[-shm_key shmid]
|
||||
[-system_mem]
|
||||
[-tmp_dir dirname]
|
||||
[-txn [nosync]]
|
||||
[-txn_max max]
|
||||
[-use_environ]
|
||||
[-use_environ_root]
|
||||
</pre></b>
|
||||
<b>Description(berkdb env)</b>
|
||||
<p>The <b>berkdb env</b> command opens and optionally creates a database
|
||||
environment. The returned environment handle is bound to a Tcl command
|
||||
of the form <b>envN</b>, where N is an integer starting at 0 (for
|
||||
example, env0 and env1). It is through this Tcl command that the script
|
||||
accesses the environment methods. The command automatically initializes
|
||||
the Shared Memory Buffer Pool subsystem. This subsystem is used
|
||||
whenever the application is using any Berkeley DB access method.</p>
|
||||
<p>The options are as follows:</p>
|
||||
<br>
|
||||
<b>-cachesize {gbytes bytes ncache}</b><ul compact><li>Set the size of the database's shared memory buffer pool (that is, the
|
||||
cache), to <b>gbytes</b> gigabytes plus <b>bytes</b>. The cache
|
||||
should be the size of the normal working data set of the application,
|
||||
with some small amount of additional memory for unusual situations.
|
||||
(Note: The working set is not the same as the number of simultaneously
|
||||
referenced pages, and should be quite a bit larger!)
|
||||
<p>The default cache size is 256KB, and may not be specified as less than
|
||||
20KB. Any cache size less than 500MB is automatically increased by 25%
|
||||
to account for buffer pool overhead; cache sizes larger than 500MB are
|
||||
used as specified.</p>
|
||||
<p>It is possible to specify caches to Berkeley DB that are large enough so that
|
||||
they cannot be allocated contiguously on some architectures; for example,
|
||||
some releases of Solaris limit the amount of memory that may be
|
||||
allocated contiguously by a process. If <b>ncache</b> is 0 or 1, the
|
||||
cache will be allocated contiguously in memory. If it is greater than
|
||||
1, the cache will be broken up into <b>ncache</b> equally sized
|
||||
separate pieces of memory.</p>
|
||||
<p>For information on tuning the Berkeley DB cache size, see
|
||||
<a href="../ref/am_conf/cachesize.html">Selecting a cache size</a>.</p></ul>
|
||||
<b>-create</b><ul compact><li>Cause Berkeley DB subsystems to create any underlying files, as necessary.</ul>
|
||||
<b>-data_dir dirname</b><ul compact><li>Specify the environment's data directory as described in
|
||||
<a href="../ref/env/naming.html">Berkeley DB File Naming</a>.</ul>
|
||||
<b>-encryptaes passwd</b><ul compact><li>Specify the database should be encrypted with the given password
|
||||
using the Rijndael/AES (also known as the Advanced Encryption Standard
|
||||
and Federal Information Processing Standard (FIPS) 197) algorithm.</ul>
|
||||
<b>-encryptany passwd</b><ul compact><li>Specify the already existing environment should be opened
|
||||
with the given password. This option is used if the environment is
|
||||
known to be encrypted, but the specific algorithm used is not known.</ul>
|
||||
<b>-errfile filename</b><ul compact><li><p>When an error occurs in the Berkeley DB library, a Berkeley DB error or an error
|
||||
return value is returned by the function. In some cases, however, the
|
||||
errno value may be insufficient to completely describe the cause of the
|
||||
error especially during initial application debugging.</p>
|
||||
<p>The <b>-errfile</b> argument is used to enhance the mechanism for
|
||||
reporting error messages to the application by specifying a file to be
|
||||
used for displaying additional Berkeley DB error messages. In some cases, when
|
||||
an error occurs, Berkeley DB will output an additional error message to the
|
||||
specified file reference.</p>
|
||||
<p>consist of the environment command name (for example, env0) and a colon
|
||||
(":"), an error string, and a trailing <newline>
|
||||
character.</p>
|
||||
<p>This error-logging enhancement does not slow performance or significantly
|
||||
increase application size, and may be run during normal operation as well
|
||||
as during application debugging.</p></ul>
|
||||
<b>-home directory</b><ul compact><li>The <b>-home</b> argument is described in
|
||||
<a href="../ref/env/naming.html">Berkeley DB File Naming</a>.</ul>
|
||||
<b>-log_dir dirname</b><ul compact><li>Specify the environment's logging file directory as described in
|
||||
<a href="../ref/env/naming.html">Berkeley DB File Naming</a>.</ul>
|
||||
<b>-mode mode</b><ul compact><li><p>On UNIX systems, or in IEEE/ANSI Std 1003.1 (POSIX) environments, all files created by Berkeley DB
|
||||
are created with mode <b>mode</b> (as described in <b>chmod</b>(2)) and
|
||||
modified by the process' umask value at the time of creation (see
|
||||
<b>umask</b>(2)). The group ownership of created files is based on
|
||||
the system and directory defaults, and is not further specified by Berkeley DB.
|
||||
If <b>mode</b> is 0, files are created readable and writable by both
|
||||
owner and group. On Windows systems, the mode argument is ignored.</p></ul>
|
||||
<b>-private</b><ul compact><li>Specify that the environment will only be accessed by a single process
|
||||
(although that process may be multithreaded). This flag has two effects
|
||||
on the Berkeley DB environment. First, all underlying data structures are
|
||||
allocated from per-process memory instead of from shared memory that is
|
||||
potentially accessible to more than a single process. Second, mutexes
|
||||
are only configured to work between threads.
|
||||
<p>This flag should not be specified if more than a single process is
|
||||
accessing the environment, as it is likely to cause database corruption
|
||||
and unpredictable behavior. For example, if both a server application
|
||||
and the Berkeley DB utility <a href="../utility/db_stat.html">db_stat</a> will access the environment, the
|
||||
<b>-private</b> option should not be specified.</p></ul>
|
||||
<b>-recover</b><ul compact><li>Run normal recovery on this environment before opening it for normal use.
|
||||
If this flag is set, the <b>-create</b> option must also be set because
|
||||
the regions will be removed and re-created.</ul>
|
||||
<b>-recover_fatal</b><ul compact><li>Run catastrophic recovery on this environment before opening it for
|
||||
normal use. If this flag is set, the <b>-create</b> option must also be
|
||||
set since the regions will be removed and re-created.</ul>
|
||||
<b>-shm_key key</b><ul compact><li>Specify a base segment ID for Berkeley DB environment shared memory regions
|
||||
created in system memory on systems supporting X/Open-style shared
|
||||
memory interfaces, for example, UNIX systems supporting shmget(2) and
|
||||
related System V IPC interfaces. See <a href="../ref/env/region.html">Shared Memory Regions</a> for more information.</ul>
|
||||
<b>-system_mem</b><ul compact><li>Allocate memory from system shared memory instead of memory backed by the
|
||||
filesystem. See <a href="../ref/env/region.html">Shared Memory Regions</a>
|
||||
for more information.</ul>
|
||||
<b>-tmp_dir dirname</b><ul compact><li>Specify the environment's tmp directory, as described in
|
||||
<a href="../ref/env/naming.html">Berkeley DB File Naming</a>.</ul>
|
||||
<b>-txn [nosync]</b><ul compact><li>Initialize the Transaction subsystem. This subsystem is used when
|
||||
recovery and atomicity of multiple operations and recovery are important.
|
||||
The <b>-txn</b> option implies the initialization of the logging
|
||||
and locking subsystems as well.
|
||||
<p>If the optional <b>nosync</b> argument is specified, the log will not
|
||||
be synchronously flushed on transaction commit. This means that
|
||||
transactions exhibit the ACI (atomicity, consistency, and isolation)
|
||||
properties, but not D (durability); that is, database integrity will be
|
||||
maintained, but it is possible that some number of the most recently
|
||||
committed transactions may be undone during recovery instead of being
|
||||
redone.</p>
|
||||
<p>The number of transactions that are potentially at risk is governed by
|
||||
how often the log is checkpointed (see <a href="../utility/db_checkpoint.html">db_checkpoint</a> for more
|
||||
information) and how many log updates can fit on a single log page.</p></ul>
|
||||
<b>-txn_max max</b><ul compact><li>Set the maximum number of simultaneous transactions that are supported
|
||||
by the environment, which bounds the size of backing files. When there
|
||||
are more than the specified number of concurrent transactions, calls to
|
||||
<i>env</i> <b>txn</b> will fail (until some active transactions complete).</ul>
|
||||
<b>-use_environ</b><ul compact><li>The Berkeley DB process' environment may be permitted to specify information
|
||||
to be used when naming files; see
|
||||
<a href="../ref/env/naming.html">Berkeley DB File Naming</a>.
|
||||
Because 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 <b>-use_environ</b> flag is set.</ul>
|
||||
<b>-use_environ_root</b><ul compact><li>The Berkeley DB process' environment may be permitted to specify information
|
||||
to be used when naming files; see
|
||||
<a href="../ref/env/naming.html">Berkeley DB File Naming</a>.
|
||||
As permitting users to specify which files are used can create security
|
||||
problems, if the <b>-use_environ_root</b> flag is set, environment
|
||||
information will be used for file naming only for users with appropriate
|
||||
permissions (for example, users with a user-ID of 0 on IEEE/ANSI Std 1003.1 (POSIX)
|
||||
systems).</ul>
|
||||
<br>
|
||||
<p>The <b>berkdb env</b> command returns an environment handle on success.</p>
|
||||
<p>In the case of error, a Tcl error is thrown.</p>
|
||||
</tt>
|
||||
<table width="100%"><tr><td><br></td><td align=right>
|
||||
<a href="../api_tcl/api_tcl.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a>
|
||||
</td></tr></table>
|
||||
<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user