mirror of
https://github.com/MariaDB/server.git
synced 2025-11-09 11:41:36 +03:00
146 lines
9.4 KiB
HTML
146 lines
9.4 KiB
HTML
<!--$Id: naming.so,v 10.36 2001/01/09 15:36:10 bostic Exp $-->
|
|
<!--Copyright 1997, 1998, 1999, 2000 by Sleepycat Software, Inc.-->
|
|
<!--All rights reserved.-->
|
|
<html>
|
|
<head>
|
|
<title>Berkeley DB Reference Guide: File naming</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><h3><dl><dt>Berkeley DB Reference Guide:<dd>Environment</dl></h3></td>
|
|
<td width="1%"><a href="../../ref/env/create.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/security.html"><img src="../../images/next.gif" alt="Next"></a>
|
|
</td></tr></table>
|
|
<p>
|
|
<h1 align=center>File naming</h1>
|
|
<p>The most important task of the environment is to structure file naming
|
|
within Berkeley DB.
|
|
<p>Each of the locking, logging, memory pool and transaction subsystems of
|
|
Berkeley DB require shared memory regions, backed by the filesystem. Further,
|
|
cooperating applications (or multiple invocations of the same application)
|
|
must agree on the location of the shared memory regions and other files
|
|
used by the Berkeley DB subsystems, the log files used by the logging subsystem,
|
|
and, of course, the data files. Although it is possible to specify full
|
|
pathnames to all Berkeley DB functions, this is cumbersome and requires
|
|
that applications be recompiled when database files are moved.
|
|
<p>Applications are normally expected to specify a single directory home for
|
|
their database. This can be done easily in the call to <a href="../../api_c/env_open.html">DBENV->open</a>
|
|
by specifying a value for the <b>db_home</b> argument. There are more
|
|
complex configurations where it may be desirable to override
|
|
<b>db_home</b> or provide supplementary path information.
|
|
<h3>Specifying file naming to Berkeley DB</h3>
|
|
<p>The following 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><dl compact>
|
|
<p><dt><b><a name="db_home">db_home</a></b><dd>If the <b>db_home</b> argument to <a href="../../api_c/env_open.html">DBENV->open</a> is non-NULL, its
|
|
value may be used as the database home, and files named relative to its
|
|
path.
|
|
<p><dt><a name="DB_HOME">DB_HOME</a><dd>If the DB_HOME environment variable is set when <a href="../../api_c/env_open.html">DBENV->open</a> is
|
|
called, its value may be used as the database home, and files named
|
|
relative to its path.
|
|
<p>The DB_HOME environment variable is intended to permit users and system
|
|
administrators to override application and installation defaults, e.g.:
|
|
<p><blockquote><pre>env DB_HOME=/database/my_home application</pre></blockquote>
|
|
<p>Application writers are encouraged to support the <b>-h</b> option
|
|
found in the supporting Berkeley DB utilities to let users specify a database
|
|
home.
|
|
<p><dt>DB_ENV methods<dd>There are three DB_ENV methods that affect file naming. The
|
|
<a href="../../api_c/env_set_data_dir.html">DBENV->set_data_dir</a> function specifies a directory to search for database
|
|
files. The <a href="../../api_c/env_set_lg_dir.html">DBENV->set_lg_dir</a> function specifies a directory in which to
|
|
create logging files. The <a href="../../api_c/env_set_tmp_dir.html">DBENV->set_tmp_dir</a> function specifies a
|
|
directory in which to create backing temporary files. These methods are
|
|
intended to permit applications to customize file location for a database.
|
|
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><dt><a name="DB_CONFIG">DB_CONFIG</a><dd>The same information specified to the above DB_ENV methods may also
|
|
be specified using a configuration file. If an environment home directory
|
|
has been specified (either by the application specifying a non-NULL
|
|
<b>db_home</b> argument to <a href="../../api_c/env_open.html">DBENV->open</a>, or by the application
|
|
setting the DB_USE_ENVIRON or DB_USE_ENVIRON_ROOT flags and the DB_HOME
|
|
environment variable being set), any file named <b>DB_CONFIG</b> in the
|
|
database home directory will be read for lines of the format <b>NAME
|
|
VALUE</b>.
|
|
<p>The characters delimiting the two parts of the entry may be one or more
|
|
whitespace characters, and trailing whitespace characters are discarded.
|
|
All empty lines or lines whose first character is a whitespace or hash
|
|
(<b>#</b>) character will be ignored. Each line must specify both
|
|
the NAME and the VALUE of the pair. The specific NAME VALUE pairs are
|
|
documented in the manual <a href="../../api_c/env_set_data_dir.html">DBENV->set_data_dir</a>,
|
|
<a href="../../api_c/env_set_lg_dir.html">DBENV->set_lg_dir</a> and <a href="../../api_c/env_set_tmp_dir.html">DBENV->set_tmp_dir</a> pages.
|
|
<p>The DB_CONFIG configuration file is intended to permit systems to
|
|
customize file location for an environment independent of applications
|
|
using that database. For example, a database administrator can move the
|
|
database log and data files to a different location without application
|
|
recompilation.
|
|
</dl>
|
|
<h3>File name resolution in Berkeley DB</h3>
|
|
<p>The following describes the specific circumstances and order in which the
|
|
different ways of specifying file naming information are applied. Berkeley DB
|
|
file name processing proceeds sequentially through the following steps:
|
|
<p><dl compact>
|
|
<p><dt>absolute pathnames<dd>If the file name specified to a Berkeley DB function is an absolute pathname,
|
|
that file name is used without modification by Berkeley DB.
|
|
<p>On UNIX systems, an absolute pathname is defined as any pathname that
|
|
begins with a leading slash (<b>/</b>).
|
|
<p>On Windows systems, an absolute pathname is any pathname that begins with
|
|
a leading slash or leading backslash (<b>\</b>), or any
|
|
pathname beginning with a single alphabetic character, a colon and a
|
|
leading slash or backslash, e.g., <b>C:/tmp</b>.
|
|
<p><dt>DB_ENV methods, DB_CONFIG<dd>If a relevant configuration string (e.g., set_data_dir), is specified
|
|
either by calling a DB_ENV method or as a line in the DB_CONFIG
|
|
configuration file, the VALUE from the <b>NAME VALUE</b> pair is
|
|
prepended to the current file name. If the resulting file name is an
|
|
absolute pathname, the file name is used without further modification by
|
|
Berkeley DB.
|
|
<p><dt><b>db_home</b><dd>If the application specified a non-NULL <b>db_home</b> argument to
|
|
<a href="../../api_c/env_open.html">DBENV->open</a> its value is prepended to the current file name. If
|
|
the resulting file name is an absolute pathname, the file name is used
|
|
without further modification by Berkeley DB.
|
|
<p><dt>DB_HOME<dd>If the <b>db_home</b> argument is null, the DB_HOME environment variable
|
|
was set and the application has set the appropriate DB_USE_ENVIRON or
|
|
DB_USE_ENVIRON_ROOT environment variable, its value is prepended to the
|
|
current file name. If the resulting file name is an absolute pathname,
|
|
the file name is used without further modification by Berkeley DB.
|
|
<p><dt>(nothing)<dd>Finally, all file names are interpreted relative to the current working
|
|
directory of the process.
|
|
</dl>
|
|
<p>The common model for a Berkeley DB environment is one where only the DB_HOME
|
|
environment variable, or the <b>db_home</b> argument, is specified. In
|
|
this case, all data file names are relative to that directory, and all
|
|
files created by the Berkeley DB subsystems will be created in that directory.
|
|
<p>The more complex model for a transaction environment might be one where
|
|
a database home is specified, using either the DB_HOME environment
|
|
variable or the <b>db_home</b> argument to <a href="../../api_c/env_open.html">DBENV->open</a>, and then
|
|
the data directory and logging directory are set to the relative path
|
|
names of directories underneath the environment home.
|
|
<h3>Examples</h3>
|
|
Store all files in the directory <b>/a/database</b>:
|
|
<p><blockquote><pre>DBENV->open(DBENV, "/a/database", ...);</pre></blockquote>
|
|
Create temporary backing files in <b>/b/temporary</b>, and all other files
|
|
in <b>/a/database</b>:
|
|
<p><blockquote><pre>DBENV->set_tmp_dir(DBENV, "/b/temporary");
|
|
DBENV->open(DBENV, "/a/database", ...);</pre></blockquote>
|
|
Store data files in <b>/a/database/datadir</b>, log files in
|
|
<b>/a/database/logdir</b>, and all other files in the directory
|
|
<b>/a/database</b>:
|
|
<p><blockquote><pre>DBENV->set_lg_dir("logdir");
|
|
DBENV->set_data_dir("datadir");
|
|
DBENV->open(DBENV, "/a/database", ...);</pre></blockquote>
|
|
<p>Store data files in <b>/a/database/data1</b> and <b>/b/data2</b>, and
|
|
all other files in the directory <b>/a/database</b>. Any data files
|
|
that are created will be created in <b>/b/data2</b>, because it is the
|
|
first DB_DATA_DIR directory specified:
|
|
<p><blockquote><pre>DBENV->set_data_dir(DBENV, "/b/data2");
|
|
DBENV->set_data_dir(DBENV, "data1");
|
|
DBENV->open(DBENV, "/a/database", ...);</pre></blockquote>
|
|
<table><tr><td><br></td><td width="1%"><a href="../../ref/env/create.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../ref/toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/security.html"><img src="../../images/next.gif" alt="Next"></a>
|
|
</td></tr></table>
|
|
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
|
|
</body>
|
|
</html>
|