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