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