← Back to branch summary

~ubuntu-branches/ubuntu/maverick/evolution-data-server/maverick-proposed

« back to all changes in this revision

Viewing changes to libdb/docs/ref/env/naming.html

  • Committer: Bazaar Package Importer
  • Author(s): Didier Roche
  • Date: 2010-05-17 17:02:06 UTC
  • mfrom: (1.1.79 upstream) (1.6.12 experimental)
  • Revision ID: james.westby@ubuntu.com-20100517170206-4ufr52vwrhh26yh0
Tags: 2.30.1-1ubuntu1
https://launchpad.net/bugs/42199
https://launchpad.net/bugs/229669
https://launchpad.net/bugs/173703
https://launchpad.net/bugs/360344
https://launchpad.net/bugs/508494
* Merge from debian experimental. Remaining change:
  (LP: #42199, #229669, #173703, #360344, #508494)
  + debian/control:
    - add Vcs-Bzr tag
    - don't use libgnome
    - Use Breaks instead of Conflicts against evolution 2.25 and earlier.
  + debian/evolution-data-server.install,
    debian/patches/45_libcamel_providers_version.patch:
    - use the upstream versioning, not a Debian-specific one 
  + debian/libedata-book1.2-dev.install, debian/libebackend-1.2-dev.install,
    debian/libcamel1.2-dev.install, debian/libedataserverui1.2-dev.install:
    - install html documentation
  + debian/rules:
    - don't build documentation it's shipped with the tarball

Show diffs side-by-side

added added

removed removed

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