]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1990, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
3 | .\" | |
47009d5e | 4 | .\" SPDX-License-Identifier: BSD-4-Clause-UC |
fea681da MK |
5 | .\" |
6 | .\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94 | |
7 | .\" | |
1ae6b2c7 | 8 | .TH DBOPEN 3 2017-09-15 GNU "Linux Programmer's Manual" |
fea681da MK |
9 | .UC 7 |
10 | .SH NAME | |
11 | dbopen \- database access methods | |
b813014f AC |
12 | .SH LIBRARY |
13 | Standard C library | |
14 | .RI ( libc ", " \-lc ) | |
fea681da MK |
15 | .SH SYNOPSIS |
16 | .nf | |
b9f02710 MK |
17 | .B #include <sys/types.h> |
18 | .B #include <limits.h> | |
19 | .B #include <db.h> | |
76f42241 | 20 | .B #include <fcntl.h> |
f90f031e | 21 | .PP |
b9f02710 | 22 | .BI "DB *dbopen(const char *" file ", int " flags ", int " mode \ |
c13182ef | 23 | ", DBTYPE " type , |
b9f02710 | 24 | .BI " const void *" openinfo ); |
fea681da MK |
25 | .fi |
26 | .SH DESCRIPTION | |
df21098d MK |
27 | .IR "Note well" : |
28 | This page documents interfaces provided in glibc up until version 2.1. | |
29 | Since version 2.2, glibc no longer provides these interfaces. | |
30 | Probably, you are looking for the APIs provided by the | |
31 | .I libdb | |
32 | library instead. | |
847e0d88 | 33 | .PP |
8a9648b9 | 34 | .BR dbopen () |
fea681da | 35 | is the library interface to database files. |
735334d4 | 36 | The supported file formats are btree, hashed, and UNIX file oriented. |
fea681da MK |
37 | The btree format is a representation of a sorted, balanced tree structure. |
38 | The hashed format is an extensible, dynamic hashing scheme. | |
39 | The flat-file format is a byte stream file with fixed or variable length | |
40 | records. | |
76c637e1 | 41 | The formats and file-format-specific information are described in detail |
fea681da | 42 | in their respective manual pages |
31e9a9ec | 43 | .BR btree (3), |
9af134cd | 44 | .BR hash (3), |
fea681da | 45 | and |
31e9a9ec | 46 | .BR recno (3). |
fea681da | 47 | .PP |
8a9648b9 MK |
48 | .BR dbopen () |
49 | opens | |
fea681da MK |
50 | .I file |
51 | for reading and/or writing. | |
52 | Files never intended to be preserved on disk may be created by setting | |
c4bb193f MK |
53 | the |
54 | .I file | |
55 | argument to NULL. | |
fea681da MK |
56 | .PP |
57 | The | |
58 | .I flags | |
59 | and | |
60 | .I mode | |
61 | arguments are as specified to the | |
31e9a9ec | 62 | .BR open (2) |
d9a10d9d MK |
63 | routine, however, only the |
64 | .BR O_CREAT , | |
65 | .BR O_EXCL , | |
66 | .BR O_EXLOCK , | |
67 | .BR O_NONBLOCK , | |
68 | .BR O_RDONLY , | |
69 | .BR O_RDWR , | |
70 | .BR O_SHLOCK , | |
71 | and | |
c8fe3fa2 MK |
72 | .B O_TRUNC |
73 | flags are meaningful. | |
d9a10d9d MK |
74 | (Note, opening a database file |
75 | .B O_WRONLY | |
76 | is not possible.) | |
cebca1bd | 77 | .\"Three additional options may be specified by ORing |
fea681da MK |
78 | .\"them into the |
79 | .\".I flags | |
80 | .\"argument. | |
81 | .\".TP | |
82 | .\"DB_LOCK | |
83 | .\"Do the necessary locking in the database to support concurrent access. | |
84 | .\"If concurrent access isn't needed or the database is read-only this | |
85 | .\"flag should not be set, as it tends to have an associated performance | |
86 | .\"penalty. | |
87 | .\".TP | |
88 | .\"DB_SHMEM | |
89 | .\"Place the underlying memory pool used by the database in shared | |
90 | .\"memory. | |
91 | .\"Necessary for concurrent access. | |
92 | .\".TP | |
93 | .\"DB_TXN | |
94 | .\"Support transactions in the database. | |
95 | .\"The DB_LOCK and DB_SHMEM flags must be set as well. | |
96 | .PP | |
97 | The | |
98 | .I type | |
d9a10d9d MK |
99 | argument is of type |
100 | .I DBTYPE | |
101 | (as defined in the | |
a9a13a50 MK |
102 | .I <db.h> |
103 | include file) and | |
628d8d62 MK |
104 | may be set to |
105 | .BR DB_BTREE , | |
106 | .BR DB_HASH , | |
107 | or | |
108 | .BR DB_RECNO . | |
fea681da MK |
109 | .PP |
110 | The | |
111 | .I openinfo | |
76c637e1 | 112 | argument is a pointer to an access-method-specific structure described |
fea681da MK |
113 | in the access method's manual page. |
114 | If | |
115 | .I openinfo | |
116 | is NULL, each access method will use defaults appropriate for the system | |
117 | and the access method. | |
118 | .PP | |
8a9648b9 | 119 | .BR dbopen () |
4bd8c614 MK |
120 | returns a pointer to a |
121 | .I DB | |
122 | structure on success and NULL on error. | |
123 | The | |
124 | .I DB | |
125 | structure is defined in the | |
a9a13a50 MK |
126 | .I <db.h> |
127 | include file, and contains at | |
fea681da | 128 | least the following fields: |
51f5698d | 129 | .PP |
088a639b | 130 | .in +4n |
b8302363 | 131 | .EX |
fea681da | 132 | typedef struct { |
b9f02710 MK |
133 | DBTYPE type; |
134 | int (*close)(const DB *db); | |
aeb4b1fc | 135 | int (*del)(const DB *db, const DBT *key, unsigned int flags); |
b9f02710 | 136 | int (*fd)(const DB *db); |
207bc0d1 MK |
137 | int (*get)(const DB *db, DBT *key, DBT *data, |
138 | unsigned int flags); | |
b9f02710 | 139 | int (*put)(const DB *db, DBT *key, const DBT *data, |
aeb4b1fc MK |
140 | unsigned int flags); |
141 | int (*sync)(const DB *db, unsigned int flags); | |
207bc0d1 MK |
142 | int (*seq)(const DB *db, DBT *key, DBT *data, |
143 | unsigned int flags); | |
fea681da | 144 | } DB; |
b8302363 | 145 | .EE |
628d8d62 | 146 | .in |
fea681da MK |
147 | .PP |
148 | These elements describe a database type and a set of functions performing | |
149 | various actions. | |
150 | These functions take a pointer to a structure as returned by | |
8a9648b9 | 151 | .BR dbopen (), |
fea681da MK |
152 | and sometimes one or more pointers to key/data structures and a flag value. |
153 | .TP | |
85467cb8 | 154 | .I type |
fea681da MK |
155 | The type of the underlying access method (and file format). |
156 | .TP | |
85467cb8 | 157 | .I close |
fea681da MK |
158 | A pointer to a routine to flush any cached information to disk, free any |
159 | allocated resources, and close the underlying file(s). | |
160 | Since key/data pairs may be cached in memory, failing to sync the file | |
161 | with a | |
162 | .I close | |
163 | or | |
164 | .I sync | |
165 | function may result in inconsistent or lost information. | |
85467cb8 | 166 | .I close |
fea681da MK |
167 | routines return \-1 on error (setting |
168 | .IR errno ) | |
169 | and 0 on success. | |
170 | .TP | |
85467cb8 | 171 | .I del |
fea681da MK |
172 | A pointer to a routine to remove key/data pairs from the database. |
173 | .IP | |
c4bb193f | 174 | The argument |
fea681da MK |
175 | .I flag |
176 | may be set to the following value: | |
177 | .RS | |
178 | .TP | |
628d8d62 | 179 | .B R_CURSOR |
fea681da MK |
180 | Delete the record referenced by the cursor. |
181 | The cursor must have previously been initialized. | |
182 | .RE | |
183 | .IP | |
85467cb8 | 184 | .I delete |
fea681da MK |
185 | routines return \-1 on error (setting |
186 | .IR errno ), | |
187 | 0 on success, and 1 if the specified | |
188 | .I key | |
189 | was not in the file. | |
190 | .TP | |
85467cb8 | 191 | .I fd |
fea681da MK |
192 | A pointer to a routine which returns a file descriptor representative |
193 | of the underlying database. | |
194 | A file descriptor referencing the same file will be returned to all | |
195 | processes which call | |
8a9648b9 | 196 | .BR dbopen () |
fea681da MK |
197 | with the same |
198 | .I file | |
199 | name. | |
200 | This file descriptor may be safely used as an argument to the | |
31e9a9ec | 201 | .BR fcntl (2) |
fea681da | 202 | and |
31e9a9ec | 203 | .BR flock (2) |
fea681da MK |
204 | locking functions. |
205 | The file descriptor is not necessarily associated with any of the | |
206 | underlying files used by the access method. | |
207 | No file descriptor is available for in memory databases. | |
85467cb8 | 208 | .I fd |
fea681da MK |
209 | routines return \-1 on error (setting |
210 | .IR errno ), | |
211 | and the file descriptor on success. | |
212 | .TP | |
85467cb8 | 213 | .I get |
fea681da MK |
214 | A pointer to a routine which is the interface for keyed retrieval from |
215 | the database. | |
216 | The address and length of the data associated with the specified | |
217 | .I key | |
218 | are returned in the structure referenced by | |
219 | .IR data . | |
85467cb8 | 220 | .I get |
fea681da MK |
221 | routines return \-1 on error (setting |
222 | .IR errno ), | |
223 | 0 on success, and 1 if the | |
224 | .I key | |
225 | was not in the file. | |
226 | .TP | |
85467cb8 | 227 | .I put |
fea681da MK |
228 | A pointer to a routine to store key/data pairs in the database. |
229 | .IP | |
c4bb193f | 230 | The argument |
fea681da MK |
231 | .I flag |
232 | may be set to one of the following values: | |
233 | .RS | |
234 | .TP | |
628d8d62 | 235 | .B R_CURSOR |
fea681da MK |
236 | Replace the key/data pair referenced by the cursor. |
237 | The cursor must have previously been initialized. | |
238 | .TP | |
628d8d62 | 239 | .B R_IAFTER |
fea681da MK |
240 | Append the data immediately after the data referenced by |
241 | .IR key , | |
242 | creating a new key/data pair. | |
243 | The record number of the appended key/data pair is returned in the | |
244 | .I key | |
245 | structure. | |
628d8d62 MK |
246 | (Applicable only to the |
247 | .B DB_RECNO | |
248 | access method.) | |
fea681da | 249 | .TP |
628d8d62 | 250 | .B R_IBEFORE |
fea681da MK |
251 | Insert the data immediately before the data referenced by |
252 | .IR key , | |
253 | creating a new key/data pair. | |
254 | The record number of the inserted key/data pair is returned in the | |
255 | .I key | |
256 | structure. | |
628d8d62 MK |
257 | (Applicable only to the |
258 | .B DB_RECNO | |
259 | access method.) | |
fea681da | 260 | .TP |
628d8d62 | 261 | .B R_NOOVERWRITE |
fea681da MK |
262 | Enter the new key/data pair only if the key does not previously exist. |
263 | .TP | |
628d8d62 | 264 | .B R_SETCURSOR |
fea681da MK |
265 | Store the key/data pair, setting or initializing the position of the |
266 | cursor to reference it. | |
628d8d62 MK |
267 | (Applicable only to the |
268 | .B DB_BTREE | |
269 | and | |
270 | .B DB_RECNO | |
271 | access methods.) | |
fea681da MK |
272 | .RE |
273 | .IP | |
628d8d62 MK |
274 | .B R_SETCURSOR |
275 | is available only for the | |
276 | .B DB_BTREE | |
277 | and | |
278 | .B DB_RECNO | |
279 | access | |
fea681da MK |
280 | methods because it implies that the keys have an inherent order |
281 | which does not change. | |
282 | .IP | |
628d8d62 MK |
283 | .B R_IAFTER |
284 | and | |
285 | .B R_IBEFORE | |
286 | are available only for the | |
287 | .B DB_RECNO | |
fea681da MK |
288 | access method because they each imply that the access method is able to |
289 | create new keys. | |
33a0ccb2 | 290 | This is true only if the keys are ordered and independent, record numbers |
fea681da MK |
291 | for example. |
292 | .IP | |
293 | The default behavior of the | |
294 | .I put | |
295 | routines is to enter the new key/data pair, replacing any previously | |
296 | existing key. | |
297 | .IP | |
85467cb8 | 298 | .I put |
fea681da MK |
299 | routines return \-1 on error (setting |
300 | .IR errno ), | |
628d8d62 MK |
301 | 0 on success, and 1 if the |
302 | .B R_NOOVERWRITE | |
fea681da MK |
303 | .I flag |
304 | was set and the key already exists in the file. | |
305 | .TP | |
85467cb8 | 306 | .I seq |
fea681da MK |
307 | A pointer to a routine which is the interface for sequential |
308 | retrieval from the database. | |
309 | The address and length of the key are returned in the structure | |
310 | referenced by | |
311 | .IR key , | |
312 | and the address and length of the data are returned in the | |
313 | structure referenced | |
314 | by | |
315 | .IR data . | |
316 | .IP | |
317 | Sequential key/data pair retrieval may begin at any time, and the | |
324633ae | 318 | position of the "cursor" is not affected by calls to the |
fea681da MK |
319 | .IR del , |
320 | .IR get , | |
321 | .IR put , | |
322 | or | |
323 | .I sync | |
324 | routines. | |
325 | Modifications to the database during a sequential scan will be reflected | |
988db661 | 326 | in the scan, that is, |
75b94dc3 | 327 | records inserted behind the cursor will not be returned |
fea681da MK |
328 | while records inserted in front of the cursor will be returned. |
329 | .IP | |
330 | The flag value | |
331 | .B must | |
332 | be set to one of the following values: | |
333 | .RS | |
334 | .TP | |
628d8d62 | 335 | .B R_CURSOR |
fea681da MK |
336 | The data associated with the specified key is returned. |
337 | This differs from the | |
338 | .I get | |
339 | routines in that it sets or initializes the cursor to the location of | |
340 | the key as well. | |
628d8d62 MK |
341 | (Note, for the |
342 | .B DB_BTREE | |
343 | access method, the returned key is not necessarily an | |
fea681da MK |
344 | exact match for the specified key. |
345 | The returned key is the smallest key greater than or equal to the specified | |
346 | key, permitting partial key matches and range searches.) | |
347 | .TP | |
628d8d62 | 348 | .B R_FIRST |
fea681da MK |
349 | The first key/data pair of the database is returned, and the cursor |
350 | is set or initialized to reference it. | |
351 | .TP | |
628d8d62 | 352 | .B R_LAST |
fea681da MK |
353 | The last key/data pair of the database is returned, and the cursor |
354 | is set or initialized to reference it. | |
628d8d62 MK |
355 | (Applicable only to the |
356 | .B DB_BTREE | |
357 | and | |
358 | .B DB_RECNO | |
359 | access methods.) | |
fea681da | 360 | .TP |
628d8d62 | 361 | .B R_NEXT |
fea681da | 362 | Retrieve the key/data pair immediately after the cursor. |
628d8d62 MK |
363 | If the cursor is not yet set, this is the same as the |
364 | .B R_FIRST | |
365 | flag. | |
fea681da | 366 | .TP |
628d8d62 | 367 | .B R_PREV |
fea681da | 368 | Retrieve the key/data pair immediately before the cursor. |
628d8d62 MK |
369 | If the cursor is not yet set, this is the same as the |
370 | .B R_LAST | |
371 | flag. | |
372 | (Applicable only to the | |
373 | .B DB_BTREE | |
374 | and | |
375 | .B DB_RECNO | |
376 | access methods.) | |
fea681da MK |
377 | .RE |
378 | .IP | |
628d8d62 MK |
379 | .B R_LAST |
380 | and | |
381 | .B R_PREV | |
382 | are available only for the | |
383 | .B DB_BTREE | |
384 | and | |
385 | .B DB_RECNO | |
fea681da MK |
386 | access methods because they each imply that the keys have an inherent |
387 | order which does not change. | |
388 | .IP | |
85467cb8 | 389 | .I seq |
fea681da MK |
390 | routines return \-1 on error (setting |
391 | .IR errno ), | |
392 | 0 on success and 1 if there are no key/data pairs less than or greater | |
393 | than the specified or current key. | |
628d8d62 MK |
394 | If the |
395 | .B DB_RECNO | |
396 | access method is being used, and if the database file | |
fea681da MK |
397 | is a character special file and no complete key/data pairs are currently |
398 | available, the | |
399 | .I seq | |
400 | routines return 2. | |
401 | .TP | |
85467cb8 | 402 | .I sync |
fea681da MK |
403 | A pointer to a routine to flush any cached information to disk. |
404 | If the database is in memory only, the | |
405 | .I sync | |
406 | routine has no effect and will always succeed. | |
407 | .IP | |
408 | The flag value may be set to the following value: | |
409 | .RS | |
410 | .TP | |
628d8d62 MK |
411 | .B R_RECNOSYNC |
412 | If the | |
413 | .B DB_RECNO | |
414 | access method is being used, this flag causes | |
fea681da MK |
415 | the sync routine to apply to the btree file which underlies the |
416 | recno file, not the recno file itself. | |
417 | (See the | |
418 | .I bfname | |
419 | field of the | |
31e9a9ec | 420 | .BR recno (3) |
fea681da MK |
421 | manual page for more information.) |
422 | .RE | |
423 | .IP | |
85467cb8 | 424 | .I sync |
fea681da MK |
425 | routines return \-1 on error (setting |
426 | .IR errno ) | |
427 | and 0 on success. | |
73d8cece | 428 | .SS Key/data pairs |
fea681da MK |
429 | Access to all file types is based on key/data pairs. |
430 | Both keys and data are represented by the following data structure: | |
e646a1ba | 431 | .PP |
088a639b | 432 | .in +4n |
e646a1ba | 433 | .EX |
fea681da | 434 | typedef struct { |
628d8d62 MK |
435 | void *data; |
436 | size_t size; | |
fea681da | 437 | } DBT; |
b8302363 | 438 | .EE |
628d8d62 | 439 | .in |
fea681da | 440 | .PP |
628d8d62 MK |
441 | The elements of the |
442 | .I DBT | |
443 | structure are defined as follows: | |
fea681da | 444 | .TP |
85467cb8 | 445 | .I data |
fea681da MK |
446 | A pointer to a byte string. |
447 | .TP | |
85467cb8 | 448 | .I size |
fea681da MK |
449 | The length of the byte string. |
450 | .PP | |
451 | Key and data byte strings may reference strings of essentially unlimited | |
452 | length although any two of them must fit into available memory at the same | |
453 | time. | |
454 | It should be noted that the access methods provide no guarantees about | |
455 | byte string alignment. | |
456 | .SH ERRORS | |
457 | The | |
8a9648b9 | 458 | .BR dbopen () |
fea681da MK |
459 | routine may fail and set |
460 | .I errno | |
461 | for any of the errors specified for the library routines | |
31e9a9ec | 462 | .BR open (2) |
fea681da | 463 | and |
31e9a9ec | 464 | .BR malloc (3) |
fea681da MK |
465 | or the following: |
466 | .TP | |
747944fe | 467 | .B EFTYPE |
fea681da MK |
468 | A file is incorrectly formatted. |
469 | .TP | |
747944fe | 470 | .B EINVAL |
61e1aee0 | 471 | A parameter has been specified (hash function, pad byte, etc.) that is |
fea681da MK |
472 | incompatible with the current file specification or which is not |
473 | meaningful for the function (for example, use of the cursor without | |
474 | prior initialization) or there is a mismatch between the version | |
475 | number of file and the software. | |
476 | .PP | |
477 | The | |
478 | .I close | |
479 | routines may fail and set | |
480 | .I errno | |
481 | for any of the errors specified for the library routines | |
31e9a9ec MK |
482 | .BR close (2), |
483 | .BR read (2), | |
484 | .BR write (2), | |
485 | .BR free (3), | |
fea681da | 486 | or |
31e9a9ec | 487 | .BR fsync (2). |
fea681da MK |
488 | .PP |
489 | The | |
490 | .IR del , | |
491 | .IR get , | |
a797afac | 492 | .IR put , |
fea681da MK |
493 | and |
494 | .I seq | |
495 | routines may fail and set | |
496 | .I errno | |
497 | for any of the errors specified for the library routines | |
31e9a9ec MK |
498 | .BR read (2), |
499 | .BR write (2), | |
aa0da2b9 | 500 | .BR free (3), |
fea681da | 501 | or |
31e9a9ec | 502 | .BR malloc (3). |
fea681da MK |
503 | .PP |
504 | The | |
505 | .I fd | |
506 | routines will fail and set | |
507 | .I errno | |
628d8d62 MK |
508 | to |
509 | .B ENOENT | |
510 | for in memory databases. | |
fea681da MK |
511 | .PP |
512 | The | |
513 | .I sync | |
514 | routines may fail and set | |
515 | .I errno | |
516 | for any of the errors specified for the library routine | |
31e9a9ec | 517 | .BR fsync (2). |
fea681da | 518 | .SH BUGS |
628d8d62 MK |
519 | The typedef |
520 | .I DBT | |
324633ae | 521 | is a mnemonic for "data base thang", and was used |
9b13f770 | 522 | because no one could think of a reasonable name that wasn't already used. |
fea681da MK |
523 | .PP |
524 | The file descriptor interface is a kludge and will be deleted in a | |
525 | future version of the interface. | |
526 | .PP | |
527 | None of the access methods provide any form of concurrent access, | |
528 | locking, or transactions. | |
47297adb | 529 | .SH SEE ALSO |
e37e3282 MK |
530 | .BR btree (3), |
531 | .BR hash (3), | |
532 | .BR mpool (3), | |
533 | .BR recno (3) | |
847e0d88 | 534 | .PP |
e37e3282 MK |
535 | .IR "LIBTP: Portable, Modular Transactions for UNIX" , |
536 | Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. |