Commit | Line | Data |
---|---|---|
bcd70bc9 KB |
1 | .\" Copyright (c) 1990 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" %sccs.include.redist.man% | |
5 | .\" | |
4e3894e7 | 6 | .\" @(#)dbopen.3 5.20 (Berkeley) %G% |
bcd70bc9 | 7 | .\" |
4e3894e7 | 8 | .TH DBOPEN 3 "" |
bcd70bc9 KB |
9 | .UC 7 |
10 | .SH NAME | |
f52ca292 | 11 | dbopen \- database access methods |
bcd70bc9 KB |
12 | .SH SYNOPSIS |
13 | .nf | |
14 | .ft B | |
ad422b65 | 15 | #include <sys/types.h> |
f52ca292 | 16 | #include <limits.h> |
bcd70bc9 KB |
17 | #include <db.h> |
18 | ||
19 | DB * | |
f52ca292 | 20 | dbopen(const char *file, int flags, int mode, DBTYPE type, |
16d71a3a | 21 | .ti +5 |
f52ca292 | 22 | const void *openinfo); |
bcd70bc9 KB |
23 | .ft R |
24 | .fi | |
25 | .SH DESCRIPTION | |
f52ca292 KB |
26 | .IR Dbopen |
27 | is the library interface to database files. | |
28 | The supported file formats are btree, hashed and record oriented. | |
8e982eee KB |
29 | The btree format is a representation of a sorted, balanced tree structure. |
30 | The hashed format is an extensible, dynamic hashing scheme. | |
f52ca292 KB |
31 | The flat-file format is a byte stream file with fixed or variable length |
32 | records. | |
33 | The formats and file format specific information are described in detail | |
34 | in their respective manual pages | |
35 | .IR btree (3), | |
36 | .IR hash (3) | |
37 | and | |
38 | .IR recno (3). | |
bcd70bc9 | 39 | .PP |
f52ca292 | 40 | Dbopen opens |
bcd70bc9 KB |
41 | .I file |
42 | for reading and/or writing. | |
f52ca292 | 43 | Files never intended to be preserved on disk may be created by setting |
ad422b65 | 44 | the file parameter to NULL. |
f52ca292 | 45 | .PP |
bcd70bc9 KB |
46 | The |
47 | .I flags | |
48 | and | |
49 | .I mode arguments | |
50 | are as specified to the | |
51 | .IR open (2) | |
ad422b65 | 52 | routine, however, only the O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_TRUNC |
bcd70bc9 | 53 | and O_WRONLY flags are meaningful. |
f52ca292 KB |
54 | .PP |
55 | The | |
56 | .I type | |
57 | argument is of type DBTYPE (as defined in the <db.h> include file) and | |
58 | may be set to DB_BTREE, DB_HASH or DB_RECNO. | |
59 | .PP | |
60 | The | |
8e982eee | 61 | .I openinfo |
f52ca292 KB |
62 | argument is a pointer to an access method specific structure described |
63 | in the access method's manual page. | |
64 | If | |
65 | .I openinfo | |
66 | is NULL, each access method will use defaults appropriate for the system | |
67 | and the access method. | |
bcd70bc9 | 68 | .PP |
f52ca292 KB |
69 | .I Dbopen |
70 | returns a pointer to a DB structure on success and NULL on error. | |
71 | The DB structure is defined in the <db.h> include file, and contains at | |
72 | least the following fields: | |
16d71a3a KB |
73 | .sp |
74 | .nf | |
bcd70bc9 KB |
75 | typedef struct { |
76 | .RS | |
f52ca292 | 77 | DBTYPE type; |
8e982eee | 78 | int (*close)(const DB *db); |
96a0c789 KB |
79 | int (*del)(const DB *db, const DBT *key, u_int flags); |
80 | int (*get)(const DB *db, DBT *key, DBT *data, u_int flags); | |
16d71a3a KB |
81 | int (*put)(const DB *db, const DBT *key, const DBT *data, |
82 | .ti +5 | |
96a0c789 | 83 | u_int flags); |
f52ca292 | 84 | int (*sync)(const DB *db); |
96a0c789 | 85 | int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags); |
bcd70bc9 KB |
86 | .RE |
87 | } DB; | |
16d71a3a | 88 | .fi |
bcd70bc9 | 89 | .PP |
f52ca292 KB |
90 | These elements a database type and a set of functions performing various |
91 | actions. | |
92 | These functions take a pointer to a structure as returned by | |
93 | .IR dbopen , | |
94 | and sometimes one or more pointers to key/data structures and a flag value. | |
bcd70bc9 | 95 | .TP |
189ff9f0 | 96 | type |
f52ca292 | 97 | The type of the underlying access method (and file format). |
189ff9f0 | 98 | .TP |
bcd70bc9 KB |
99 | close |
100 | A pointer to a routine to flush any cached information to disk, free any | |
f52ca292 KB |
101 | allocated resources, and close the underlying file(s). |
102 | Since key/data pairs may be cached in memory, failing to sync the file | |
103 | with a | |
bcd70bc9 | 104 | .I close |
f52ca292 KB |
105 | or |
106 | .I sync | |
107 | function may result in inconsistent or lost information. | |
8e982eee KB |
108 | .I Close |
109 | routines return -1 on error (setting | |
110 | .IR errno ) | |
111 | and 0 on success. | |
bcd70bc9 | 112 | .TP |
16d71a3a | 113 | del |
932a5d4e | 114 | A pointer to a routine to remove key/data pairs from the database. |
f52ca292 KB |
115 | .IP |
116 | The parameter | |
117 | .I flag | |
118 | may be set to the following value: | |
119 | .RS | |
120 | .TP | |
121 | R_CURSOR | |
122 | Delete the record referenced by the cursor. | |
123 | .RE | |
124 | .IP | |
8e982eee KB |
125 | .I Delete |
126 | routines return -1 on error (setting | |
127 | .IR errno ), | |
128 | 0 on success, and 1 if the specified | |
bcd70bc9 KB |
129 | .I key |
130 | was not in the file. | |
131 | .TP | |
132 | get | |
133 | A pointer to a routine which is the interface for keyed retrieval from | |
932a5d4e | 134 | the database. |
bcd70bc9 KB |
135 | The address and length of the data associated with the specified |
136 | .I key | |
137 | are returned in the structure referenced by | |
138 | .IR data . | |
8e982eee KB |
139 | .I Get |
140 | routines return -1 on error (setting | |
141 | .IR errno ), | |
142 | 0 on success, and 1 if the | |
bcd70bc9 KB |
143 | .I key |
144 | was not in the file. | |
145 | .TP | |
146 | put | |
932a5d4e | 147 | A pointer to a routine to store key/data pairs in the database. |
ad422b65 | 148 | .IP |
44c9ff50 KB |
149 | The parameter |
150 | .I flag | |
8a7be813 | 151 | may be set to one of the following values: |
44c9ff50 | 152 | .RS |
bcd70bc9 | 153 | .TP |
8a7be813 KB |
154 | R_APPEND |
155 | Append the data to the tree, creating a new key/data pair. | |
156 | (Applicable only to the DB_RECNO access method.) | |
157 | .TP | |
158 | R_CURSOR | |
159 | Replace the key/data pair referenced by the cursor. | |
160 | .TP | |
8e982eee | 161 | R_IAFTER |
bcd70bc9 KB |
162 | Append the data immediately after the data referenced by |
163 | .IR key , | |
8e982eee | 164 | creating a new key/data pair. |
8a7be813 | 165 | (Applicable only to the DB_RECNO access method.) |
ad422b65 | 166 | .TP |
8e982eee | 167 | R_IBEFORE |
bcd70bc9 KB |
168 | Insert the data immediately before the data referenced by |
169 | .IR key , | |
8e982eee | 170 | creating a new key/data pair. |
8a7be813 | 171 | (Applicable only to the DB_RECNO access method.) |
bcd70bc9 KB |
172 | .TP |
173 | R_NOOVERWRITE | |
174 | Enter the new key/data pair only if the key does not previously exist. | |
175 | .RE | |
ad422b65 | 176 | .IP |
8a7be813 KB |
177 | R_APPEND, R_IAFTER and R_IBEFORE are available only for the DB_RECNO access |
178 | method because they each imply that the access method is able to create new | |
179 | keys. | |
180 | This is only true if the keys are ordered and independent, record numbers | |
181 | for example. | |
182 | .IP | |
f52ca292 KB |
183 | The default behavior of the |
184 | .I put | |
185 | routines is to enter the new key/data pair, replacing any previously | |
186 | existing key. | |
187 | .IP | |
8e982eee KB |
188 | .I Put |
189 | routines return -1 on error (setting | |
190 | .IR errno ), | |
191 | 0 on success, and 1 if the R_NOOVERWRITE | |
ad422b65 | 192 | .I flag |
8e982eee | 193 | was set and the key already exists in the file. |
bcd70bc9 KB |
194 | .TP |
195 | seq | |
196 | A pointer to a routine which is the interface for sequential | |
932a5d4e | 197 | retrieval from the database. |
bcd70bc9 KB |
198 | The address and length of the key are returned in the structure |
199 | referenced by | |
200 | .IR key , | |
201 | and the address and length of the data are returned in the | |
202 | structure referenced | |
203 | by | |
204 | .IR data . | |
ad422b65 | 205 | .IP |
7226de19 KB |
206 | Sequential key/data pair retrieval may begin at any time, and the |
207 | position of the ``cursor'' is not affected by calls to the | |
16d71a3a | 208 | .IR del , |
7226de19 KB |
209 | .IR get , |
210 | .IR put , | |
211 | or | |
212 | .I sync | |
213 | routines. | |
214 | Modifications to the database during a sequential scan will be reflected | |
215 | in the scan, i.e. records inserted behind the cursor will not be returned | |
216 | while records inserted in front of the cursor will be returned. | |
217 | .IP | |
8a7be813 KB |
218 | The flag value |
219 | .B must | |
220 | be set to one of the following values: | |
bcd70bc9 KB |
221 | .RS |
222 | .TP | |
ad422b65 | 223 | R_CURSOR |
8e982eee KB |
224 | The data associated with the specified key is returned. |
225 | This differs from the | |
226 | .I get | |
227 | routines in that it sets the ``cursor'' to the location of the | |
228 | key as well. | |
8a7be813 KB |
229 | (Note, for the DB_BTREE access method, the returned key is not necessarily an |
230 | exact match for the specified key. | |
231 | The returned key is the smallest key greater than or equal to the specified | |
232 | key, permitting partial key matches and range searches.) | |
ad422b65 | 233 | .TP |
bcd70bc9 | 234 | R_FIRST |
8e982eee | 235 | The first key/data pair of the database is returned. |
bcd70bc9 KB |
236 | .TP |
237 | R_LAST | |
8e982eee | 238 | The last key/data pair of the database is returned. |
8a7be813 | 239 | (Applicable only to the DB_BTREE and DB_RECNO access methods.) |
bcd70bc9 KB |
240 | .TP |
241 | R_NEXT | |
8e982eee KB |
242 | Retrieve the key/data pair immediately after the key/data pair most recently |
243 | retrieved using the | |
244 | .I seq | |
245 | routine. | |
246 | The cursor is moved to the returned key/data pair. | |
247 | If | |
248 | .I flag | |
249 | is set to R_NEXT the first time the | |
250 | .I seq | |
251 | routine is called, the first key/data pair of the database is returned. | |
bcd70bc9 KB |
252 | .TP |
253 | R_PREV | |
8e982eee KB |
254 | Retrieve the key/data pair immediately before the key/data pair most recently |
255 | retrieved using the | |
256 | .I seq | |
257 | routine. | |
258 | The cursor is moved to the returned key/data pair. | |
7226de19 KB |
259 | If |
260 | .I flag | |
261 | is set to R_PREV the first time the | |
262 | .I seq | |
263 | routine is called, the last key/data pair of the database is returned. | |
8a7be813 | 264 | (Applicable only to the DB_BTREE and DB_RECNO access methods.) |
bcd70bc9 | 265 | .RE |
ad422b65 | 266 | .IP |
8a7be813 KB |
267 | R_LAST and R_PREV are available only for the DB_BTREE and DB_RECNO |
268 | access methods because they each imply that the keys have an inherent order | |
269 | which does not change. | |
270 | .IP | |
8e982eee KB |
271 | .I Seq |
272 | routines return -1 on error (setting | |
273 | .IR errno ), | |
8a7be813 KB |
274 | 0 on success and 1 if there are no key/data pairs less than or greater |
275 | than the specified or current key. | |
f52ca292 KB |
276 | If the DB_RECNO access method is being used, and if the database file |
277 | is a character special file and no complete key/data pairs are currently | |
278 | available, the | |
7226de19 KB |
279 | .I seq |
280 | routines return 2. | |
bcd70bc9 KB |
281 | .TP |
282 | sync | |
932a5d4e | 283 | A pointer to a routine to flush any cached information to disk. |
bcd70bc9 KB |
284 | If the database is in memory only, the |
285 | .I sync | |
8e982eee KB |
286 | routine has no effect and will always succeed. |
287 | .I Sync | |
288 | routines return -1 on error (setting | |
289 | .IR errno ) | |
290 | and 0 on success. | |
ad422b65 | 291 | .SH "KEY/DATA PAIRS" |
8e982eee | 292 | Access to all file types is based on key/data pairs. |
ad422b65 | 293 | Both keys and data are represented by the following data structure: |
bcd70bc9 | 294 | .PP |
bcd70bc9 KB |
295 | typedef struct { |
296 | .RS | |
189ff9f0 | 297 | void *data; |
bcd70bc9 KB |
298 | .br |
299 | size_t size; | |
300 | .RE | |
932a5d4e | 301 | } DBT; |
bcd70bc9 | 302 | .PP |
ad422b65 | 303 | The elements of the DBT structure are defined as follows: |
bcd70bc9 KB |
304 | .TP |
305 | data | |
306 | A pointer to a byte string. | |
307 | .TP | |
308 | size | |
309 | The length of the byte string. | |
ad422b65 | 310 | .PP |
f52ca292 KB |
311 | Key and data byte strings may reference strings of essentially unlimited |
312 | length although any two of them must fit into available memory at the same | |
313 | time. | |
314 | It should be noted that the access methods provide no guarantees about | |
315 | byte string alignment. | |
bcd70bc9 KB |
316 | .SH ERRORS |
317 | The | |
f52ca292 KB |
318 | .I dbopen |
319 | routine may fail and set | |
8e982eee KB |
320 | .I errno |
321 | for any of the errors specified for the library routines | |
bcd70bc9 KB |
322 | .IR open (2) |
323 | and | |
324 | .IR malloc (3) | |
325 | or the following: | |
326 | .TP | |
189ff9f0 | 327 | [EFTYPE] |
f52ca292 | 328 | A file is incorrectly formatted. |
189ff9f0 | 329 | .TP |
bcd70bc9 KB |
330 | [EINVAL] |
331 | A parameter has been specified (hash function, pad byte etc.) that is | |
332 | incompatible with the current file specification or there is a mismatch | |
333 | between the version number of file and the software. | |
334 | .PP | |
335 | The | |
bcd70bc9 | 336 | .I close |
8e982eee KB |
337 | routines may fail and set |
338 | .I errno | |
339 | for any of the errors specified for the library routines | |
bcd70bc9 | 340 | .IR close (2), |
8e982eee KB |
341 | .IR read (2), |
342 | .IR write (2), | |
bcd70bc9 KB |
343 | .IR free (3), |
344 | or | |
345 | .IR fsync (2). | |
346 | .PP | |
347 | The | |
16d71a3a | 348 | .IR del , |
8e982eee KB |
349 | .IR get , |
350 | .I put | |
351 | and | |
352 | .I seq | |
353 | routines may fail and set | |
354 | .I errno | |
355 | for any of the errors specified for the library routines | |
356 | .IR read (2), | |
357 | .IR write (2), | |
358 | .IR free (3) | |
359 | or | |
360 | .IR malloc (3). | |
361 | .PP | |
362 | The | |
bcd70bc9 | 363 | .I sync |
8e982eee KB |
364 | routines may fail and set |
365 | .I errno | |
366 | for any of the errors specified for the library routine | |
bcd70bc9 | 367 | .IR fsync (2). |
8e982eee | 368 | .SH "SEE ALSO" |
f52ca292 KB |
369 | .IR btree (3), |
370 | .IR hash (3), | |
371 | .IR mpool (3), | |
372 | .IR recno (3) | |
932a5d4e KB |
373 | .SH BUGS |
374 | The typedef DBT is a mnemonic for ``data base thang'', and was used | |
5cbd5d23 | 375 | because noone could think of a reasonable name that wasn't already used. |
ad422b65 | 376 | .PP |
8e982eee KB |
377 | None of the access methods provide any form of concurrent access, |
378 | locking, or transactions. |