mirror of
https://github.com/yasuhirokimura/db18
synced 2026-06-08 18:29:23 +00:00
Yasuhiro KIMURA
369 lines
17 KiB
HTML
369 lines
17 KiB
HTML
<?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>File naming</title>
|
||
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
|
||
<link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
|
||
<link rel="up" href="env.html" title="Chapter 9. The Berkeley DB Environment" />
|
||
<link rel="prev" href="env_db_config.html" title="DB_CONFIG configuration file" />
|
||
<link rel="next" href="env_region.html" title="Shared memory regions" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 18.1.40</p>
|
||
</div>
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">File naming</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"><a accesskey="p" href="env_db_config.html">Prev</a> </td>
|
||
<th width="60%" align="center">Chapter 9. The Berkeley DB Environment </th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="env_region.html">Next</a></td>
|
||
</tr>
|
||
</table>
|
||
<hr />
|
||
</div>
|
||
<div class="sect1" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h2 class="title" style="clear: both"><a id="env_naming"></a>File naming</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="toc">
|
||
<dl>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="env_naming.html#idm140654538864576">Specifying file naming to Berkeley DB</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="env_naming.html#idm140654538873824">Filename resolution in Berkeley DB</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="env_naming.html#idm140654546493792">Examples</a>
|
||
</span>
|
||
</dt>
|
||
</dl>
|
||
</div>
|
||
<p>
|
||
One of the most important tasks of the database environment
|
||
is to structure file naming within Berkeley DB. Cooperating
|
||
applications (or multiple invocations of the same application)
|
||
must agree on the location of the database environment, log
|
||
files and other files used by the Berkeley DB subsystems, and,
|
||
of course, the database files. Although it is possible to
|
||
specify full pathnames to all Berkeley DB methods, this is
|
||
cumbersome and requires applications be recompiled when
|
||
database files are moved.
|
||
</p>
|
||
<p>
|
||
Applications are normally expected to specify a single
|
||
directory home for the database environment. This can be done
|
||
easily in the call to <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> by specifying a value for the
|
||
<span class="bold"><strong>db_home</strong></span> argument. There
|
||
are more complex configurations in which it may be desirable
|
||
to override <span class="bold"><strong>db_home</strong></span> or
|
||
provide supplementary path information.
|
||
</p>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="idm140654538864576"></a>Specifying file naming to Berkeley DB</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
The following list describes the possible ways in which
|
||
file naming information may be specified to the Berkeley
|
||
DB library. The specific circumstances and order in which
|
||
these ways are applied are described in a subsequent
|
||
paragraph.
|
||
</p>
|
||
<div class="variablelist">
|
||
<dl>
|
||
<dt>
|
||
<span class="term">db_home</span>
|
||
</dt>
|
||
<dd>
|
||
If the <span class="bold"><strong>db_home</strong></span> argument
|
||
to <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> is
|
||
non-NULL, its value may be used as the database
|
||
home, and files named relative to its path.
|
||
</dd>
|
||
<dt>
|
||
<span class="term">DB_HOME</span>
|
||
</dt>
|
||
<dd>
|
||
<p>
|
||
If the DB_HOME environment variable is set
|
||
when <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> is called, its value may be
|
||
used as the database home, and files named
|
||
relative to its path.
|
||
</p>
|
||
<p>
|
||
The DB_HOME environment variable is
|
||
intended to permit users and system
|
||
administrators to override application and
|
||
installation defaults. For example:
|
||
</p>
|
||
<pre class="programlisting">env DB_HOME=/database/my_home application</pre>
|
||
<p>
|
||
Application writers are encouraged to
|
||
support the <span class="bold"><strong>-h</strong></span>
|
||
option found in the
|
||
supporting Berkeley DB utilities to let users
|
||
specify a database home.
|
||
</p>
|
||
</dd>
|
||
<dt>
|
||
<span class="term"><a href="../api_reference/C/env.html" class="olink">DB_ENV</a> methods</span>
|
||
</dt>
|
||
<dd>
|
||
<p>
|
||
There are five <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> methods that affect
|
||
file naming:
|
||
</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>
|
||
<p>
|
||
The <a href="../api_reference/C/envadd_data_dir.html" class="olink">DB_ENV->add_data_dir()</a> method
|
||
specifies a directory to search for
|
||
database files.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
The <a href="../api_reference/C/envset_lg_dir.html" class="olink">DB_ENV->set_lg_dir()</a> method
|
||
specifies a directory in which to
|
||
create logging files.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
The <a href="../api_reference/C/envset_tmp_dir.html" class="olink">DB_ENV->set_tmp_dir()</a> method
|
||
specifies a directory in which to
|
||
create backing temporary files.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
The <a href="../api_reference/C/envset_metadata_dir.html" class="olink">DB_ENV->set_metadata_dir()</a> method
|
||
specifies the directory in which to
|
||
create persistent metadata files used
|
||
by the environment.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
The <a href="../api_reference/C/envset_region_dir.html" class="olink">DB_ENV->set_region_dir()</a> method
|
||
specifies the directory in which to
|
||
create disk-backed region files used
|
||
by the environment.
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<p>
|
||
These methods are intended to permit
|
||
applications to customize a file locations for
|
||
an environment. For example, an application
|
||
writer can place data files and log files in
|
||
different directories or instantiate a new log
|
||
directory each time the application runs.
|
||
</p>
|
||
</dd>
|
||
<dt>
|
||
<span class="term">
|
||
<a class="link" href="env_db_config.html" title="DB_CONFIG configuration file">DB_CONFIG</a>
|
||
</span>
|
||
</dt>
|
||
<dd>
|
||
The same information specified to the <a href="../api_reference/C/env.html" class="olink">DB_ENV</a>
|
||
methods may also be specified using the <a class="link" href="env_db_config.html" title="DB_CONFIG configuration file">DB_CONFIG</a>
|
||
configuration file.
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="idm140654538873824"></a>Filename resolution in Berkeley DB</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
The following list describes the specific circumstances
|
||
and order in which the different ways of specifying file
|
||
naming information are applied. Berkeley DB filename
|
||
processing proceeds sequentially through the following
|
||
steps:
|
||
</p>
|
||
<div class="variablelist">
|
||
<dl>
|
||
<dt>
|
||
<span class="term">absolute pathnames</span>
|
||
</dt>
|
||
<dd>
|
||
<p>
|
||
If the filename specified to a Berkeley DB
|
||
function is an <span class="emphasis"><em>absolute
|
||
pathname</em></span>, that filename is used
|
||
without modification by Berkeley DB. </p>
|
||
<p>
|
||
On UNIX systems, an absolute pathname is
|
||
defined as any pathname that begins with a
|
||
leading slash (<span class="bold"><strong>/</strong></span>).
|
||
</p>
|
||
<p>
|
||
On Windows systems, an absolute pathname is
|
||
any pathname that begins with a leading slash
|
||
or leading backslash (<span class="bold"><strong>\</strong></span>);
|
||
or any pathname beginning
|
||
with a single alphabetic character, a colon
|
||
and a leading slash or backslash (for example,
|
||
<code class="filename">C:/tmp</code>).
|
||
</p>
|
||
</dd>
|
||
<dt>
|
||
<span class="term"><a href="../api_reference/C/env.html" class="olink">DB_ENV</a> methods, DB_CONFIG</span>
|
||
</dt>
|
||
<dd>
|
||
If a relevant configuration string (for
|
||
example, add_data_dir), is specified either by
|
||
calling a <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> method or as a line in the <a class="link" href="env_db_config.html" title="DB_CONFIG configuration file">DB_CONFIG</a>
|
||
configuration file, the value is prepended to the
|
||
filename. If the resulting filename is an absolute
|
||
pathname, the filename is used without further
|
||
modification by Berkeley DB.
|
||
</dd>
|
||
<dt>
|
||
<span class="term">db_home</span>
|
||
</dt>
|
||
<dd>
|
||
If the application specified a non-NULL
|
||
<span class="bold"><strong>db_home</strong></span>
|
||
argument to <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a>, its value is prepended to
|
||
the filename. If the resulting filename is an
|
||
absolute pathname, the filename is used without
|
||
further modification by Berkeley DB.
|
||
</dd>
|
||
<dt>
|
||
<span class="term">DB_HOME</span>
|
||
</dt>
|
||
<dd>
|
||
If the <span class="bold"><strong>db_home</strong></span> argument is NULL, the
|
||
DB_HOME environment variable was set, and the
|
||
application has set the appropriate
|
||
<a href="../api_reference/C/envopen.html#envopen_DB_USE_ENVIRON" class="olink">DB_USE_ENVIRON</a> or <a href="../api_reference/C/envopen.html#envopen_DB_USE_ENVIRON_ROOT" class="olink">DB_USE_ENVIRON_ROOT</a> flags,
|
||
its value is prepended to the filename. If the
|
||
resulting filename is an absolute pathname, the
|
||
filename is used without further modification by
|
||
Berkeley DB.
|
||
</dd>
|
||
<dt>
|
||
<span class="term">default</span>
|
||
</dt>
|
||
<dd>
|
||
Finally, all filenames are interpreted
|
||
relative to the current working directory of the
|
||
process.
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<p>
|
||
The common model for a Berkeley DB environment is one
|
||
in which only the DB_HOME environment variable, or the
|
||
<span class="bold"><strong>db_home</strong></span> argument is
|
||
specified. In this case, all data filenames are relative
|
||
to that directory, and all files created by the Berkeley
|
||
DB subsystems will be created in that directory.
|
||
</p>
|
||
<p>
|
||
The more complex model for a transaction environment
|
||
might be one in which a database home is specified, using
|
||
either the DB_HOME environment variable or the <span class="bold"><strong>db_home</strong></span> argument to <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a>;
|
||
and then the data directory and logging directory are set
|
||
to the relative pathnames of directories underneath the
|
||
environment home.
|
||
</p>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="idm140654546493792"></a>Examples</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
Store all files in the directory
|
||
<code class="filename">/a/database</code>:
|
||
</p>
|
||
<pre class="programlisting">dbenv->open(dbenv, "/a/database", flags, mode);</pre>
|
||
<p>
|
||
Create temporary backing files in
|
||
<code class="filename">/b/temporary</code>, and all other files
|
||
in <code class="filename">/a/database</code>:
|
||
</p>
|
||
<pre class="programlisting">dbenv->set_tmp_dir(dbenv, "/b/temporary");
|
||
dbenv->open(dbenv, "/a/database", flags, mode);</pre>
|
||
<p>
|
||
Store data files in
|
||
<code class="filename">/a/database/datadir</code>, log files in
|
||
<code class="filename">/a/database/logdir</code>, and all other
|
||
files in the directory <code class="filename">/a/database</code>:
|
||
</p>
|
||
<pre class="programlisting">dbenv->set_lg_dir(dbenv, "logdir");
|
||
dbenv->add_data_dir(dbenv, "datadir");
|
||
dbenv->open(dbenv, "/a/database", flags, mode);</pre>
|
||
<p>
|
||
Store data files in
|
||
<code class="filename">/a/database/data1</code> and
|
||
<code class="filename">/b/data2</code>, and all other files in
|
||
the directory <code class="filename">/a/database</code>. Any data
|
||
files that are created will be created in
|
||
<code class="filename">/b/data2</code>, because it is the first
|
||
data file directory specified:
|
||
</p>
|
||
<pre class="programlisting">dbenv->add_data_dir(dbenv, "/b/data2");
|
||
dbenv->add_data_dir(dbenv, "data1");
|
||
dbenv->open(dbenv, "/a/database", flags, mode);</pre>
|
||
</div>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"><a accesskey="p" href="env_db_config.html">Prev</a> </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="u" href="env.html">Up</a>
|
||
</td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="env_region.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top">DB_CONFIG configuration
|
||
file </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="h" href="index.html">Home</a>
|
||
</td>
|
||
<td width="40%" align="right" valign="top"> Shared memory regions</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|