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