mirror of
https://github.com/MariaDB/server.git
synced 2025-01-18 04:53:01 +01:00
168 lines
9.3 KiB
HTML
168 lines
9.3 KiB
HTML
<!--$Id: env_open.so,v 11.21 2000/06/05 15:17:24 sue Exp $-->
|
|
<!--$Id: m4.tcl,v 11.17 2000/04/24 17:31:11 sue Exp $-->
|
|
<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.-->
|
|
<!--All rights reserved.-->
|
|
<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,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
|
|
</head>
|
|
<body bgcolor=white>
|
|
<a name="2"><!--meow--></a>
|
|
<table><tr valign=top>
|
|
<td>
|
|
<h1><b>berkdb env</b></h1>
|
|
</td>
|
|
<td width="1%">
|
|
<a href="../api_tcl/tcl_index.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>
|
|
<h3><pre>berkdb env
|
|
[-cachesize {gbytes bytes ncache}]
|
|
[-create]
|
|
[-data_dir dirname]
|
|
[-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></h3>
|
|
<h1>Description</h1>
|
|
<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 (e.g., 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>The options are as follows:
|
|
<p><dl compact>
|
|
<p><dt>-cachesize {gbytes bytes ncache}<dd>Set the size of the database's shared memory buffer pool, i.e., 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>It is possible to specify caches to Berkeley DB that are large enough so that
|
|
they cannot be allocated contiguously on some architectures, e.g., 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>For information on tuning the Berkeley DB cache size, see
|
|
<a href="../ref/am_conf/cachesize.html">Selecting a cache size</a>.
|
|
<p><dt>-create<dd>Cause Berkeley DB subsystems to create any underlying files, as necessary.
|
|
<p><dt>-data_dir dirname<dd>Specify the environment's data directory as described in
|
|
<a href="../ref/env/naming.html">Berkeley DB File Naming</a>.
|
|
<p><dt>-errfile filename<dd>
|
|
<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>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>The error message will consist of the environment command name (e.g., env0)
|
|
and a colon (":"), an error string, and a trailing <newline>
|
|
character.
|
|
<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><dt>-home directory<dd>The <b>-home</b> argument is described in
|
|
<a href="../ref/env/naming.html">Berkeley DB File Naming</a>.
|
|
<p><dt>-log_dir dirname<dd>Specify the environment's logging file directory as described in
|
|
<a href="../ref/env/naming.html">Berkeley DB File Naming</a>.
|
|
<p><dt>-mode mode<dd>
|
|
<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 writeable by both
|
|
owner and group. On Windows systems, the mode argument is ignored.
|
|
<p><dt>-private<dd>Specify that the environment will only be accessed by a single process
|
|
(although that process may be multi-threaded). 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, e.g., 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><dt>-recover<dd>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 since
|
|
the regions will be removed and recreated.
|
|
<p><dt>-recover_fatal<dd>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 recreated.
|
|
<p><dt>-shm_key key<dd>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, e.g., 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.
|
|
<p><dt>-system_mem<dd>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.
|
|
<p><dt>-tmp_dir dirname<dd>Specify the environment's tmp directory as described in
|
|
<a href="../ref/env/naming.html">Berkeley DB File Naming</a>.
|
|
<p><dt>-txn [nosync]<dd>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 or prepare. This means that
|
|
transactions exhibit the ACI (atomicity, consistency and isolation)
|
|
properties, but not D (durability), i.e., 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>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><dt>-txn_max max<dd>Set the maximum number of simultaneous transactions that are supported
|
|
by the environment. This 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).
|
|
<p><dt>-use_environ<dd>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, environment information will be used in file
|
|
naming for all users only if the <b>-use_environ</b> flag is set.
|
|
<p><dt>-use_environ_root<dd>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 (e.g., on IEEE/ANSI Std 1003.1 (POSIX) systems, users with a
|
|
user-ID of 0).
|
|
</dl>
|
|
<p>The <b>berkdb env</b> command returns an environment handle on success.
|
|
<p>In the case of error, a Tcl error is thrown.
|
|
</tt>
|
|
<table><tr><td><br></td><td width="1%">
|
|
<a href="../api_tcl/tcl_index.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><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
|
|
</body>
|
|
</html>
|