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
|
<! "@(#)open.so 10.16 (Sleepycat) 10/30/98">
<!Copyright 1997, 1998 by Sleepycat Software, Inc. All rights reserved.>
<html>
<body bgcolor=white>
<head>
<title>Berkeley DB: db_open</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>
<h1>db_open</h1>
<hr size=1 noshade>
<tt>
<h3>
<pre>
#include <db.h>
<p>
int
db_open(const char *file, DBTYPE type, u_int32_t flags,
int mode, DB_ENV *dbenv, DB_INFO *dbinfo, DB **dbpp);
</pre>
</h3>
<h1>Description</h1>
<p>
The currently supported Berkeley DB file formats (or <i>access methods</i>)
are B+tree, Extended Linear Hashing, and Fixed and Variable-length records.
Generally, these are referred to as the <i>btree</i>, <i>hash</i>
and <i>recno</i> access methods.
The btree format is a representation of a sorted, balanced tree structure.
The hashed format is an extensible, dynamic hashing scheme.
The recno format supports fixed or variable length records (optionally
retrieved from a flat text file).
<p>
Storage and retrieval for the Berkeley DB access methods are based on key/data
pairs, or <a href="../../api_c/Dbt/dbt.html">DBT structures</a>.
<p>
The db_open function opens the database represented by
<b>file</b> for both reading and writing.
Files never intended to be shared or preserved on disk may be created by
setting the file parameter to NULL.
<p>
Note, while most of the access methods use <b>file</b> as the name of an
underlying file on disk, this is not guaranteed.
Also, calling db_open is a reasonably expensive operation.
(This is based on a model where the DBMS keeps a set of files open for a
long time rather than opening and closing them on each query.)
<p>
The <b>type</b> argument is of type DBTYPE, and must be set to one of
DB_BTREE, DB_HASH, DB_RECNO or DB_UNKNOWN. If <b>type</b> is DB_UNKNOWN,
the database must already exist and db_open will then determine
if it is of type DB_BTREE, DB_HASH or DB_RECNO.
<p>
The <b>flags</b> and <b>mode</b> arguments specify how files will be opened
and/or created if they do not already exist.
The flags value is specified by logically <b>OR</b>'ing together one or more of the
following values:
<dl compact>
<a name="DB_CREATE">
<p><dt>DB_CREATE<dd>Create any underlying files, as necessary. If the files do not already
exist and the DB_CREATE flag is not specified, the call will fail.
<a name="DB_NOMMAP">
<p><dt>DB_NOMMAP<dd>Do not map this file (see <a href="../../api_c/DbMpool/open.html">memp_open</a> for further information).
<a name="DB_RDONLY">
<p><dt>DB_RDONLY<dd>Open the database for reading only.
Any attempt to modify items in the database will fail regardless of the
actual permissions of any underlying files.
<a name="DB_THREAD">
<p><dt>DB_THREAD<dd>Cause the m4_reg(DB) handle returned by db_open to be useable
by multiple threads within a single address space, i.e., to be
<i>free-threaded</i>.
<a name="DB_TRUNCATE">
<p><dt>DB_TRUNCATE<dd>Logically truncate the database if it exists, i.e., behave as if the
database were just created, discarding any previous contents.
</dl>
<p>
All files created by the access methods are created with mode <b>mode</b> (as described
in <b>chmod</b>(2)) and modified by the process' umask value at the time
of creation (see <b>umask</b>(2)))).
The group ownership of created files is based on the system and directory
defaults, and is not further specified by Berkeley DB.
<p>
When sharing a database environment with other processes, it is necessary
to provide the access methods with database environment information. The
<a href="../../api_c/DbEnv/env.html">db_env argument</a> to db_open
is intended for this purpose.
<p>
Additionally, there is access method specific information that may be
specified when calling db_open. The
<a href="../../api_c/DbInfo/info.html">db_info argument</a> to db_open
is intended for this purpose.
<p>
Before returning, the db_open function copies a pointer to a DB
structure, into the memory location referenced by <b>dbpp</b>.
This structure describes a database type and includes a set of functions
to perform various database actions.
Each of these functions takes a pointer to a DB structure, and may take
a pointer to one or more DBT structures and a flag value as well.
The set of functions are described in the following manual pages:
<a href="../../api_c/Db/close.html">DB->close</a>,
<a href="../../api_c/Db/cursor.html">DB->cursor</a>,
<a href="../../api_c/Db/del.html">DB->del</a>,
<a href="../../api_c/Db/fd.html">DB->fd</a>,
<a href="../../api_c/Db/get.html">DB->get</a>,
<a href="../../api_c/Db/put.html">DB->put</a>
and
<a href="../../api_c/Db/sync.html">DB->sync</a>.
<p>
In addition, the returned DB structure includes the following
fields:
<dl compact>
<a name="type">
<p><dt>DBTYPE type;<dd>The type of the underlying access method (and file format).
Set to one of DB_BTREE, DB_HASH or DB_RECNO.
This field may be used to determine the type of the database after a return
from db_open with the <b>type</b> argument set to DB_UNKNOWN.
<a name="byteswapped">
<p><dt>int byteswapped;<dd>Set to 0 if the underlying database files were created on an architecture
of the same byte order as the current one, and 1 if they were not (i.e.,
big-endian on a little-endian machine or vice-versa).
This field may be used to determine if application data needs to be
adjusted for this architecture or not.
</dl>
<p>
The db_open
function returns the value of <b>errno</b> on failure, and 0 on success.
<h1>Environment Variables</h1>
<p>
<dl compact>
<p><dt>DB_HOME<dd>
If the <b>dbenv</b> argument to db_open was initialized using
<a href="../../api_c/DbEnv/appinit.html">db_appinit</a> the environment variable <b>DB_HOME</b> may
be used as the path of the database home for the interpretation of
the <b>dir</b>. Specifically, db_open is affected by the
configuration string value of DB_DATA_DIR.
</dl>
<p>
<h1>Errors</h1>
If a fatal error occurs in Berkeley DB, the db_open function may fail and return
DB_RUNRECOVERY, at which point all subsequent database calls will also
return DB_RUNRECOVERY.
<p>
The db_open
function may fail and return <b>errno</b>
for any of the errors specified for the following Berkeley DB and C library
functions:
<a href="../../api_c/Db/cursor.html">DB->cursor</a>,
<a href="../../api_c/Db/sync.html">DB->sync</a>,
DBcursor->c_close(3),
DBmemp->pgin(3),
DBmemp->pgout(3),
__account_page(3),
abort(3),
close(3),
dbenv->db_paniccall(3),
dbp->h_hash(3),
fcntl(3),
fflush(3),
fprintf(3),
free(3),
fstat(3),
fsync(3),
func(3),
getenv(3),
getpid(3),
getuid(3),
isdigit(3),
<a href="../../api_c/DbLockTab/get.html">lock_get</a>,
<a href="../../api_c/DbLockTab/id.html">lock_id</a>,
<a href="../../api_c/DbLock/put.html">lock_put</a>,
<a href="../../api_c/DbLockTab/vec.html">lock_vec</a>,
<a href="../../api_c/DbLog/compare.html">log_compare</a>,
<a href="../../api_c/DbLog/flush.html">log_flush</a>,
<a href="../../api_c/DbLog/put.html">log_put</a>,
<a href="../../api_c/DbLog/db_register.html">log_register</a>,
<a href="../../api_c/DbLog/db_unregister.html">log_unregister</a>,
lseek(3),
malloc(3),
memcmp(3),
memcpy(3),
memmove(3),
<a href="../../api_c/DbMpool/close.html">memp_close</a>,
<a href="../../api_c/DbMpoolFile/close.html">memp_fclose</a>,
<a href="../../api_c/DbMpoolFile/get.html">memp_fget</a>,
<a href="../../api_c/DbMpoolFile/open.html">memp_fopen</a>,
<a href="../../api_c/DbMpoolFile/put.html">memp_fput</a>,
<a href="../../api_c/DbMpoolFile/set.html">memp_fset</a>,
<a href="../../api_c/DbMpoolFile/sync.html">memp_fsync</a>,
<a href="../../api_c/DbMpool/open.html">memp_open</a>,
<a href="../../api_c/DbMpool/db_register.html">memp_register</a>,
memset(3),
mmap(3),
munmap(3),
open(3),
pread(3),
pstat_getdynamic(3),
pwrite(3),
read(3),
realloc(3),
sigfillset(3),
sigprocmask(3),
stat(3),
strerror(3),
strlen(3),
sysconf(3),
time(3),
unlink(3),
vfprintf(3),
vsnprintf(3),
and
write(3).
<p>
In addition, the db_open
function may fail and return <b>errno</b>
for the following conditions:
<p>
<dl compact>
<p><dt>EAGAIN<dd>A lock was unavailable.
</dl>
<p>
<dl compact>
<p><dt>EINVAL<dd>An invalid flag value or parameter was specified (e.g., unknown database
type, page size, hash function, recno pad byte, byte order) or a flag value
or parameter that is incompatible with the current <b>file</b> specification.
<p>
The DB_THREAD flag was specified and spinlocks are not implemented for
this architecture.
<p>
There is a mismatch between the version number of <b>file</b> and the
software.
<p>
A <b>re_source</b> file was specified with either the DB_THREAD flag or a
non-NULL <b>tx_info</b> field in the DB_ENV argument to db_open.
<p><dt>ENOENT<dd>A non-existent <b>re_source</b> file was specified.
</dl>
<p>
<h1>See Also</h1>
<a href="../../api_c/DbEnv/appexit.html">db_appexit</a>,
<a href="../../api_c/DbEnv/appinit.html">db_appinit</a>,
<a href="../../api_c/DbEnv/version.html">db_version</a>,
<a href="../../api_c/Db/close.html">DB->close</a>,
<a href="../../api_c/Db/cursor.html">DB->cursor</a>,
<a href="../../api_c/Db/del.html">DB->del</a>,
<a href="../../api_c/Db/fd.html">DB->fd</a>,
<a href="../../api_c/Db/get.html">DB->get</a>,
<a href="../../api_c/Db/join.html">DB->join</a>,
db_open,
<a href="../../api_c/Db/put.html">DB->put</a>,
<a href="../../api_c/Db/stat.html">DB->stat</a>,
<a href="../../api_c/Db/sync.html">DB->sync</a>,
<a href="../../api_c/Dbc/close.html">DBcursor->c_close</a>,
<a href="../../api_c/Dbc/del.html">DBcursor->c_del</a>,
<a href="../../api_c/Dbc/get.html">DBcursor->c_get</a>
and
<a href="../../api_c/Dbc/put.html">DBcursor->c_put</a>.
</tt>
</body>
</html>
|
