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