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