Import BSDDB 4.7.25 (as of svn r89086)
This commit is contained in:
Zachary Ware
952
docs/gsg_txn/CXX/enabletxn.html
Normal file
952
docs/gsg_txn/CXX/enabletxn.html
Normal file
@@ -0,0 +1,952 @@
|
||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||||
<title>Chapter 2. Enabling Transactions</title>
|
||||
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.62.4" />
|
||||
<link rel="home" href="index.html" title="Getting Started with Berkeley DB Transaction Processing" />
|
||||
<link rel="up" href="index.html" title="Getting Started with Berkeley DB Transaction Processing" />
|
||||
<link rel="previous" href="perftune-intro.html" title="Performance Tuning" />
|
||||
<link rel="next" href="envopen.html" title="Opening a Transactional Environment and Database " />
|
||||
</head>
|
||||
<body>
|
||||
<div class="navheader">
|
||||
<table width="100%" summary="Navigation header">
|
||||
<tr>
|
||||
<th colspan="3" align="center">Chapter 2. Enabling Transactions</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="20%" align="left"><a accesskey="p" href="perftune-intro.html">Prev</a> </td>
|
||||
<th width="60%" align="center"> </th>
|
||||
<td width="20%" align="right"> <a accesskey="n" href="envopen.html">Next</a></td>
|
||||
</tr>
|
||||
</table>
|
||||
<hr />
|
||||
</div>
|
||||
<div class="chapter" lang="en" xml:lang="en">
|
||||
<div class="titlepage">
|
||||
<div>
|
||||
<div>
|
||||
<h2 class="title"><a id="enabletxn"></a>Chapter 2. Enabling Transactions</h2>
|
||||
</div>
|
||||
</div>
|
||||
<div></div>
|
||||
</div>
|
||||
<div class="toc">
|
||||
<p>
|
||||
<b>Table of Contents</b>
|
||||
</p>
|
||||
<dl>
|
||||
<dt>
|
||||
<span class="sect1">
|
||||
<a href="enabletxn.html#environments">Environments</a>
|
||||
</span>
|
||||
</dt>
|
||||
<dd>
|
||||
<dl>
|
||||
<dt>
|
||||
<span class="sect2">
|
||||
<a href="enabletxn.html#filenaming">File Naming</a>
|
||||
</span>
|
||||
</dt>
|
||||
<dt>
|
||||
<span class="sect2">
|
||||
<a href="enabletxn.html#errorsupport">Error Support</a>
|
||||
</span>
|
||||
</dt>
|
||||
<dt>
|
||||
<span class="sect2">
|
||||
<a href="enabletxn.html#sharedmemory">Shared Memory Regions</a>
|
||||
</span>
|
||||
</dt>
|
||||
<dt>
|
||||
<span class="sect2">
|
||||
<a href="enabletxn.html#security">Security Considerations</a>
|
||||
</span>
|
||||
</dt>
|
||||
</dl>
|
||||
</dd>
|
||||
<dt>
|
||||
<span class="sect1">
|
||||
<a href="envopen.html">Opening a Transactional Environment and
|
||||
Database
|
||||
|
||||
|
||||
</a>
|
||||
</span>
|
||||
</dt>
|
||||
</dl>
|
||||
</div>
|
||||
<p>
|
||||
In order to use transactions with your application, you must turn them
|
||||
on. To do this you must:
|
||||
</p>
|
||||
<div class="itemizedlist">
|
||||
<ul type="disc">
|
||||
<li>
|
||||
<p>
|
||||
Use an
|
||||
environment (see <a href="enabletxn.html#environments">Environments</a> for details).
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
Turn on transactions for your environment.
|
||||
|
||||
|
||||
|
||||
<span>
|
||||
You do this by providing the <tt class="literal">DB_INIT_TXN</tt>
|
||||
flag to the
|
||||
<tt class="methodname">DbEnv::open()</tt>
|
||||
|
||||
method.
|
||||
</span>
|
||||
|
||||
<span>
|
||||
Note that initializing the transactional subsystem implies that
|
||||
the logging subsystem is also initialized. Also, note that
|
||||
if you do not initialize transactions when you first create
|
||||
your environment, then you cannot use transactions for that
|
||||
environment after that. This is because DB
|
||||
allocates certain structures needed for transactional
|
||||
locking that are not available if the environment is
|
||||
created without transactional support.
|
||||
</span>
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
Initialize the in-memory cache by
|
||||
<span>
|
||||
passing the <tt class="literal">DB_INIT_MPOOL</tt>
|
||||
flag to the
|
||||
<tt class="methodname">DbEnv::open()</tt>
|
||||
|
||||
method.
|
||||
</span>
|
||||
|
||||
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
Initialize the locking subsystem. This is what provides locking for concurrent applications. It also is used
|
||||
to perform deadlock detection. See <a href="txnconcurrency.html">Concurrency</a>
|
||||
for more information.
|
||||
</p>
|
||||
<p>
|
||||
You initialize the locking subsystem by
|
||||
<span>
|
||||
passing the <tt class="literal">DB_INIT_LOCK</tt>
|
||||
flag to the
|
||||
<tt class="methodname">DbEnv::open()</tt>
|
||||
|
||||
method.
|
||||
</span>
|
||||
|
||||
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
Initialize the logging subsystem. While this is enabled by
|
||||
default for transactional applications, we suggest that
|
||||
you explicitly initialize it anyway for the purposes of code readability. The logging
|
||||
subsystem is what provides your transactional application its durability guarantee, and it is required for
|
||||
recoverability purposes. See <a href="filemanagement.html">Managing DB Files</a>
|
||||
for more information.
|
||||
</p>
|
||||
<p>
|
||||
You initialize the logging subsystem by
|
||||
<span>
|
||||
passing the <tt class="literal">DB_INIT_LOG</tt>
|
||||
flag to the
|
||||
<tt class="methodname">DbEnv::open()</tt>
|
||||
|
||||
method.
|
||||
</span>
|
||||
|
||||
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
<span>
|
||||
Transaction-enable your databases.
|
||||
</span>
|
||||
<span>
|
||||
If you are using the base API, transaction-enable your databases.
|
||||
</span>
|
||||
You do this by
|
||||
|
||||
|
||||
<span>
|
||||
encapsulating the database open in a transaction.
|
||||
</span>
|
||||
|
||||
|
||||
|
||||
<span>
|
||||
Note that the common practice is for auto commit to be used to
|
||||
transaction-protect the database open. To use auto-commit, you
|
||||
must still enable transactions as described here, but you do
|
||||
not have to explicitly use a transaction when you open your
|
||||
database. An example of this is given in the next section.
|
||||
</span>
|
||||
</p>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="sect1" lang="en" xml:lang="en">
|
||||
<div class="titlepage">
|
||||
<div>
|
||||
<div>
|
||||
<h2 class="title" style="clear: both"><a id="environments"></a>Environments</h2>
|
||||
</div>
|
||||
</div>
|
||||
<div></div>
|
||||
</div>
|
||||
<p>
|
||||
For simple DB applications, environments are optional. However, in
|
||||
order to transaction protect your database operations, you must use an
|
||||
environment.
|
||||
</p>
|
||||
<p>
|
||||
An <span class="emphasis"><em>environment</em></span>, represents an
|
||||
encapsulation of one or more databases and any associated log and
|
||||
region files. They are used to support multi-threaded
|
||||
and multi-process applications by allowing different threads of
|
||||
control to share the in-memory cache, the locking tables, the
|
||||
logging subsystem, and the file namespace. By sharing these things,
|
||||
your concurrent application is more efficient than if each thread
|
||||
of control had to manage these resources on its own.
|
||||
</p>
|
||||
<p>
|
||||
By default all DB databases are backed by files on disk. In
|
||||
addition to these files, transactional DB applications create
|
||||
logs that are also by default stored on disk (they can optionally
|
||||
be backed using shared memory). Finally, transactional
|
||||
DB applications also create and use shared-memory regions that
|
||||
are also typically backed by the filesystem. But like databases and
|
||||
logs, the regions can be maintained strictly in-memory if your
|
||||
application requires it. For an example of an application that
|
||||
manages all environment files in-memory, see
|
||||
<span><a href="inmem_txnexample_c.html">In-Memory Transaction Example</a>.</span>
|
||||
|
||||
|
||||
|
||||
</p>
|
||||
<div class="sect2" lang="en" xml:lang="en">
|
||||
<div class="titlepage">
|
||||
<div>
|
||||
<div>
|
||||
<h3 class="title"><a id="filenaming"></a>File Naming</h3>
|
||||
</div>
|
||||
</div>
|
||||
<div></div>
|
||||
</div>
|
||||
<p>
|
||||
In order to operate, your DB application must be able to
|
||||
locate its database files, log files, and region files. If these
|
||||
are stored in the filesystem, then you must tell DB where
|
||||
they are located (a number of mechanisms exist that allow you to
|
||||
identify the location of these files – see below). Otherwise,
|
||||
by default they are located in the current working directory.
|
||||
</p>
|
||||
<div class="sect3" lang="en" xml:lang="en">
|
||||
<div class="titlepage">
|
||||
<div>
|
||||
<div>
|
||||
<h4 class="title"><a id="envhome"></a>Specifying the Environment Home Directory</h4>
|
||||
</div>
|
||||
</div>
|
||||
<div></div>
|
||||
</div>
|
||||
<p>
|
||||
The environment home directory is used to determine where
|
||||
DB files are located. Its location
|
||||
is identified using one of the following mechanisms, in the
|
||||
following order of priority:
|
||||
</p>
|
||||
<div class="itemizedlist">
|
||||
<ul type="disc">
|
||||
<li>
|
||||
<p>
|
||||
If no information is given as to where to put the
|
||||
environment home, then the current working
|
||||
directory is used.
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
If a home directory is specified on the
|
||||
|
||||
<tt class="methodname">DbEnv::open()</tt>
|
||||
|
||||
<span>method,</span>
|
||||
|
||||
then that location is always used for the environment
|
||||
home.
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
If a home directory is not supplied to
|
||||
|
||||
<span><tt class="methodname">DbEnv::open()</tt>, </span>
|
||||
|
||||
then the directory identified by the <tt class="literal">DB_HOME</tt> environment variable
|
||||
is used <span class="emphasis"><em>if</em></span> you specify
|
||||
<span>
|
||||
either the <tt class="literal">DB_USE_ENVIRON</tt> or
|
||||
<tt class="literal">DB_USE_ENVIRON_ROOT</tt> flags to the
|
||||
|
||||
<tt class="methodname">DbEnv::open()</tt>
|
||||
method. Both flags allow you to identify the
|
||||
path to the environment's home directory
|
||||
using the <tt class="literal">DB_HOME</tt> environment variable. However,
|
||||
<tt class="literal">DB_USE_ENVIRON_ROOT</tt> is honored only if the
|
||||
process is run with root or administrative privileges.
|
||||
</span>
|
||||
|
||||
|
||||
</p>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div class="sect3" lang="en" xml:lang="en">
|
||||
<div class="titlepage">
|
||||
<div>
|
||||
<div>
|
||||
<h4 class="title"><a id="filelocation"></a>Specifying File Locations</h4>
|
||||
</div>
|
||||
</div>
|
||||
<div></div>
|
||||
</div>
|
||||
<p>
|
||||
By default, all DB files are created relative to the environment
|
||||
home directory. For example, suppose your environment home is in
|
||||
<tt class="literal">/export/myAppHome</tt>. Also suppose you name your database
|
||||
<span><tt class="literal">data/myDatabase.db</tt>.</span>
|
||||
|
||||
Then in this case, the database is placed in:
|
||||
<span><tt class="literal">/export/myAppHome/data/myDatabase.db</tt>.</span>
|
||||
|
||||
</p>
|
||||
<p>
|
||||
That said, DB always defers to absolute pathnames.
|
||||
This means that if you provide an absolute filename when you
|
||||
name your database, then that file is <span class="emphasis"><em>not</em></span>
|
||||
placed relative to the environment home directory. Instead, it
|
||||
is placed in the exact location that you specified for the
|
||||
filename.
|
||||
</p>
|
||||
<p>
|
||||
On UNIX systems, an absolute pathname is a name that begins with a
|
||||
forward slash ('/'). On Windows systems, an absolute pathname is a
|
||||
name that begins with one of the following:
|
||||
</p>
|
||||
<div class="itemizedlist">
|
||||
<ul type="disc">
|
||||
<li>
|
||||
<p>
|
||||
A backslash ('\').
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
Any alphabetic letter, followed by a colon (':'), followed
|
||||
by a backslash ('\').
|
||||
</p>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
|
||||
<h3 class="title">Note</h3>
|
||||
<p>
|
||||
Try not to use absolute path names for your
|
||||
environment's files. Under certain recovery scenarios, absolute path names can
|
||||
render your environment unrecoverable. This occurs if you are attempting to recover
|
||||
you environment on a system that does not support the absolute path name that you used.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="sect3" lang="en" xml:lang="en">
|
||||
<div class="titlepage">
|
||||
<div>
|
||||
<div>
|
||||
<h4 class="title"><a id="splittingdata"></a>Identifying Specific File Locations</h4>
|
||||
</div>
|
||||
</div>
|
||||
<div></div>
|
||||
</div>
|
||||
<p>
|
||||
As described in the previous sections, DB will place all its
|
||||
files in or relative to the environment home directory.
|
||||
You can also cause a
|
||||
specific database file to be placed in a particular location by
|
||||
using an absolute path name for its name. In this
|
||||
situation, the environment's home directory is not
|
||||
considered when naming the file.
|
||||
</p>
|
||||
<p>
|
||||
It is frequently desirable to place database, log, and region files on separate
|
||||
disk drives. By spreading I/O across multiple drives, you
|
||||
can increase parallelism and improve throughput.
|
||||
Additionally, by placing log files and database files on
|
||||
separate drives, you improve your application's
|
||||
reliability by providing your application with a greater
|
||||
chance of surviving a disk failure.
|
||||
</p>
|
||||
<p>
|
||||
You can cause DB's files to be placed in specific
|
||||
locations using the following mechanisms:
|
||||
</p>
|
||||
<div class="informaltable">
|
||||
<table border="1" width="80%">
|
||||
<colgroup>
|
||||
<col />
|
||||
<col />
|
||||
</colgroup>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>File Type</th>
|
||||
<th>To Override</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>database files</td>
|
||||
<td>
|
||||
<p>
|
||||
You can cause database files to be created
|
||||
in a directory other than the
|
||||
environment home by using the
|
||||
|
||||
<tt class="methodname">DbEnv::set_data_dir()</tt>
|
||||
|
||||
method.
|
||||
The directory identified
|
||||
here must exist. If a relative path is
|
||||
provided, then the directory location is
|
||||
resolved relative to the environment's home
|
||||
directory.
|
||||
</p>
|
||||
<p>
|
||||
This method modifies the directory
|
||||
used for database files created and managed by
|
||||
a single environment handle; it does not
|
||||
configure the entire environment.
|
||||
<span>This
|
||||
method may not be called after the
|
||||
environment has been opened.
|
||||
</span>
|
||||
</p>
|
||||
<p>
|
||||
You can also set a default data location that is used by
|
||||
the entire environment by using the
|
||||
<tt class="literal">set_data_dir</tt> parameter
|
||||
in the environment's <tt class="literal">DB_CONFIG</tt> file.
|
||||
Note that the <tt class="literal">set_data_dir</tt>
|
||||
parameter overrides any value set by the
|
||||
|
||||
<tt class="methodname">DbEnv::set_data_dir()</tt>
|
||||
|
||||
method.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Log files</td>
|
||||
<td>
|
||||
<p>
|
||||
You can cause log files to be created
|
||||
in a directory other than the environment home
|
||||
directory by using the
|
||||
|
||||
<tt class="methodname">DbEnv::set_lg_dir()</tt>
|
||||
|
||||
method. The directory identified
|
||||
here must exist. If a relative path is
|
||||
provided, then the directory location is
|
||||
resolved relative to the environment's home
|
||||
directory.
|
||||
</p>
|
||||
<p>
|
||||
This method modifies the directory
|
||||
used for database files created and managed by
|
||||
a single environment handle; it does not
|
||||
configure the entire environment.
|
||||
<span>This
|
||||
method may not be called after the
|
||||
environment has been opened.
|
||||
</span>
|
||||
</p>
|
||||
<p>
|
||||
You can also set a default log file location that is used by
|
||||
the entire environment by using the
|
||||
<tt class="literal">set_lg_dir</tt> parameter
|
||||
in the environment's <tt class="literal">DB_CONFIG</tt> file.
|
||||
Note that the <tt class="literal">set_lg_dir</tt>
|
||||
parameter overrides any value set by the
|
||||
|
||||
<tt class="methodname">DbEnv::set_lg_dir()</tt>
|
||||
|
||||
method.
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Region files</td>
|
||||
<td>
|
||||
If backed by the filesystem, region
|
||||
files are always placed in the environment home
|
||||
directory.
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
<p>
|
||||
Note that the <tt class="literal">DB_CONFIG</tt> must reside in the
|
||||
environment home directory. Parameters are specified in it one
|
||||
parameter to a line. Each parameter is followed by a space,
|
||||
which is followed by the parameter value. For example:
|
||||
</p>
|
||||
<pre class="programlisting"> set_data_dir /export1/db/env_data_files </pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="sect2" lang="en" xml:lang="en">
|
||||
<div class="titlepage">
|
||||
<div>
|
||||
<div>
|
||||
<h3 class="title"><a id="errorsupport"></a>Error Support</h3>
|
||||
</div>
|
||||
</div>
|
||||
<div></div>
|
||||
</div>
|
||||
<p>
|
||||
To simplify error handling and to aid in application debugging, environments offer several useful
|
||||
methods.
|
||||
|
||||
<span>Note that many of these
|
||||
methods are identical to the error handling methods available for the
|
||||
|
||||
<span>Db</span>
|
||||
|
||||
|
||||
<span>class.</span>
|
||||
|
||||
</span>
|
||||
|
||||
They are:
|
||||
</p>
|
||||
<div class="itemizedlist">
|
||||
<ul type="disc">
|
||||
<li>
|
||||
<p>
|
||||
<tt class="methodname">set_error_stream()</tt>
|
||||
|
||||
</p>
|
||||
<p>
|
||||
Sets the
|
||||
<span>C++ <tt class="classname">ostream</tt></span>
|
||||
|
||||
to be used for displaying error messages issued by the DB library.
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
<tt class="methodname">set_errcall()</tt>
|
||||
|
||||
</p>
|
||||
<p>
|
||||
Defines the function that is called when an error message is
|
||||
issued by DB. The error prefix and message are passed to
|
||||
this callback. It is up to the application to display this
|
||||
information correctly.
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
<tt class="methodname">set_errfile()</tt>
|
||||
</p>
|
||||
<p>
|
||||
Sets the C library <tt class="literal">FILE *</tt> to be used for
|
||||
displaying error messages issued by the DB library.
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
<tt class="methodname">set_errpfx()</tt>
|
||||
|
||||
</p>
|
||||
<p>
|
||||
Sets the prefix used to for any error messages issued by the
|
||||
DB library.
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
<tt class="methodname">err()</tt>
|
||||
</p>
|
||||
<p>
|
||||
Issues an error message based upon a DB error code a message text that you supply.
|
||||
The error message is sent to the
|
||||
callback function as defined by <tt class="methodname">set_errcall()</tt>.
|
||||
If that method has not been used, then the error message is sent to the
|
||||
file defined by
|
||||
|
||||
<span>
|
||||
<tt class="methodname">set_errfile()</tt> or <tt class="methodname">set_error_stream()</tt>.
|
||||
</span>
|
||||
If none of these methods have been used, then the error message is sent to
|
||||
standard error.
|
||||
</p>
|
||||
<p>
|
||||
The error message consists of the prefix string
|
||||
(as defined by <tt class="methodname">set_errprefix()</tt>),
|
||||
an optional <tt class="literal">printf</tt>-style formatted message,
|
||||
the DB error message associated with the supplied error code,
|
||||
and a trailing newline.
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
<tt class="methodname">errx()</tt>
|
||||
</p>
|
||||
<p>
|
||||
Behaves identically to <tt class="methodname">err()</tt> except
|
||||
that you do not provide the DB error code and so
|
||||
the DB message text is not displayed.
|
||||
</p>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<p>
|
||||
In addition, you can use the <tt class="function">db_strerror()</tt>
|
||||
function to directly return the error string that corresponds to a
|
||||
particular error number. For more information on the
|
||||
<tt class="function">db_strerror()</tt> function, see the <tt class="literal">Error Returns</tt>
|
||||
section of the <i class="citetitle">Getting Started with Berkeley DB</i> guide.
|
||||
</p>
|
||||
</div>
|
||||
<div class="sect2" lang="en" xml:lang="en">
|
||||
<div class="titlepage">
|
||||
<div>
|
||||
<div>
|
||||
<h3 class="title"><a id="sharedmemory"></a>Shared Memory Regions</h3>
|
||||
</div>
|
||||
</div>
|
||||
<div></div>
|
||||
</div>
|
||||
<p>
|
||||
The subsystems that you enable for an environment (in our case,
|
||||
transaction, logging, locking, and the memory pool)
|
||||
are described by one or more regions. The regions contain all of the
|
||||
state information that needs to be shared among threads and/or
|
||||
processes using the environment.
|
||||
</p>
|
||||
<p>
|
||||
Regions may be backed by the file system, by heap memory, or by
|
||||
system shared memory.
|
||||
</p>
|
||||
<div class="sect3" lang="en" xml:lang="en">
|
||||
<div class="titlepage">
|
||||
<div>
|
||||
<div>
|
||||
<h4 class="title"><a id="filebackedregions"></a>Regions Backed by Files</h4>
|
||||
</div>
|
||||
</div>
|
||||
<div></div>
|
||||
</div>
|
||||
<p>
|
||||
By default, shared memory regions are created as files in the environment's
|
||||
home directory (<span class="emphasis"><em>not</em></span> the environment's data
|
||||
directory). If it is available, the POSIX <tt class="literal">mmap</tt>
|
||||
interface is used to map these files into your application's
|
||||
address space. If <tt class="literal">mmap</tt>
|
||||
is not available, then the UNIX <tt class="literal">shmget</tt> interfaces
|
||||
are used instead (again, if they are available).
|
||||
</p>
|
||||
<p>
|
||||
In this default case, the region files are named
|
||||
<tt class="literal">__db.###</tt>
|
||||
(for example, <tt class="literal">__db.001</tt>, <tt class="literal">__db.002</tt>,
|
||||
and so on).
|
||||
</p>
|
||||
</div>
|
||||
<div class="sect3" lang="en" xml:lang="en">
|
||||
<div class="titlepage">
|
||||
<div>
|
||||
<div>
|
||||
<h4 class="title"><a id="heapbackedregions"></a>Regions Backed by Heap Memory</h4>
|
||||
</div>
|
||||
</div>
|
||||
<div></div>
|
||||
</div>
|
||||
<p>
|
||||
If heap memory is used to back your shared memory regions,
|
||||
the environment may only be
|
||||
accessed by a single process, although that process may be
|
||||
multi-threaded. In this case, the regions are managed only in
|
||||
memory, and they are not written to the filesystem. You
|
||||
indicate that heap memory is to be used for the region files by
|
||||
specifying
|
||||
<span>
|
||||
<tt class="literal">DB_PRIVATE</tt> to the
|
||||
|
||||
<tt class="methodname">DbEnv::open()</tt>
|
||||
method.
|
||||
</span>
|
||||
|
||||
|
||||
|
||||
</p>
|
||||
<p>
|
||||
(For an example of an entirely in-memory transactional
|
||||
application, see
|
||||
<span>
|
||||
<a href="inmem_txnexample_c.html">In-Memory Transaction Example</a>.)
|
||||
</span>
|
||||
|
||||
|
||||
|
||||
</p>
|
||||
</div>
|
||||
<div class="sect3" lang="en" xml:lang="en">
|
||||
<div class="titlepage">
|
||||
<div>
|
||||
<div>
|
||||
<h4 class="title"><a id="systembackedregions"></a>Regions Backed by System Memory</h4>
|
||||
</div>
|
||||
</div>
|
||||
<div></div>
|
||||
</div>
|
||||
<p>
|
||||
Finally, you can cause system memory to be used for your
|
||||
regions instead of memory-mapped files. You do this by providing
|
||||
<span>
|
||||
<tt class="literal">DB_SYSTEM_MEM</tt> to the
|
||||
|
||||
<tt class="methodname">DbEnv::open()</tt>
|
||||
method.
|
||||
</span>
|
||||
|
||||
|
||||
</p>
|
||||
<p>
|
||||
When region files are backed by system memory, DB creates a
|
||||
single file in the environment's home directory. This file
|
||||
contains information necessary to identify the system shared
|
||||
memory in use by the environment. By creating this file, DB
|
||||
enables multiple processes to share the environment.
|
||||
</p>
|
||||
<p>
|
||||
The system memory that is used is architecture-dependent. For
|
||||
example, on systems supporting X/Open-style shared memory
|
||||
interfaces, such as UNIX systems, the <tt class="literal">shmget(2)</tt>
|
||||
and related System V IPC interfaces are used.
|
||||
|
||||
<span>
|
||||
|
||||
Additionally, VxWorks systems use system memory. In these cases,
|
||||
an initial segment ID must be specified by the application to
|
||||
ensure that applications do not overwrite each other's
|
||||
environments, so that the number of segments created does not
|
||||
grow without bounds. See the
|
||||
|
||||
|
||||
<tt class="methodname">DbEnv::set_shm_key()</tt>
|
||||
|
||||
method for more information.
|
||||
</span>
|
||||
</p>
|
||||
<p>
|
||||
On Windows platforms, the use of system memory for the region files
|
||||
is problematic because the operating system uses reference counting
|
||||
to clean up shared objects in the paging file automatically. In
|
||||
addition, the default access permissions for shared objects are
|
||||
different from files, which may cause problems when an environment
|
||||
is accessed by multiple processes running as different users. See
|
||||
<a href="" target="_top">Windows notes</a>
|
||||
or more information.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="sect2" lang="en" xml:lang="en">
|
||||
<div class="titlepage">
|
||||
<div>
|
||||
<div>
|
||||
<h3 class="title"><a id="security"></a>Security Considerations</h3>
|
||||
</div>
|
||||
</div>
|
||||
<div></div>
|
||||
</div>
|
||||
<p>
|
||||
When using environments, there are some security considerations to
|
||||
keep in mind:
|
||||
</p>
|
||||
<div class="itemizedlist">
|
||||
<ul type="disc">
|
||||
<li>
|
||||
<p>
|
||||
Database environment permissions
|
||||
</p>
|
||||
<p>
|
||||
The directory used for the environment
|
||||
should have its permissions set to ensure that files in the
|
||||
environment are not accessible to users without appropriate
|
||||
permissions. Applications that add to the user's permissions
|
||||
(for example, UNIX <tt class="literal">setuid</tt> or
|
||||
<tt class="literal">setgid</tt> applications), must be
|
||||
carefully checked to not permit illegal use of those
|
||||
permissions such as general file access in the environment
|
||||
directory.
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
Environment variables
|
||||
</p>
|
||||
<p>
|
||||
Setting
|
||||
|
||||
<span>
|
||||
the <tt class="literal">DB_USE_ENVIRON</tt> or
|
||||
<tt class="literal">DB_USE_ENVIRON_ROOT</tt> flags
|
||||
</span>
|
||||
|
||||
|
||||
so that environment variables can be used during file naming
|
||||
can be dangerous. Setting those flags in DB
|
||||
applications with additional permissions (for example, UNIX
|
||||
<tt class="literal">setuid</tt> or <tt class="literal">setgid</tt>
|
||||
applications) could potentially allow users
|
||||
to read and write databases to which they would not normally
|
||||
have access.
|
||||
</p>
|
||||
<p>
|
||||
For example, suppose you write a DB application
|
||||
that runs <tt class="literal">setuid</tt>. This means that
|
||||
when the application runs, it does so under a
|
||||
userid different than that of the application's caller.
|
||||
This is especially problematic if the application is
|
||||
granting stronger privileges to a user than the user
|
||||
might ordinarily have.
|
||||
</p>
|
||||
<p>
|
||||
Now, if
|
||||
<span>
|
||||
the <tt class="literal">DB_USE_ENVIRON</tt> or
|
||||
<tt class="literal">DB_USE_ENVIRON_ROOT</tt> flags
|
||||
are set for the environment,
|
||||
</span>
|
||||
|
||||
|
||||
|
||||
then the environment that the application is
|
||||
using is modifiable using the
|
||||
<tt class="literal">DB_HOME</tt> environment variable. In
|
||||
this scenario, if the uid used by the application has
|
||||
sufficiently broad privileges, then the application's caller
|
||||
can read and/or write databases owned by another user
|
||||
simply by setting his
|
||||
<tt class="literal">DB_HOME</tt> environment variable to the
|
||||
environment used by that other user.
|
||||
</p>
|
||||
<p>
|
||||
Note that this scenario need not be malicious; the
|
||||
wrong environment could be used by the application
|
||||
simply by inadvertently specifying the wrong path to
|
||||
<tt class="literal">DB_HOME</tt>.
|
||||
</p>
|
||||
<p>
|
||||
As always, you should use <tt class="literal">setuid</tt>
|
||||
sparingly, if at all. But if you do use
|
||||
<tt class="literal">setuid</tt>, then you should refrain from
|
||||
specifying
|
||||
<span>
|
||||
the <tt class="literal">DB_USE_ENVIRON</tt> or
|
||||
<tt class="literal">DB_USE_ENVIRON_ROOT</tt> flags
|
||||
</span>
|
||||
|
||||
for the environment open. And, of course, if you must
|
||||
use <tt class="literal">setuid</tt>, then make sure you use
|
||||
the weakest uid possible – preferably one that is
|
||||
used only by the application itself.
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
File permissions
|
||||
</p>
|
||||
<p>
|
||||
By default, DB always creates database and log files readable and
|
||||
writable by the owner and the group (that is,
|
||||
<tt class="literal">S_IRUSR</tt>,
|
||||
<tt class="literal">S_IWUSR</tt>, <tt class="literal">S_IRGRP</tt> and
|
||||
<tt class="literal">S_IWGRP</tt>; or octal mode 0660 on historic
|
||||
UNIX systems). The group ownership of created files is based
|
||||
on the system and directory defaults, and is not further
|
||||
specified by DB.
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
Temporary backing files
|
||||
</p>
|
||||
<p>
|
||||
If an unnamed database is created and the cache is too small
|
||||
to hold the database in memory, Berkeley DB will create a
|
||||
temporary physical file to enable it to page the database to
|
||||
disk as needed. In this case, environment variables such as
|
||||
<tt class="literal">TMPDIR</tt> may be used to specify the
|
||||
location of that temporary file. Although temporary backing
|
||||
files are created readable and writable by the owner only
|
||||
(<tt class="literal">S_IRUSR</tt> and <tt class="literal">S_IWUSR</tt>,
|
||||
or octal mode 0600 on historic UNIX systems), some
|
||||
filesystems may not sufficiently protect temporary files
|
||||
created in random directories from improper access. To be
|
||||
absolutely safe, applications storing sensitive data in
|
||||
unnamed databases should use the
|
||||
|
||||
<tt class="methodname">DbEnv::set_tmp_dir()</tt>
|
||||
|
||||
method to specify a temporary directory with known permissions.
|
||||
</p>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="navfooter">
|
||||
<hr />
|
||||
<table width="100%" summary="Navigation footer">
|
||||
<tr>
|
||||
<td width="40%" align="left"><a accesskey="p" href="perftune-intro.html">Prev</a> </td>
|
||||
<td width="20%" align="center">
|
||||
<a accesskey="u" href="index.html">Up</a>
|
||||
</td>
|
||||
<td width="40%" align="right"> <a accesskey="n" href="envopen.html">Next</a></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="40%" align="left" valign="top">Performance Tuning </td>
|
||||
<td width="20%" align="center">
|
||||
<a accesskey="h" href="index.html">Home</a>
|
||||
</td>
|
||||
<td width="40%" align="right" valign="top"> Opening a Transactional Environment and
|
||||
Database
|
||||
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user