Debian Codegraph @

upstream/debian-unstable/man3/dbopen.3

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