1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>File naming</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" /> 10 <link rel="up" href="env.html" title="Chapter��9.�� The Berkeley DB Environment" /> 11 <link rel="prev" href="env_db_config.html" title="DB_CONFIG configuration file" /> 12 <link rel="next" href="env_region.html" title="Shared memory regions" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">File naming</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="env_db_config.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��9.�� 23 The Berkeley DB Environment 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="env_region.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="env_naming"></a>File naming</h2> 35 </div> 36 </div> 37 </div> 38 <div class="toc"> 39 <dl> 40 <dt> 41 <span class="sect2"> 42 <a href="env_naming.html#id1605342">Specifying file naming to Berkeley DB</a> 43 </span> 44 </dt> 45 <dt> 46 <span class="sect2"> 47 <a href="env_naming.html#id1605560">Filename resolution in Berkeley DB</a> 48 </span> 49 </dt> 50 <dt> 51 <span class="sect2"> 52 <a href="env_naming.html#id1605734">Examples</a> 53 </span> 54 </dt> 55 </dl> 56 </div> 57 <p>One of the most important tasks of the database environment is to 58structure file naming within Berkeley DB. Cooperating applications (or 59multiple invocations of the same application) must agree on the location 60of the database environment, log files and other files used by the Berkeley DB 61subsystems, and, of course, the database files. Although it is possible 62to specify full pathnames to all Berkeley DB methods, this is cumbersome and 63requires applications be recompiled when database files are moved.</p> 64 <p>Applications are normally expected to specify a single directory home 65for the database environment. This can be done easily in the call to 66<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> 67argument. There are more complex configurations in which it may be 68desirable to override <span class="bold"><strong>db_home</strong></span> or provide supplementary path 69information.</p> 70 <div class="sect2" lang="en" xml:lang="en"> 71 <div class="titlepage"> 72 <div> 73 <div> 74 <h3 class="title"><a id="id1605342"></a>Specifying file naming to Berkeley DB</h3> 75 </div> 76 </div> 77 </div> 78 <p>The following list describes the possible ways in which file naming 79information may be specified to the Berkeley DB library. The specific 80circumstances and order in which these ways are applied are described 81in a subsequent paragraph.</p> 82 <div class="variablelist"> 83 <dl> 84 <dt> 85 <span class="term">db_home</span> 86 </dt> 87 <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, 88its value may be used as the database home, and files named relative to 89its path.</dd> 90 <dt> 91 <span class="term">DB_HOME</span> 92 </dt> 93 <dd> 94 <p>If the DB_HOME environment variable is set when <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> is 95called, its value may be used as the database home, and files named 96relative to its path.</p> 97 <p>The DB_HOME environment variable is intended to permit users and system 98administrators to override application and installation defaults. For 99example::</p> 100 <pre class="programlisting">env DB_HOME=/database/my_home application</pre> 101 <p>Application writers are encouraged to support the <span class="bold"><strong>-h</strong></span> option 102found in the supporting Berkeley DB utilities to let users specify a database 103home.</p> 104 </dd> 105 <dt> 106 <span class="term"><a href="../api_reference/C/env.html" class="olink">DB_ENV</a> methods</span> 107 </dt> 108 <dd> There are three <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> methods that affect file naming. The 109<a href="../api_reference/C/envset_data_dir.html" class="olink">DB_ENV->set_data_dir()</a> method specifies a directory to search for database 110files. 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 111create logging files. The <a href="../api_reference/C/envset_tmp_dir.html" class="olink">DB_ENV->set_tmp_dir()</a> method specifies a 112directory in which to create backing temporary files. These methods 113are intended to permit applications to customize a file location for a 114database. For example, an application writer can place data files and 115log files in different directories or instantiate a new log directory 116each time the application runs.</dd> 117 <dt> 118 <span class="term"> 119 <a class="link" href="env_db_config.html" title="DB_CONFIG configuration file">DB_CONFIG</a> 120 </span> 121 </dt> 122 <dd>The same information specified to the <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> 123 methods may also be specified using the <a class="link" href="env_db_config.html" title="DB_CONFIG configuration file">DB_CONFIG</a> 124 configuration file.</dd> 125 </dl> 126 </div> 127 </div> 128 <div class="sect2" lang="en" xml:lang="en"> 129 <div class="titlepage"> 130 <div> 131 <div> 132 <h3 class="title"><a id="id1605560"></a>Filename resolution in Berkeley DB</h3> 133 </div> 134 </div> 135 </div> 136 <p>The following list describes the specific circumstances and order in 137which the different ways of specifying file naming information are 138applied. Berkeley DB filename processing proceeds sequentially through the 139following steps:</p> 140 <div class="variablelist"> 141 <dl> 142 <dt> 143 <span class="term">absolute pathnames</span> 144 </dt> 145 <dd>If the filename specified to a Berkeley DB function is an <span class="emphasis"><em>absolute 146pathname</em></span>, that filename is used without modification by Berkeley DB. 147<p>On UNIX systems, an absolute pathname is defined as any pathname that 148begins with a leading slash (<span class="bold"><strong>/</strong></span>).</p><p>On Windows systems, an absolute pathname is any pathname that begins with 149a leading slash or leading backslash (<span class="bold"><strong>\</strong></span>); or any 150pathname beginning with a single alphabetic character, a colon and a 151leading slash or backslash (for example, <code class="filename">C:/tmp</code>).</p></dd> 152 <dt> 153 <span class="term"><a href="../api_reference/C/env.html" class="olink">DB_ENV</a> methods, DB_CONFIG</span> 154 </dt> 155 <dd>If a relevant configuration string (for example, set_data_dir), is 156specified either by calling a <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> method or as a line in the 157<a class="link" href="env_db_config.html" title="DB_CONFIG configuration file">DB_CONFIG</a> configuration file, the value is prepended to the 158filename. If the resulting filename is an absolute pathname, the 159filename is used without further modification by Berkeley DB.</dd> 160 <dt> 161 <span class="term">db_home</span> 162 </dt> 163 <dd>If the application specified a non-NULL <span class="bold"><strong>db_home</strong></span> argument to 164<a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a>, its value is prepended to the filename. If the 165resulting filename is an absolute pathname, the filename is used without 166further modification by Berkeley DB.</dd> 167 <dt> 168 <span class="term">DB_HOME</span> 169 </dt> 170 <dd>If the <span class="bold"><strong>db_home</strong></span> argument is NULL, the DB_HOME environment 171variable was set, and the application has set the appropriate 172<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 173is prepended to the filename. If the resulting filename is an absolute 174pathname, the filename is used without further modification by Berkeley DB.</dd> 175 <dt> 176 <span class="term">default</span> 177 </dt> 178 <dd>Finally, all filenames are interpreted relative to the current working 179directory of the process.</dd> 180 </dl> 181 </div> 182 <p>The common model for a Berkeley DB environment is one in which only the DB_HOME 183environment variable, or the <span class="bold"><strong>db_home</strong></span> argument is specified. In 184this case, all data filenames are relative to that directory, and all 185files created by the Berkeley DB subsystems will be created in that directory.</p> 186 <p>The more complex model for a transaction environment might be one in 187which a database home is specified, using either the DB_HOME environment 188variable 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 189the data directory and logging directory are set to the relative 190pathnames of directories underneath the environment home.</p> 191 </div> 192 <div class="sect2" lang="en" xml:lang="en"> 193 <div class="titlepage"> 194 <div> 195 <div> 196 <h3 class="title"><a id="id1605734"></a>Examples</h3> 197 </div> 198 </div> 199 </div> 200 <p>Store all files in the directory <code class="filename">/a/database</code>:</p> 201 <pre class="programlisting">dbenv->open(dbenv, "/a/database", flags, mode);</pre> 202 <p>Create temporary backing files in <code class="filename">/b/temporary</code>, and all other files 203in <code class="filename">/a/database</code>:</p> 204 <pre class="programlisting">dbenv->set_tmp_dir(dbenv, "/b/temporary"); 205dbenv->open(dbenv, "/a/database", flags, mode);</pre> 206 <p>Store data files in <code class="filename">/a/database/datadir</code>, log files in 207<code class="filename">/a/database/logdir</code>, and all other files in the directory 208<code class="filename">/a/database</code>:</p> 209 <pre class="programlisting">dbenv->set_lg_dir(dbenv, "logdir"); 210dbenv->set_data_dir(dbenv, "datadir"); 211dbenv->open(dbenv, "/a/database", flags, mode);</pre> 212 <p>Store data files in <code class="filename">/a/database/data1</code> and <code class="filename">/b/data2</code>, and 213all other files in the directory <code class="filename">/a/database</code>. Any data files 214that are created will be created in <code class="filename">/b/data2</code>, because it is 215the first data file directory specified:</p> 216 <pre class="programlisting">dbenv->set_data_dir(dbenv, "/b/data2"); 217dbenv->set_data_dir(dbenv, "data1"); 218dbenv->open(dbenv, "/a/database", flags, mode);</pre> 219 </div> 220 </div> 221 <div class="navfooter"> 222 <hr /> 223 <table width="100%" summary="Navigation footer"> 224 <tr> 225 <td width="40%" align="left"><a accesskey="p" href="env_db_config.html">Prev</a>��</td> 226 <td width="20%" align="center"> 227 <a accesskey="u" href="env.html">Up</a> 228 </td> 229 <td width="40%" align="right">��<a accesskey="n" href="env_region.html">Next</a></td> 230 </tr> 231 <tr> 232 <td width="40%" align="left" valign="top">DB_CONFIG configuration file��</td> 233 <td width="20%" align="center"> 234 <a accesskey="h" href="index.html">Home</a> 235 </td> 236 <td width="40%" align="right" valign="top">��Shared memory regions</td> 237 </tr> 238 </table> 239 </div> 240 </body> 241</html> 242