Penguin
Recent Changes
Annotated edit history of dbopen(3) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 DBOPEN
2 !!!DBOPEN
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 KEY/DATA PAIRS
7 ERRORS
8 SEE ALSO
9 BUGS
10 ----
11 !!NAME
12
13
14 dbopen - database access methods
15 !!SYNOPSIS
16
17
18 __#include
19 __
20 !!DESCRIPTION
21
22
23 ''Dbopen'' is the library interface to database files.
24 The supported file formats are btree, hashed and UNIX file
25 oriented. The btree format is a representation of a sorted,
26 balanced tree structure. The hashed format is an extensible,
27 dynamic hashing scheme. The flat-file format is a byte
28 stream file with fixed or variable length records. The
29 formats and file format specific information are described
30 in detail in their respective manual pages btree(3),
31 hash(3) and recno(3).
32
33
34 Dbopen opens ''file'' for reading and/or writing. Files
35 never intended to be preserved on disk may be created by
36 setting the file parameter to NULL.
37
38
39 The ''flags'' and ''mode arguments'' are as specified
40 to the open(2) routine, however, only the O_CREAT,
41 O_EXCL, O_EXLOCK, O_NONBLOCK, O_RDONLY, O_RDWR, O_SHLOCK and
42 O_TRUNC flags are meaningful. (Note, opening a database file
43 O_WRONLY is not possible.)
44
45
46 The ''type'' argument is of type DBTYPE (as defined in
47 the
48 ''
49
50
51 The ''openinfo'' argument is a pointer to an access
52 method specific structure described in the access method's
53 manual page. If ''openinfo'' is NULL, each access method
54 will use defaults appropriate for the system and the access
55 method.
56
57
58 ''Dbopen'' returns a pointer to a DB structure on success
59 and NULL on error. The DB structure is defined in the
60 ''
61
62
63 typedef struct {
64 DBTYPE type;
65 int (*close)(DB *db);
66 int (*del)(DB *db, DB_TXN txnid, const DBT *key, u_int flags);
67 int (*fd)(DB *db, int *fdp);
68 int (*get)(DB *db, DB_TXN txnid, DBT *key, DBT *data, u_int flags);
69 int (*join)(DB *db, DBC **, u_int, DBC **);
70 int (*put)(DB *db, DB_TXN txnid, DBT *key, const DBT *data,
71 u_int flags);
72 int (*sync)(const DB *db, u_int flags);
73 int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags);
74 } DB;
75 These elements describe a database type and a set of functions performing various actions. These functions take a pointer to a structure as returned by ''dbopen'', and sometimes one or more pointers to key/data structures and a flag value.
76
77
78 type
79
80
81 The type of the underlying access method (and file
82 format).
83
84
85 close
86
87
88 A pointer to a routine to flush any cached information to
89 disk, free any allocated resources, and close the underlying
90 file(s). Since key/data pairs may be cached in memory,
91 failing to sync the file with a ''close'' or ''sync''
92 function may result in inconsistent or lost information.
93 ''Close'' routines return -1 on error (setting
94 ''errno'') and 0 on success.
95
96
97 del
98
99
100 A pointer to a routine to remove key/data pairs from the
101 database.
102
103
104 The parameter ''flag'' may be set to the following
105 value:
106
107
108 R_CURSOR
109
110
111 Delete the record referenced by the cursor. The cursor must
112 have previously been initialized.
113
114
115 ''Delete'' routines return -1 on error (setting
116 ''errno''), 0 on success, and 1 if the specified
117 ''key'' was not in the file.
118
119
120 fd
121
122
123 A pointer to a routine which returns a file descriptor
124 representative of the underlying database. A file descriptor
125 referencing the same file will be returned to all processes
126 which call ''dbopen'' with the same ''file'' name.
127 This file descriptor may be safely used as an argument to
128 the fcntl(2) and flock(2) locking functions.
129 The file descriptor is not necessarily associated with any
130 of the underlying files used by the access method. No file
131 descriptor is available for in memory databases. ''Fd''
132 routines return -1 on error (setting ''errno''), and the
133 file descriptor on success.
134
135
136 get
137
138
139 A pointer to a routine which is the interface for keyed
140 retrieval from the database. The address and length of the
141 data associated with the specified ''key'' are returned
142 in the structure referenced by ''data''. ''Get''
143 routines return -1 on error (setting ''errno''), 0 on
144 success, and 1 if the ''key'' was not in the
145 file.
146
147
148 put
149
150
151 A pointer to a routine to store key/data pairs in the
152 database.
153
154
155 The parameter ''flag'' may be set to one of the following
156 values:
157
158
159 R_CURSOR
160
161
162 Replace the key/data pair referenced by the cursor. The
163 cursor must have previously been initialized.
164
165
166 R_IAFTER
167
168
169 Append the data immediately after the data referenced by
170 ''key'', creating a new key/data pair. The record number
171 of the appended key/data pair is returned in the ''key''
172 structure. (Applicable only to the DB_RECNO access
173 method.)
174
175
176 R_IBEFORE
177
178
179 Insert the data immediately before the data referenced by
180 ''key'', creating a new key/data pair. The record number
181 of the inserted key/data pair is returned in the ''key''
182 structure. (Applicable only to the DB_RECNO access
183 method.)
184
185
186 R_NOOVERWRITE
187
188
189 Enter the new key/data pair only if the key does not
190 previously exist.
191
192
193 R_SETCURSOR
194
195
196 Store the key/data pair, setting or initializing the
197 position of the cursor to reference it. (Applicable only to
198 the DB_BTREE and DB_RECNO access methods.)
199
200
201 R_SETCURSOR is available only for the DB_BTREE and DB_RECNO
202 access methods because it implies that the keys have an
203 inherent order which does not change.
204
205
206 R_IAFTER and R_IBEFORE are available only for the DB_RECNO
207 access method because they each imply that the access method
208 is able to create new keys. This is only true if the keys
209 are ordered and independent, record numbers for
210 example.
211
212
213 The default behavior of the ''put'' routines is to enter
214 the new key/data pair, replacing any previously existing
215 key.
216
217
218 ''Put'' routines return -1 on error (setting
219 ''errno''), 0 on success, and 1 if the R_NOOVERWRITE
220 ''flag'' was set and the key already exists in the
221 file.
222
223
224 seq
225
226
227 A pointer to a routine which is the interface for sequential
228 retrieval from the database. The address and length of the
229 key are returned in the structure referenced by ''key'',
230 and the address and length of the data are returned in the
231 structure referenced by ''data''.
232
233
234 Sequential key/data pair retrieval may begin at any time,
235 and the position of the ``cursor'' is not affected by calls
236 to the ''del'', ''get'', ''put'', or ''sync''
237 routines. Modifications to the database during a sequential
238 scan will be reflected in the scan, i.e. records inserted
239 behind the cursor will not be returned while records
240 inserted in front of the cursor will be
241 returned.
242
243
244 The flag value __must__ be set to one of the following
245 values:
246
247
248 R_CURSOR
249
250
251 The data associated with the specified key is returned. This
252 differs from the ''get'' routines in that it sets or
253 initializes the cursor to the location of the key as well.
254 (Note, for the DB_BTREE access method, the returned key is
255 not necessarily an exact match for the specified key. The
256 returned key is the smallest key greater than or equal to
257 the specified key, permitting partial key matches and range
258 searches.)
259
260
261 R_FIRST
262
263
264 The first key/data pair of the database is returned, and the
265 cursor is set or initialized to reference it.
266
267
268 R_LAST
269
270
271 The last key/data pair of the database is returned, and the
272 cursor is set or initialized to reference it. (Applicable
273 only to the DB_BTREE and DB_RECNO access
274 methods.)
275
276
277 R_NEXT
278
279
280 Retrieve the key/data pair immediately after the cursor. If
281 the cursor is not yet set, this is the same as the R_FIRST
282 flag.
283
284
285 R_PREV
286
287
288 Retrieve the key/data pair immediately before the cursor. If
289 the cursor is not yet set, this is the same as the R_LAST
290 flag. (Applicable only to the DB_BTREE and DB_RECNO access
291 methods.)
292
293
294 R_LAST and R_PREV are available only for the DB_BTREE and
295 DB_RECNO access methods because they each imply that the
296 keys have an inherent order which does not
297 change.
298
299
300 ''Seq'' routines return -1 on error (setting
301 ''errno''), 0 on success and 1 if there are no key/data
302 pairs less than or greater than the specified or current
303 key. If the DB_RECNO access method is being used, and if the
304 database file is a character special file and no complete
305 key/data pairs are currently available, the ''seq''
306 routines return 2.
307
308
309 sync
310
311
312 A pointer to a routine to flush any cached information to
313 disk. If the database is in memory only, the ''sync''
314 routine has no effect and will always succeed.
315
316
317 The flag value may be set to the following
318 value:
319
320
321 R_RECNOSYNC
322
323
324 If the DB_RECNO access method is being used, this flag
325 causes the sync routine to apply to the btree file which
326 underlies the recno file, not the recno file itself. (See
327 the ''bfname'' field of the recno(3) manual page
328 for more information.)
329
330
331 ''Sync'' routines return -1 on error (setting
332 ''errno'') and 0 on success.
333 !!KEY/DATA PAIRS
334
335
336 Access to all file types is based on key/data pairs. Both
337 keys and data are represented by the following data
338 structure:
339
340
341 typedef struct {
342
343
344 void *data;
345 size_t size;
346
347
348 } DBT;
349
350
351 The elements of the DBT structure are defined as
352 follows:
353
354
355 data
356
357
358 A pointer to a byte string.
359
360
361 size
362
363
364 The length of the byte string.
365
366
367 Key and data byte strings may reference strings of
368 essentially unlimited length although any two of them must
369 fit into available memory at the same time. It should be
370 noted that the access methods provide no guarantees about
371 byte string alignment.
372 !!ERRORS
373
374
375 The ''dbopen'' routine may fail and set ''errno'' for
376 any of the errors specified for the library routines
377 open(2) and malloc(3) or the
378 following:
379
380
381 [[EFTYPE]
382
383
384 A file is incorrectly formatted.
385
386
387 [[EINVAL]
388
389
390 A parameter has been specified (hash function, pad byte
391 etc.) that is incompatible with the current file
392 specification or which is not meaningful for the function
393 (for example, use of the cursor without prior
394 initialization) or there is a mismatch between the version
395 number of file and the software.
396
397
398 The ''close'' routines may fail and set ''errno'' for
399 any of the errors specified for the library routines
400 close(2), read(2), write(2),
401 free(3), or fsync(2).
402
403
404 The ''del'', ''get'', ''put'' and ''seq''
405 routines may fail and set ''errno'' for any of the errors
406 specified for the library routines read(2),
407 write(2), free(3) or
408 malloc(3).
409
410
411 The ''fd'' routines will fail and set ''errno'' to
412 ENOENT for in memory databases.
413
414
415 The ''sync'' routines may fail and set ''errno'' for
416 any of the errors specified for the library routine
417 fsync(2).
418 !!SEE ALSO
419
420
421 btree(3), hash(3), mpool(3),
422 recno(3)
423
424
425 ''LIBTP: Portable, Modular Transactions for UNIX'', Margo
426 Seltzer, Michael Olson, USENIX proceedings, Winter
427 1992.
428 !!BUGS
429
430
431 The typedef DBT is a mnemonic for ``data base thang'', and
432 was used because noone could think of a reasonable name that
433 wasn't already used.
434
435
436 The file descriptor interface is a kluge and will be deleted
437 in a future version of the interface.
438
439
440 None of the access methods provide any form of concurrent
441 access, locking, or transactions.
442 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.