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