]>
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 | .\" | |
c13182ef | 34 | .TH DBOPEN 3 1994-01-02 |
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) |
fea681da MK |
76 | routine, however, only the O_CREAT, O_EXCL, O_EXLOCK, O_NONBLOCK, |
77 | O_RDONLY, O_RDWR, O_SHLOCK and O_TRUNC flags are meaningful. | |
78 | (Note, opening a database file O_WRONLY is not possible.) | |
79 | .\"Three additional options may be specified by | |
80 | .\".IR or 'ing | |
81 | .\"them into the | |
82 | .\".I flags | |
83 | .\"argument. | |
84 | .\".TP | |
85 | .\"DB_LOCK | |
86 | .\"Do the necessary locking in the database to support concurrent access. | |
87 | .\"If concurrent access isn't needed or the database is read-only this | |
88 | .\"flag should not be set, as it tends to have an associated performance | |
89 | .\"penalty. | |
90 | .\".TP | |
91 | .\"DB_SHMEM | |
92 | .\"Place the underlying memory pool used by the database in shared | |
93 | .\"memory. | |
94 | .\"Necessary for concurrent access. | |
95 | .\".TP | |
96 | .\"DB_TXN | |
97 | .\"Support transactions in the database. | |
98 | .\"The DB_LOCK and DB_SHMEM flags must be set as well. | |
99 | .PP | |
100 | The | |
101 | .I type | |
102 | argument is of type DBTYPE (as defined in the <db.h> include file) and | |
103 | may be set to DB_BTREE, DB_HASH or DB_RECNO. | |
104 | .PP | |
105 | The | |
106 | .I openinfo | |
107 | argument is a pointer to an access method specific structure described | |
108 | in the access method's manual page. | |
109 | If | |
110 | .I openinfo | |
111 | is NULL, each access method will use defaults appropriate for the system | |
112 | and the access method. | |
113 | .PP | |
8a9648b9 | 114 | .BR dbopen () |
fea681da MK |
115 | returns a pointer to a DB structure on success and NULL on error. |
116 | The DB structure is defined in the <db.h> include file, and contains at | |
117 | least the following fields: | |
118 | .sp | |
119 | .nf | |
120 | typedef struct { | |
b9f02710 MK |
121 | DBTYPE type; |
122 | int (*close)(const DB *db); | |
123 | int (*del)(const DB *db, const DBT *key, u_int flags); | |
124 | int (*fd)(const DB *db); | |
125 | int (*get)(const DB *db, DBT *key, DBT *data, u_int flags); | |
126 | int (*put)(const DB *db, DBT *key, const DBT *data, | |
127 | u_int flags); | |
128 | int (*sync)(const DB *db, u_int flags); | |
129 | int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags); | |
fea681da MK |
130 | } DB; |
131 | .fi | |
132 | .PP | |
133 | These elements describe a database type and a set of functions performing | |
134 | various actions. | |
135 | These functions take a pointer to a structure as returned by | |
8a9648b9 | 136 | .BR dbopen (), |
fea681da MK |
137 | and sometimes one or more pointers to key/data structures and a flag value. |
138 | .TP | |
139 | type | |
140 | The type of the underlying access method (and file format). | |
141 | .TP | |
142 | close | |
143 | A pointer to a routine to flush any cached information to disk, free any | |
144 | allocated resources, and close the underlying file(s). | |
145 | Since key/data pairs may be cached in memory, failing to sync the file | |
146 | with a | |
147 | .I close | |
148 | or | |
149 | .I sync | |
150 | function may result in inconsistent or lost information. | |
151 | .I Close | |
152 | routines return \-1 on error (setting | |
153 | .IR errno ) | |
154 | and 0 on success. | |
155 | .TP | |
156 | del | |
157 | A pointer to a routine to remove key/data pairs from the database. | |
158 | .IP | |
159 | The parameter | |
160 | .I flag | |
161 | may be set to the following value: | |
162 | .RS | |
163 | .TP | |
164 | R_CURSOR | |
165 | Delete the record referenced by the cursor. | |
166 | The cursor must have previously been initialized. | |
167 | .RE | |
168 | .IP | |
169 | .I Delete | |
170 | routines return \-1 on error (setting | |
171 | .IR errno ), | |
172 | 0 on success, and 1 if the specified | |
173 | .I key | |
174 | was not in the file. | |
175 | .TP | |
176 | fd | |
177 | A pointer to a routine which returns a file descriptor representative | |
178 | of the underlying database. | |
179 | A file descriptor referencing the same file will be returned to all | |
180 | processes which call | |
8a9648b9 | 181 | .BR dbopen () |
fea681da MK |
182 | with the same |
183 | .I file | |
184 | name. | |
185 | This file descriptor may be safely used as an argument to the | |
31e9a9ec | 186 | .BR fcntl (2) |
fea681da | 187 | and |
31e9a9ec | 188 | .BR flock (2) |
fea681da MK |
189 | locking functions. |
190 | The file descriptor is not necessarily associated with any of the | |
191 | underlying files used by the access method. | |
192 | No file descriptor is available for in memory databases. | |
193 | .I Fd | |
194 | routines return \-1 on error (setting | |
195 | .IR errno ), | |
196 | and the file descriptor on success. | |
197 | .TP | |
198 | get | |
199 | A pointer to a routine which is the interface for keyed retrieval from | |
200 | the database. | |
201 | The address and length of the data associated with the specified | |
202 | .I key | |
203 | are returned in the structure referenced by | |
204 | .IR data . | |
205 | .I Get | |
206 | routines return \-1 on error (setting | |
207 | .IR errno ), | |
208 | 0 on success, and 1 if the | |
209 | .I key | |
210 | was not in the file. | |
211 | .TP | |
212 | put | |
213 | A pointer to a routine to store key/data pairs in the database. | |
214 | .IP | |
215 | The parameter | |
216 | .I flag | |
217 | may be set to one of the following values: | |
218 | .RS | |
219 | .TP | |
220 | R_CURSOR | |
221 | Replace the key/data pair referenced by the cursor. | |
222 | The cursor must have previously been initialized. | |
223 | .TP | |
224 | R_IAFTER | |
225 | Append the data immediately after the data referenced by | |
226 | .IR key , | |
227 | creating a new key/data pair. | |
228 | The record number of the appended key/data pair is returned in the | |
229 | .I key | |
230 | structure. | |
231 | (Applicable only to the DB_RECNO access method.) | |
232 | .TP | |
233 | R_IBEFORE | |
234 | Insert the data immediately before the data referenced by | |
235 | .IR key , | |
236 | creating a new key/data pair. | |
237 | The record number of the inserted key/data pair is returned in the | |
238 | .I key | |
239 | structure. | |
240 | (Applicable only to the DB_RECNO access method.) | |
241 | .TP | |
242 | R_NOOVERWRITE | |
243 | Enter the new key/data pair only if the key does not previously exist. | |
244 | .TP | |
245 | R_SETCURSOR | |
246 | Store the key/data pair, setting or initializing the position of the | |
247 | cursor to reference it. | |
248 | (Applicable only to the DB_BTREE and DB_RECNO access methods.) | |
249 | .RE | |
250 | .IP | |
251 | R_SETCURSOR is available only for the DB_BTREE and DB_RECNO access | |
252 | methods because it implies that the keys have an inherent order | |
253 | which does not change. | |
254 | .IP | |
255 | R_IAFTER and R_IBEFORE are available only for the DB_RECNO | |
256 | access method because they each imply that the access method is able to | |
257 | create new keys. | |
258 | This is only true if the keys are ordered and independent, record numbers | |
259 | for example. | |
260 | .IP | |
261 | The default behavior of the | |
262 | .I put | |
263 | routines is to enter the new key/data pair, replacing any previously | |
264 | existing key. | |
265 | .IP | |
266 | .I Put | |
267 | routines return \-1 on error (setting | |
268 | .IR errno ), | |
269 | 0 on success, and 1 if the R_NOOVERWRITE | |
270 | .I flag | |
271 | was set and the key already exists in the file. | |
272 | .TP | |
273 | seq | |
274 | A pointer to a routine which is the interface for sequential | |
275 | retrieval from the database. | |
276 | The address and length of the key are returned in the structure | |
277 | referenced by | |
278 | .IR key , | |
279 | and the address and length of the data are returned in the | |
280 | structure referenced | |
281 | by | |
282 | .IR data . | |
283 | .IP | |
284 | Sequential key/data pair retrieval may begin at any time, and the | |
285 | position of the ``cursor'' is not affected by calls to the | |
286 | .IR del , | |
287 | .IR get , | |
288 | .IR put , | |
289 | or | |
290 | .I sync | |
291 | routines. | |
292 | Modifications to the database during a sequential scan will be reflected | |
293 | in the scan, i.e. records inserted behind the cursor will not be returned | |
294 | while records inserted in front of the cursor will be returned. | |
295 | .IP | |
296 | The flag value | |
297 | .B must | |
298 | be set to one of the following values: | |
299 | .RS | |
300 | .TP | |
301 | R_CURSOR | |
302 | The data associated with the specified key is returned. | |
303 | This differs from the | |
304 | .I get | |
305 | routines in that it sets or initializes the cursor to the location of | |
306 | the key as well. | |
307 | (Note, for the DB_BTREE access method, the returned key is not necessarily an | |
308 | exact match for the specified key. | |
309 | The returned key is the smallest key greater than or equal to the specified | |
310 | key, permitting partial key matches and range searches.) | |
311 | .TP | |
312 | R_FIRST | |
313 | The first key/data pair of the database is returned, and the cursor | |
314 | is set or initialized to reference it. | |
315 | .TP | |
316 | R_LAST | |
317 | The last key/data pair of the database is returned, and the cursor | |
318 | is set or initialized to reference it. | |
319 | (Applicable only to the DB_BTREE and DB_RECNO access methods.) | |
320 | .TP | |
321 | R_NEXT | |
322 | Retrieve the key/data pair immediately after the cursor. | |
323 | If the cursor is not yet set, this is the same as the R_FIRST flag. | |
324 | .TP | |
325 | R_PREV | |
326 | Retrieve the key/data pair immediately before the cursor. | |
327 | If the cursor is not yet set, this is the same as the R_LAST flag. | |
328 | (Applicable only to the DB_BTREE and DB_RECNO access methods.) | |
329 | .RE | |
330 | .IP | |
331 | R_LAST and R_PREV are available only for the DB_BTREE and DB_RECNO | |
332 | access methods because they each imply that the keys have an inherent | |
333 | order which does not change. | |
334 | .IP | |
335 | .I Seq | |
336 | routines return \-1 on error (setting | |
337 | .IR errno ), | |
338 | 0 on success and 1 if there are no key/data pairs less than or greater | |
339 | than the specified or current key. | |
340 | If the DB_RECNO access method is being used, and if the database file | |
341 | is a character special file and no complete key/data pairs are currently | |
342 | available, the | |
343 | .I seq | |
344 | routines return 2. | |
345 | .TP | |
346 | sync | |
347 | A pointer to a routine to flush any cached information to disk. | |
348 | If the database is in memory only, the | |
349 | .I sync | |
350 | routine has no effect and will always succeed. | |
351 | .IP | |
352 | The flag value may be set to the following value: | |
353 | .RS | |
354 | .TP | |
355 | R_RECNOSYNC | |
356 | If the DB_RECNO access method is being used, this flag causes | |
357 | the sync routine to apply to the btree file which underlies the | |
358 | recno file, not the recno file itself. | |
359 | (See the | |
360 | .I bfname | |
361 | field of the | |
31e9a9ec | 362 | .BR recno (3) |
fea681da MK |
363 | manual page for more information.) |
364 | .RE | |
365 | .IP | |
366 | .I Sync | |
367 | routines return \-1 on error (setting | |
368 | .IR errno ) | |
369 | and 0 on success. | |
8af1ba10 | 370 | .SS "Key/Data Pairs" |
fea681da MK |
371 | Access to all file types is based on key/data pairs. |
372 | Both keys and data are represented by the following data structure: | |
373 | .PP | |
374 | typedef struct { | |
375 | .RS | |
376 | void *data; | |
377 | .br | |
378 | size_t size; | |
379 | .RE | |
380 | } DBT; | |
381 | .PP | |
382 | The elements of the DBT structure are defined as follows: | |
383 | .TP | |
384 | data | |
385 | A pointer to a byte string. | |
386 | .TP | |
387 | size | |
388 | The length of the byte string. | |
389 | .PP | |
390 | Key and data byte strings may reference strings of essentially unlimited | |
391 | length although any two of them must fit into available memory at the same | |
392 | time. | |
393 | It should be noted that the access methods provide no guarantees about | |
394 | byte string alignment. | |
395 | .SH ERRORS | |
396 | The | |
8a9648b9 | 397 | .BR dbopen () |
fea681da MK |
398 | routine may fail and set |
399 | .I errno | |
400 | for any of the errors specified for the library routines | |
31e9a9ec | 401 | .BR open (2) |
fea681da | 402 | and |
31e9a9ec | 403 | .BR malloc (3) |
fea681da MK |
404 | or the following: |
405 | .TP | |
406 | [EFTYPE] | |
407 | A file is incorrectly formatted. | |
408 | .TP | |
409 | [EINVAL] | |
410 | A parameter has been specified (hash function, pad byte etc.) that is | |
411 | incompatible with the current file specification or which is not | |
412 | meaningful for the function (for example, use of the cursor without | |
413 | prior initialization) or there is a mismatch between the version | |
414 | number of file and the software. | |
415 | .PP | |
416 | The | |
417 | .I close | |
418 | routines may fail and set | |
419 | .I errno | |
420 | for any of the errors specified for the library routines | |
31e9a9ec MK |
421 | .BR close (2), |
422 | .BR read (2), | |
423 | .BR write (2), | |
424 | .BR free (3), | |
fea681da | 425 | or |
31e9a9ec | 426 | .BR fsync (2). |
fea681da MK |
427 | .PP |
428 | The | |
429 | .IR del , | |
430 | .IR get , | |
431 | .I put | |
432 | and | |
433 | .I seq | |
434 | routines may fail and set | |
435 | .I errno | |
436 | for any of the errors specified for the library routines | |
31e9a9ec MK |
437 | .BR read (2), |
438 | .BR write (2), | |
439 | .BR free (3) | |
fea681da | 440 | or |
31e9a9ec | 441 | .BR malloc (3). |
fea681da MK |
442 | .PP |
443 | The | |
444 | .I fd | |
445 | routines will fail and set | |
446 | .I errno | |
447 | to ENOENT for in memory databases. | |
448 | .PP | |
449 | The | |
450 | .I sync | |
451 | routines may fail and set | |
452 | .I errno | |
453 | for any of the errors specified for the library routine | |
31e9a9ec | 454 | .BR fsync (2). |
fea681da | 455 | .SH "SEE ALSO" |
31e9a9ec MK |
456 | .BR btree (3), |
457 | .BR hash (3), | |
458 | .BR mpool (3), | |
459 | .BR recno (3) | |
fea681da MK |
460 | .sp |
461 | .IR "LIBTP: Portable, Modular Transactions for UNIX" , | |
462 | Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. | |
463 | .SH BUGS | |
464 | The typedef DBT is a mnemonic for ``data base thang'', and was used | |
3f1c1b0a | 465 | because no-one could think of a reasonable name that wasn't already used. |
fea681da MK |
466 | .PP |
467 | The file descriptor interface is a kludge and will be deleted in a | |
468 | future version of the interface. | |
469 | .PP | |
470 | None of the access methods provide any form of concurrent access, | |
471 | locking, or transactions. |