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
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>File naming</title>
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
<link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
<link rel="up" href="env.html" title="Chapter 9. The Berkeley DB Environment" />
<link rel="prev" href="env_db_config.html" title="DB_CONFIG configuration file" />
<link rel="next" href="env_region.html" title="Shared memory regions" />
</head>
<body>
<div xmlns="" class="navheader">
<div class="libver">
<p>Library Version 12.1.6.1</p>
</div>
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">File naming</th>
</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>
<td width="20%" align="right"> <a accesskey="n" href="env_region.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="env_naming"></a>File naming</h2>
</div>
</div>
</div>
<div class="toc">
<dl>
<dt>
<span class="sect2">
<a href="env_naming.html#idp1149160">Specifying file naming to Berkeley DB</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="env_naming.html#idp1160456">Filename resolution in Berkeley DB</a>
</span>
</dt>
<dt>
<span class="sect2">
<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>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<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>
<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>
<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>
<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>
</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>
<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>
</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>
</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>
</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>
</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>
</dd>
<dt>
<span class="term">
<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>
</dl>
</div>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<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>
<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>
</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, 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>
<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>
<dt>
<span class="term">default</span>
</dt>
<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>
<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="idp1182752"></a>Examples</h3>
</div>
</div>
</div>
<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>
<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>
<pre class="programlisting">dbenv->set_lg_dir(dbenv, "logdir");
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->add_data_dir(dbenv, "/b/data2");
dbenv->add_data_dir(dbenv, "data1");
dbenv->open(dbenv, "/a/database", flags, mode);</pre>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="env_db_config.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="env.html">Up</a>
</td>
<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="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Shared memory regions</td>
</tr>
</table>
</div>
</body>
</html>
|
