naming.html 9.42 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145
<!--$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-&gt;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-&gt;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-&gt;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-&gt;set_data_dir</a> function specifies a directory to search for database
files.  The <a href="../../api_c/env_set_lg_dir.html">DBENV-&gt;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-&gt;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-&gt;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-&gt;set_data_dir</a>,
<a href="../../api_c/env_set_lg_dir.html">DBENV-&gt;set_lg_dir</a> and <a href="../../api_c/env_set_tmp_dir.html">DBENV-&gt;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-&gt;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-&gt;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-&gt;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-&gt;set_tmp_dir(DBENV, "/b/temporary");
DBENV-&gt;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-&gt;set_lg_dir("logdir");
DBENV-&gt;set_data_dir("datadir");
DBENV-&gt;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-&gt;set_data_dir(DBENV, "/b/data2");
DBENV-&gt;set_data_dir(DBENV, "data1");
DBENV-&gt;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>