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
|
<! "@(#)naming.so 10.12 (Sleepycat) 11/1/98">
<!Copyright 1997, 1998 by Sleepycat Software, Inc. All rights reserved.>
<html>
<body bgcolor=white>
<head>
<title>Berkeley DB Reference Guide: Environment</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btr
ee,hash,hashing,transaction,transactions,locking,logging,access method,access me
thods,java,C,C++">
</head>
<h3>Berkeley DB Reference Guide: Environment</h3>
<p>
<h1 align=center>File naming</h1>
<p>
The most important task of the environment is to structure file naming
within Berkeley DB.
<p>
Each of the locking, logging, memory pool and transaction subsystems of
Berkeley DB require shared memory regions, backed by the filesystem.
Further, cooperating applications (or multiple invocations of the same
application) must agree on the location of the shared memory regions and
other files used by the Berkeley DB subsystems, the log files used by the logging
subsystem, and, of course, the data files.
<p>
Although it is possible to specify full pathnames to all Berkeley DB functions
this is cumbersome and requires that applications be recompiled when
database files are moved.
The <a href="../../api_c/DbEnv/appinit.html">db_appinit</a> function makes it possible to place database files in a
single directory, or in multiple directories, grouped by their function
within the database.
<p>
Applications are normally expected to specify a single directory home for
their database.
This can be done easily in the call to <a href="../../api_c/DbEnv/appinit.html">db_appinit</a> by specifying
a value for the <b>db_home</b> argument.
There are more complex configurations where it may be desirable to override
<b>db_home</b> or provide supplementary path information.
<p>
The following 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.
<dl compact>
<a name="db_home">
<p><dt><b>db_home</b><dd>
If the <b>db_home</b> argument to <a href="../../api_c/DbEnv/appinit.html">db_appinit</a> is non-NULL,
its value may be used as the database home, and files named relative
to its path.
<a name="DB_HOME">
<p><dt>DB_HOME<dd>
If the DB_HOME environment variable is set when <a href="../../api_c/DbEnv/appinit.html">db_appinit</a>
is called, its value may be used as the database home, and files named
relative to its path.
<a name="db_config">
<p><dt><b>db_config</b><dd>
The <b>db_config</b> argument to <a href="../../api_c/DbEnv/appinit.html">db_appinit</a> may be used to
specify an array of character strings of the format <b>NAME VALUE</b>,
that specify file name information for the Berkeley DB process' environment.
<p>
The characters delimiting the two parts of the entry may be one or more
whitespace characters, and trailing whitespace characters are discarded.
Each entry must specify both the NAME and the VALUE of the pair.
All entries with unrecognized NAME values will be ignored.
The <b>db_config</b> array must be NULL terminated.
<a name="DB_CONFIG">
<p><dt>DB_CONFIG<dd>
The same information specified to the <b>db_config</b> argument to
<a href="../../api_c/DbEnv/appinit.html">db_appinit</a> may be specified using a configuration file.
If a database home directory has been specified (either by the application
specifying a non-NULL <b>db_home</b> argument to <a href="../../api_c/DbEnv/appinit.html">db_appinit</a>,
or by the application setting the DB_USE_ENVIRON or DB_USE_ENVIRON_ROOT
flags and the DB_HOME environment variable being set),
any file named <b>DB_CONFIG</b> in the database home directory will be
read for lines of the format <b>NAME VALUE</b>.
<p>
The characters delimiting the two parts of the entry may be one or more
whitespace characters, and trailing whitespace characters are discarded.
All empty lines or lines whose first character is a whitespace or hash
(<b>#</b>) character will be ignored.
Each line must specify both the NAME and the VALUE of the pair.
All lines with unrecognized NAME values will be ignored.
</dl>
<p>
The following <b>NAME VALUE</b> pairs in the <b>db_config</b>
argument and the DB_CONFIG file are currently supported by Berkeley DB.
<dl compact>
<a name="DB_DATA_DIR">
<p><dt>DB_DATA_DIR<dd>
The path of a directory to be used as the location of the access method
data files, e.g., paths specified to the <a href="../../api_c/Db/open.html">db_open</a> function
will be relative to this path.
<p>
The DB_DATA_DIR paths are additive, and specifying more than one will result
in each specified directory being searched for database data files.
If multiple paths are specified, created data files will always be created
in the <b>first</b> directory specified.
<a name="DB_LOG_DIR">
<p><dt>DB_LOG_DIR<dd>
The path of a directory to be used as the location of logging files, e.g.,
files created by the Log Manager subsystem will be relative to this directory.
If specified, this is the directory name that will be passed to
<a href="../../api_c/DbLog/open.html">log_open</a>.
<a name="DB_TMP_DIR">
<p><dt>DB_TMP_DIR<dd>
The path of a directory to be used as the location of temporary files, e.g.,
files created to back in-memory access method databases will be created
relative to this path.
Note, these temporary files can potentially be quite large, depending on the
size of the database.
<p>
If DB_TMP_DIR is not specified, the following environment variables are
checked in order: <b>TMPDIR</b>, <b>TEMP</b>, <b>TMP</b>,
<b>TempFolder</b>.
If one of them is set, temporary files are created relative to the directory
it specifies.
<p>
If DB_TMP_DIR is not specified and none of the above environment variables
are set, the first possible one of the following directories is used:
<b>/var/tmp</b>, <b>/usr/tmp</b>, <b>/temp</b>, <b>/tmp</b>,
<b>C:/temp</b> and <b>C:/tmp</b>.
</dl>
<p>
The following describes the specific circumstances and order in which the
different ways of specifying file naming information are applied.
Specifically,
Berkeley DB file name processing proceeds sequentially through the following steps:
<dl compact>
<p><dt>absolute pathnames<dd>If the file name specified to a Berkeley DB function is an absolute pathname,
that file name is used without modification by Berkeley DB.
<p>
On UNIX systems, an absolute pathname is defined as any pathname that
begins with a leading slash (<b>/</b>).
<p>
On Windows systems, an absolute pathname is any pathname that begins with
a leading slash or leading backslash (<b>\</b>), or any pathname
beginning with a single alphabetic character, a colon and a leading slash
or backslash, e.g., <b>C:/tmp</b>.
<p><dt>DB_CONFIG<dd>
If a relevant configuration string (e.g., DB_DATA_DIR), is specified in the
DB_CONFIG configuration file, the VALUE from the <b>NAME VALUE</b> pair
is prepended to the current file name.
If the resulting file name begins with a leading slash,
the file name is used without further modification by Berkeley DB.
<p>
The DB_CONFIG configuration file is intended to permit systems to customize
file location for a database independent of applications using that database.
For example,
a database administrator can move the database log and data files to a
different location without application recompilation.
<p><dt><b>db_config</b><dd>
If a relevant configuration string (e.g., DB_DATA_DIR), is specified in the
<b>db_config</b> argument and is not specified in the DB_CONFIG file,
the VALUE from the <b>NAME VALUE</b> pair is prepended to the current
file name.
If the resulting file name begins with a leading slash,
the file name is used without further modification by Berkeley DB.
<p>
The <b>db_config</b> argument is intended to permit applications to
customize file location for a database.
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><dt>DB_HOME<dd>
If the DB_HOME environment variable was set, (and the application has set
the appropriate DB_USE_ENVIRON or DB_USE_ENVIRON_ROOT environment variable),
its value is prepended to the current file name.
If the resulting file name begins with a leading slash,
the file name is used without further modification by Berkeley DB.
<p>
The DB_HOME environment variable is intended to permit users and system
administrators to override application and installation defaults, e.g.,
<p><ul><pre>env DB_HOME=/database/my_home application</pre></ul><p>
Alternatively, application writers are encouraged to support the
<b>-h</b> option found in the supporting Berkeley DB utilities to let users
specify a database home.
<p><dt><b>db_home</b><dd>
If the application specified a non-NULL <b>db_home</b> argument to
<a href="../../api_c/DbEnv/appinit.html">db_appinit</a> (and the database home was not already specified
using the DB_HOME environment variable) its value is prepended to the
current file name.
If the resulting file name begins with a leading slash,
the file name is used without further modification by Berkeley DB.
<p><dt>(nothing)<dd>
Finally, all file names are interpreted relative to the current working
directory of the process.
</dl>
<p>
The common model for a Berkeley DB environment is one where only the DB_HOME
environment variable, or the <b>db_home</b> argument, is specified.
In this case, all data files will be presumed to be relative to that
directory, and all files created by the Berkeley DB subsystems will be created
in that directory.
<p>
The more complex model for a transaction environment might be one where
a database home is specified, using either the DB_HOME environment variable
or the <b>db_home</b> argument to <a href="../../api_c/DbEnv/appinit.html">db_appinit</a>, and then
DB_DATA_DIR and DB_LOG_DIR are set to the relative path names of directories
underneath the home directory using the <b>db_config</b> argument to
<a href="../../api_c/DbEnv/appinit.html">db_appinit</a> or the DB_CONFIG file.
<h1>Examples</h1>
Store all files in the directory <b>/a/database</b>:
<p>
<p><ul><pre>
db_appinit("/a/database", NULL, ...);
</pre></ul><p>
<p>
Create temporary backing files in <b>/b/temporary</b>, and all other files
in <b>/a/database</b>:
<p>
<p><ul><pre>
char *config = {
"DB_TMP_DIR /b/temporary",
NULL
};
db_appinit("/a/database", config, ...);
</pre></ul><p>
<p>
Store data files in <b>/a/database/datadir</b>, log files in
<b>/a/database/logdir</b>, and all other files in the directory
<b>/a/database</b>:
<p>
<p><ul><pre>
char *config = {
"DB_DATA_DIR datadir",
"DB_LOG_DIR logdir",
NULL
};
db_appinit("/a/database", config, ...);
</pre></ul><p>
<p>
Store data files in <b>/a/database/data1</b> and <b>/b/data2</b>,
and all other files in the directory <b>/a/database</b>.
Any data files that are created will be created in <b>/b/data2</b>,
because it is the first DB_DATA_DIR directory specified:
<p>
<p><ul><pre>
char *config = {
"DB_DATA_DIR /b/data2",
"DB_DATA_DIR data1",
NULL
};
db_appinit("/a/database", config, ...);
</pre></ul><p>
<p>
See the file <b>examples/ex_appinit.c</b>
in the Berkeley DB source distribution for an example of how an application might
use <a href="../../api_c/DbEnv/appinit.html">db_appinit</a> to configure its Berkeley DB environment.
<p>
<a href="../../ref/env/open.html"><img src="../../images/prev.gif"></a>
<a href="../../ref/toc.html"><img src="../../images/toc.gif"></a>
<a href="../../ref/env/security.html"><img src="../../images/next.gif"></a>
</tt>
</body>
</html>
|
