diff options
Diffstat (limited to 'docs/programmer_reference/env_naming.html')
| -rw-r--r-- | docs/programmer_reference/env_naming.html | 368 |
1 files changed, 191 insertions, 177 deletions
diff --git a/docs/programmer_reference/env_naming.html b/docs/programmer_reference/env_naming.html index e05a12e7..c5353bc2 100644 --- a/docs/programmer_reference/env_naming.html +++ b/docs/programmer_reference/env_naming.html @@ -14,7 +14,7 @@ <body> <div xmlns="" class="navheader"> <div class="libver"> - <p>Library Version 11.2.5.3</p> + <p>Library Version 12.1.6.1</p> </div> <table width="100%" summary="Navigation header"> <tr> @@ -22,9 +22,7 @@ </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> + <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> @@ -42,143 +40,152 @@ <dl> <dt> <span class="sect2"> - <a href="env_naming.html#idp1570112">Specifying file naming to Berkeley DB</a> + <a href="env_naming.html#idp1149160">Specifying file naming to Berkeley DB</a> </span> </dt> <dt> <span class="sect2"> - <a href="env_naming.html#idp1584200">Filename resolution in Berkeley DB</a> + <a href="env_naming.html#idp1160456">Filename resolution in Berkeley DB</a> </span> </dt> <dt> <span class="sect2"> - <a href="env_naming.html#idp1605872">Examples</a> + <a href="env_naming.html#idp1182752">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> + 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="idp1570112"></a>Specifying file naming to Berkeley DB</h3> + <h3 class="title"><a id="idp1149160"></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> + 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> + 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> + 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> + 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> + <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 four <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> methods that affect file naming: - </p> + <p> + There are four <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> + <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> + <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> + 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> + 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> </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> + <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> + <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> + <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> @@ -186,140 +193,146 @@ <div class="titlepage"> <div> <div> - <h3 class="title"><a id="idp1584200"></a>Filename resolution in Berkeley DB</h3> + <h3 class="title"><a id="idp1160456"></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> + 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> + <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, - set_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> + <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> + <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> + 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> + 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> + 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> + 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="idp1605872"></a>Examples</h3> + <h3 class="title"><a id="idp1182752"></a>Examples</h3> </div> </div> </div> - <p> - Store all files in the directory <code class="filename">/a/database</code>: - </p> + <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> + <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> + <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->set_data_dir(dbenv, "datadir"); +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->set_data_dir(dbenv, "/b/data2"); -dbenv->set_data_dir(dbenv, "data1"); + <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> @@ -334,7 +347,8 @@ dbenv->open(dbenv, "/a/database", flags, mode);</pre> <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="40%" align="left" valign="top">DB_CONFIG configuration + file </td> <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> |