]>
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 () |
fea681da | 134 | returns a pointer to a DB structure on success and NULL on error. |
a9a13a50 MK |
135 | The DB structure is defined in the |
136 | .I <db.h> | |
137 | include file, and contains at | |
fea681da MK |
138 | least the following fields: |
139 | .sp | |
628d8d62 | 140 | .in +0.5i |
fea681da MK |
141 | .nf |
142 | typedef struct { | |
b9f02710 MK |
143 | DBTYPE type; |
144 | int (*close)(const DB *db); | |
145 | int (*del)(const DB *db, const DBT *key, u_int flags); | |
146 | int (*fd)(const DB *db); | |
147 | int (*get)(const DB *db, DBT *key, DBT *data, u_int flags); | |
148 | int (*put)(const DB *db, DBT *key, const DBT *data, | |
149 | u_int flags); | |
150 | int (*sync)(const DB *db, u_int flags); | |
151 | int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags); | |
fea681da MK |
152 | } DB; |
153 | .fi | |
628d8d62 | 154 | .in |
fea681da MK |
155 | .PP |
156 | These elements describe a database type and a set of functions performing | |
157 | various actions. | |
158 | These functions take a pointer to a structure as returned by | |
8a9648b9 | 159 | .BR dbopen (), |
fea681da MK |
160 | and sometimes one or more pointers to key/data structures and a flag value. |
161 | .TP | |
162 | type | |
163 | The type of the underlying access method (and file format). | |
164 | .TP | |
165 | close | |
166 | A pointer to a routine to flush any cached information to disk, free any | |
167 | allocated resources, and close the underlying file(s). | |
168 | Since key/data pairs may be cached in memory, failing to sync the file | |
169 | with a | |
170 | .I close | |
171 | or | |
172 | .I sync | |
173 | function may result in inconsistent or lost information. | |
174 | .I Close | |
175 | routines return \-1 on error (setting | |
176 | .IR errno ) | |
177 | and 0 on success. | |
178 | .TP | |
179 | del | |
180 | A pointer to a routine to remove key/data pairs from the database. | |
181 | .IP | |
182 | The parameter | |
183 | .I flag | |
184 | may be set to the following value: | |
185 | .RS | |
186 | .TP | |
628d8d62 | 187 | .B R_CURSOR |
fea681da MK |
188 | Delete the record referenced by the cursor. |
189 | The cursor must have previously been initialized. | |
190 | .RE | |
191 | .IP | |
192 | .I Delete | |
193 | routines return \-1 on error (setting | |
194 | .IR errno ), | |
195 | 0 on success, and 1 if the specified | |
196 | .I key | |
197 | was not in the file. | |
198 | .TP | |
199 | fd | |
200 | A pointer to a routine which returns a file descriptor representative | |
201 | of the underlying database. | |
202 | A file descriptor referencing the same file will be returned to all | |
203 | processes which call | |
8a9648b9 | 204 | .BR dbopen () |
fea681da MK |
205 | with the same |
206 | .I file | |
207 | name. | |
208 | This file descriptor may be safely used as an argument to the | |
31e9a9ec | 209 | .BR fcntl (2) |
fea681da | 210 | and |
31e9a9ec | 211 | .BR flock (2) |
fea681da MK |
212 | locking functions. |
213 | The file descriptor is not necessarily associated with any of the | |
214 | underlying files used by the access method. | |
215 | No file descriptor is available for in memory databases. | |
216 | .I Fd | |
217 | routines return \-1 on error (setting | |
218 | .IR errno ), | |
219 | and the file descriptor on success. | |
220 | .TP | |
221 | get | |
222 | A pointer to a routine which is the interface for keyed retrieval from | |
223 | the database. | |
224 | The address and length of the data associated with the specified | |
225 | .I key | |
226 | are returned in the structure referenced by | |
227 | .IR data . | |
228 | .I Get | |
229 | routines return \-1 on error (setting | |
230 | .IR errno ), | |
231 | 0 on success, and 1 if the | |
232 | .I key | |
233 | was not in the file. | |
234 | .TP | |
235 | put | |
236 | A pointer to a routine to store key/data pairs in the database. | |
237 | .IP | |
238 | The parameter | |
239 | .I flag | |
240 | may be set to one of the following values: | |
241 | .RS | |
242 | .TP | |
628d8d62 | 243 | .B R_CURSOR |
fea681da MK |
244 | Replace the key/data pair referenced by the cursor. |
245 | The cursor must have previously been initialized. | |
246 | .TP | |
628d8d62 | 247 | .B R_IAFTER |
fea681da MK |
248 | Append the data immediately after the data referenced by |
249 | .IR key , | |
250 | creating a new key/data pair. | |
251 | The record number of the appended key/data pair is returned in the | |
252 | .I key | |
253 | structure. | |
628d8d62 MK |
254 | (Applicable only to the |
255 | .B DB_RECNO | |
256 | access method.) | |
fea681da | 257 | .TP |
628d8d62 | 258 | .B R_IBEFORE |
fea681da MK |
259 | Insert the data immediately before the data referenced by |
260 | .IR key , | |
261 | creating a new key/data pair. | |
262 | The record number of the inserted key/data pair is returned in the | |
263 | .I key | |
264 | structure. | |
628d8d62 MK |
265 | (Applicable only to the |
266 | .B DB_RECNO | |
267 | access method.) | |
fea681da | 268 | .TP |
628d8d62 | 269 | .B R_NOOVERWRITE |
fea681da MK |
270 | Enter the new key/data pair only if the key does not previously exist. |
271 | .TP | |
628d8d62 | 272 | .B R_SETCURSOR |
fea681da MK |
273 | Store the key/data pair, setting or initializing the position of the |
274 | cursor to reference it. | |
628d8d62 MK |
275 | (Applicable only to the |
276 | .B DB_BTREE | |
277 | and | |
278 | .B DB_RECNO | |
279 | access methods.) | |
fea681da MK |
280 | .RE |
281 | .IP | |
628d8d62 MK |
282 | .B R_SETCURSOR |
283 | is available only for the | |
284 | .B DB_BTREE | |
285 | and | |
286 | .B DB_RECNO | |
287 | access | |
fea681da MK |
288 | methods because it implies that the keys have an inherent order |
289 | which does not change. | |
290 | .IP | |
628d8d62 MK |
291 | .B R_IAFTER |
292 | and | |
293 | .B R_IBEFORE | |
294 | are available only for the | |
295 | .B DB_RECNO | |
fea681da MK |
296 | access method because they each imply that the access method is able to |
297 | create new keys. | |
298 | This is only true if the keys are ordered and independent, record numbers | |
299 | for example. | |
300 | .IP | |
301 | The default behavior of the | |
302 | .I put | |
303 | routines is to enter the new key/data pair, replacing any previously | |
304 | existing key. | |
305 | .IP | |
306 | .I Put | |
307 | routines return \-1 on error (setting | |
308 | .IR errno ), | |
628d8d62 MK |
309 | 0 on success, and 1 if the |
310 | .B R_NOOVERWRITE | |
fea681da MK |
311 | .I flag |
312 | was set and the key already exists in the file. | |
313 | .TP | |
314 | seq | |
315 | A pointer to a routine which is the interface for sequential | |
316 | retrieval from the database. | |
317 | The address and length of the key are returned in the structure | |
318 | referenced by | |
319 | .IR key , | |
320 | and the address and length of the data are returned in the | |
321 | structure referenced | |
322 | by | |
323 | .IR data . | |
324 | .IP | |
325 | Sequential key/data pair retrieval may begin at any time, and the | |
326 | position of the ``cursor'' is not affected by calls to the | |
327 | .IR del , | |
328 | .IR get , | |
329 | .IR put , | |
330 | or | |
331 | .I sync | |
332 | routines. | |
333 | Modifications to the database during a sequential scan will be reflected | |
988db661 | 334 | in the scan, that is, |
75b94dc3 | 335 | records inserted behind the cursor will not be returned |
fea681da MK |
336 | while records inserted in front of the cursor will be returned. |
337 | .IP | |
338 | The flag value | |
339 | .B must | |
340 | be set to one of the following values: | |
341 | .RS | |
342 | .TP | |
628d8d62 | 343 | .B R_CURSOR |
fea681da MK |
344 | The data associated with the specified key is returned. |
345 | This differs from the | |
346 | .I get | |
347 | routines in that it sets or initializes the cursor to the location of | |
348 | the key as well. | |
628d8d62 MK |
349 | (Note, for the |
350 | .B DB_BTREE | |
351 | access method, the returned key is not necessarily an | |
fea681da MK |
352 | exact match for the specified key. |
353 | The returned key is the smallest key greater than or equal to the specified | |
354 | key, permitting partial key matches and range searches.) | |
355 | .TP | |
628d8d62 | 356 | .B R_FIRST |
fea681da MK |
357 | The first key/data pair of the database is returned, and the cursor |
358 | is set or initialized to reference it. | |
359 | .TP | |
628d8d62 | 360 | .B R_LAST |
fea681da MK |
361 | The last key/data pair of the database is returned, and the cursor |
362 | is set or initialized to reference it. | |
628d8d62 MK |
363 | (Applicable only to the |
364 | .B DB_BTREE | |
365 | and | |
366 | .B DB_RECNO | |
367 | access methods.) | |
fea681da | 368 | .TP |
628d8d62 | 369 | .B R_NEXT |
fea681da | 370 | Retrieve the key/data pair immediately after the cursor. |
628d8d62 MK |
371 | If the cursor is not yet set, this is the same as the |
372 | .B R_FIRST | |
373 | flag. | |
fea681da | 374 | .TP |
628d8d62 | 375 | .B R_PREV |
fea681da | 376 | Retrieve the key/data pair immediately before the cursor. |
628d8d62 MK |
377 | If the cursor is not yet set, this is the same as the |
378 | .B R_LAST | |
379 | flag. | |
380 | (Applicable only to the | |
381 | .B DB_BTREE | |
382 | and | |
383 | .B DB_RECNO | |
384 | access methods.) | |
fea681da MK |
385 | .RE |
386 | .IP | |
628d8d62 MK |
387 | .B R_LAST |
388 | and | |
389 | .B R_PREV | |
390 | are available only for the | |
391 | .B DB_BTREE | |
392 | and | |
393 | .B DB_RECNO | |
fea681da MK |
394 | access methods because they each imply that the keys have an inherent |
395 | order which does not change. | |
396 | .IP | |
397 | .I Seq | |
398 | routines return \-1 on error (setting | |
399 | .IR errno ), | |
400 | 0 on success and 1 if there are no key/data pairs less than or greater | |
401 | than the specified or current key. | |
628d8d62 MK |
402 | If the |
403 | .B DB_RECNO | |
404 | access method is being used, and if the database file | |
fea681da MK |
405 | is a character special file and no complete key/data pairs are currently |
406 | available, the | |
407 | .I seq | |
408 | routines return 2. | |
409 | .TP | |
410 | sync | |
411 | A pointer to a routine to flush any cached information to disk. | |
412 | If the database is in memory only, the | |
413 | .I sync | |
414 | routine has no effect and will always succeed. | |
415 | .IP | |
416 | The flag value may be set to the following value: | |
417 | .RS | |
418 | .TP | |
628d8d62 MK |
419 | .B R_RECNOSYNC |
420 | If the | |
421 | .B DB_RECNO | |
422 | access method is being used, this flag causes | |
fea681da MK |
423 | the sync routine to apply to the btree file which underlies the |
424 | recno file, not the recno file itself. | |
425 | (See the | |
426 | .I bfname | |
427 | field of the | |
31e9a9ec | 428 | .BR recno (3) |
fea681da MK |
429 | manual page for more information.) |
430 | .RE | |
431 | .IP | |
432 | .I Sync | |
433 | routines return \-1 on error (setting | |
434 | .IR errno ) | |
435 | and 0 on success. | |
8af1ba10 | 436 | .SS "Key/Data Pairs" |
fea681da MK |
437 | Access to all file types is based on key/data pairs. |
438 | Both keys and data are represented by the following data structure: | |
628d8d62 MK |
439 | .in +0.5i |
440 | .nf | |
441 | ||
fea681da | 442 | typedef struct { |
628d8d62 MK |
443 | void *data; |
444 | size_t size; | |
fea681da | 445 | } DBT; |
628d8d62 MK |
446 | .fi |
447 | .in | |
fea681da | 448 | .PP |
628d8d62 MK |
449 | The elements of the |
450 | .I DBT | |
451 | structure are defined as follows: | |
fea681da MK |
452 | .TP |
453 | data | |
454 | A pointer to a byte string. | |
455 | .TP | |
456 | size | |
457 | The length of the byte string. | |
458 | .PP | |
459 | Key and data byte strings may reference strings of essentially unlimited | |
460 | length although any two of them must fit into available memory at the same | |
461 | time. | |
462 | It should be noted that the access methods provide no guarantees about | |
463 | byte string alignment. | |
464 | .SH ERRORS | |
465 | The | |
8a9648b9 | 466 | .BR dbopen () |
fea681da MK |
467 | routine may fail and set |
468 | .I errno | |
469 | for any of the errors specified for the library routines | |
31e9a9ec | 470 | .BR open (2) |
fea681da | 471 | and |
31e9a9ec | 472 | .BR malloc (3) |
fea681da MK |
473 | or the following: |
474 | .TP | |
747944fe | 475 | .B EFTYPE |
fea681da MK |
476 | A file is incorrectly formatted. |
477 | .TP | |
747944fe | 478 | .B EINVAL |
fea681da MK |
479 | A parameter has been specified (hash function, pad byte etc.) that is |
480 | incompatible with the current file specification or which is not | |
481 | meaningful for the function (for example, use of the cursor without | |
482 | prior initialization) or there is a mismatch between the version | |
483 | number of file and the software. | |
484 | .PP | |
485 | The | |
486 | .I close | |
487 | routines may fail and set | |
488 | .I errno | |
489 | for any of the errors specified for the library routines | |
31e9a9ec MK |
490 | .BR close (2), |
491 | .BR read (2), | |
492 | .BR write (2), | |
493 | .BR free (3), | |
fea681da | 494 | or |
31e9a9ec | 495 | .BR fsync (2). |
fea681da MK |
496 | .PP |
497 | The | |
498 | .IR del , | |
499 | .IR get , | |
500 | .I put | |
501 | and | |
502 | .I seq | |
503 | routines may fail and set | |
504 | .I errno | |
505 | for any of the errors specified for the library routines | |
31e9a9ec MK |
506 | .BR read (2), |
507 | .BR write (2), | |
508 | .BR free (3) | |
fea681da | 509 | or |
31e9a9ec | 510 | .BR malloc (3). |
fea681da MK |
511 | .PP |
512 | The | |
513 | .I fd | |
514 | routines will fail and set | |
515 | .I errno | |
628d8d62 MK |
516 | to |
517 | .B ENOENT | |
518 | for in memory databases. | |
fea681da MK |
519 | .PP |
520 | The | |
521 | .I sync | |
522 | routines may fail and set | |
523 | .I errno | |
524 | for any of the errors specified for the library routine | |
31e9a9ec | 525 | .BR fsync (2). |
fea681da | 526 | .SH BUGS |
628d8d62 MK |
527 | The typedef |
528 | .I DBT | |
529 | is a mnemonic for ``data base thang'', and was used | |
3f1c1b0a | 530 | because no-one could think of a reasonable name that wasn't already used. |
fea681da MK |
531 | .PP |
532 | The file descriptor interface is a kludge and will be deleted in a | |
533 | future version of the interface. | |
534 | .PP | |
535 | None of the access methods provide any form of concurrent access, | |
536 | locking, or transactions. | |
e37e3282 MK |
537 | .SH "SEE ALSO" |
538 | .BR btree (3), | |
539 | .BR hash (3), | |
540 | .BR mpool (3), | |
541 | .BR recno (3) | |
542 | .sp | |
543 | .IR "LIBTP: Portable, Modular Transactions for UNIX" , | |
544 | Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. |