1<!--$Id: naming.so,v 10.51 2007/09/26 15:11:31 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB Reference Guide: File naming</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<a name="2"><!--meow--></a> 12<table width="100%"><tr valign=top> 13<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Environment</dl></b></td> 14<td align=right><a href="/env/db_config.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/env/region.html"><img src="/images/next.gif" alt="Next"></a> 15</td></tr></table> 16<p align=center><b>File naming</b></p> 17<p>One of the most important tasks of the database environment is to 18structure file naming within Berkeley DB. Cooperating applications (or 19multiple invocations of the same application) must agree on the location 20of the database environment, log files and other files used by the Berkeley DB 21subsystems, and, of course, the database files. Although it is possible 22to specify full pathnames to all Berkeley DB methods, this is cumbersome and 23requires applications be recompiled when database files are moved.</p> 24<p>Applications are normally expected to specify a single directory home 25for the database environment. This can be done easily in the call to 26<a href="/api_c/env_open.html">DB_ENV->open</a> by specifying a value for the <b>db_home</b> 27argument. There are more complex configurations in which it may be 28desirable to override <b>db_home</b> or provide supplementary path 29information.</p> 30<b>Specifying file naming to Berkeley DB</b> 31<p>The following list describes the possible ways in which file naming 32information may be specified to the Berkeley DB library. The specific 33circumstances and order in which these ways are applied are described 34in a subsequent paragraph.</p> 35<br> 36<b><a name="db_home">db_home</a></b><ul compact><li>If the <b>db_home</b> argument to <a href="/api_c/env_open.html">DB_ENV->open</a> is non-NULL, 37its value may be used as the database home, and files named relative to 38its path.</ul> 39<b><a name="DB_HOME">DB_HOME</a></b><ul compact><li>If the DB_HOME environment variable is set when <a href="/api_c/env_open.html">DB_ENV->open</a> is 40called, its value may be used as the database home, and files named 41relative to its path. 42<p>The DB_HOME environment variable is intended to permit users and system 43administrators to override application and installation defaults. For 44example::</p> 45<blockquote><pre>env DB_HOME=/database/my_home application</pre></blockquote> 46<p>Application writers are encouraged to support the <b>-h</b> option 47found in the supporting Berkeley DB utilities to let users specify a database 48home.</p></ul> 49<b><a href="/api_c/env_class.html">DB_ENV</a> methods</b><ul compact><li>There are three <a href="/api_c/env_class.html">DB_ENV</a> methods that affect file naming. The 50<a href="/api_c/env_set_data_dir.html">DB_ENV->set_data_dir</a> method specifies a directory to search for database 51files. The <a href="/api_c/env_set_lg_dir.html">DB_ENV->set_lg_dir</a> method specifies a directory in which to 52create logging files. The <a href="/api_c/env_set_tmp_dir.html">DB_ENV->set_tmp_dir</a> method specifies a 53directory in which to create backing temporary files. These methods 54are intended to permit applications to customize a file location for a 55database. For example, an application writer can place data files and 56log files in different directories or instantiate a new log directory 57each time the application runs.</ul> 58<b><a href="/ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a></b><ul compact><li>The same information specified to the <a href="/api_c/env_class.html">DB_ENV</a> methods may also be 59specified using the <a href="/ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration file.</ul> 60<br> 61<b>Filename resolution in Berkeley DB</b> 62<p>The following list describes the specific circumstances and order in 63which the different ways of specifying file naming information are 64applied. Berkeley DB filename processing proceeds sequentially through the 65following steps:</p> 66<br> 67<b>absolute pathnames</b><ul compact><li>If the filename specified to a Berkeley DB function is an <i>absolute 68pathname</i>, that filename is used without modification by Berkeley DB. 69<p>On UNIX systems, an absolute pathname is defined as any pathname that 70begins with a leading slash (<b>/</b>).</p> 71<p>On Windows systems, an absolute pathname is any pathname that begins with 72a leading slash or leading backslash (<b>\</b>); or any 73pathname beginning with a single alphabetic character, a colon and a 74leading slash or backslash (for example, <b>C:/tmp</b>).</p></ul> 75<b><a href="/api_c/env_class.html">DB_ENV</a> methods, DB_CONFIG</b><ul compact><li>If a relevant configuration string (for example, set_data_dir), is 76specified either by calling a <a href="/api_c/env_class.html">DB_ENV</a> method or as a line in the 77<a href="/ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration file, the value is prepended to the 78filename. If the resulting filename is an absolute pathname, the 79filename is used without further modification by Berkeley DB.</ul> 80<b>db_home</b><ul compact><li>If the application specified a non-NULL <b>db_home</b> argument to 81<a href="/api_c/env_open.html">DB_ENV->open</a>, its value is prepended to the filename. If the 82resulting filename is an absolute pathname, the filename is used without 83further modification by Berkeley DB.</ul> 84<b>DB_HOME</b><ul compact><li>If the <b>db_home</b> argument is NULL, the DB_HOME environment 85variable was set, and the application has set the appropriate 86<a href="/api_c/env_open.html#DB_USE_ENVIRON">DB_USE_ENVIRON</a> or <a href="/api_c/env_open.html#DB_USE_ENVIRON_ROOT">DB_USE_ENVIRON_ROOT</a> flags, its value 87is prepended to the filename. If the resulting filename is an absolute 88pathname, the filename is used without further modification by Berkeley DB.</ul> 89<b>default</b><ul compact><li>Finally, all filenames are interpreted relative to the current working 90directory of the process.</ul> 91<br> 92<p>The common model for a Berkeley DB environment is one in which only the DB_HOME 93environment variable, or the <b>db_home</b> argument is specified. In 94this case, all data filenames are relative to that directory, and all 95files created by the Berkeley DB subsystems will be created in that directory.</p> 96<p>The more complex model for a transaction environment might be one in 97which a database home is specified, using either the DB_HOME environment 98variable or the <b>db_home</b> argument to <a href="/api_c/env_open.html">DB_ENV->open</a>; and then 99the data directory and logging directory are set to the relative 100pathnames of directories underneath the environment home.</p> 101<b>Examples</b> 102<p>Store all files in the directory <b>/a/database</b>:</p> 103<blockquote><pre>dbenv->open(dbenv, "/a/database", flags, mode);</pre></blockquote> 104<p>Create temporary backing files in <b>/b/temporary</b>, and all other files 105in <b>/a/database</b>:</p> 106<blockquote><pre>dbenv->set_tmp_dir(dbenv, "/b/temporary"); 107dbenv->open(dbenv, "/a/database", flags, mode);</pre></blockquote> 108<p>Store data files in <b>/a/database/datadir</b>, log files in 109<b>/a/database/logdir</b>, and all other files in the directory 110<b>/a/database</b>:</p> 111<blockquote><pre>dbenv->set_lg_dir(dbenv, "logdir"); 112dbenv->set_data_dir(dbenv, "datadir"); 113dbenv->open(dbenv, "/a/database", flags, mode);</pre></blockquote> 114<p>Store data files in <b>/a/database/data1</b> and <b>/b/data2</b>, and 115all other files in the directory <b>/a/database</b>. Any data files 116that are created will be created in <b>/b/data2</b>, because it is 117the first data file directory specified:</p> 118<blockquote><pre>dbenv->set_data_dir(dbenv, "/b/data2"); 119dbenv->set_data_dir(dbenv, "data1"); 120dbenv->open(dbenv, "/a/database", flags, mode);</pre></blockquote> 121<table width="100%"><tr><td><br></td><td align=right><a href="/env/db_config.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/env/region.html"><img src="/images/next.gif" alt="Next"></a> 122</td></tr></table> 123<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 124</body> 125</html> 126
