.\" $OpenBSD: dbm.3,v 1.11 2007/05/31 19:19:27 jmc Exp $
.\"
.\" Copyright (c) 1999 Todd C. Miller <Todd.Miller@courtesan.com>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: May 31 2007 $
.Dt DBM 3
.Os
.Sh NAME
.Nm dbminit ,
.Nm dbmclose ,
.Nm fetch ,
.Nm store ,
.Nm delete ,
.Nm firstkey ,
.Nm nextkey
.Nd database subroutines
.Sh SYNOPSIS
.Fd #include <dbm.h>
.Ft int
.Fn dbminit "const char *file"
.Ft int
.Fn dbmclose "void"
.Ft datum
.Fn fetch "datum key"
.Ft int
.Fn store "datum key" "datum content"
.Ft int
.Fn delete "datum key"
.Ft datum
.Fn firstkey "void"
.Ft datum
.Fn nextkey "datum key"
.Sh DESCRIPTION
These functions provide a dbm-compatible interface to the
database access methods described in
.Xr db 3 .
Each unique record in the database is a key/content pair,
the components of which may be any arbitrary binary data.
The key and the content data are described by the
.Ft datum
data structure:
.Bd -literal -offset indent
typedef struct {
	void *dptr;
	size_t dsize;
} datum;
.Ed
.Pp
The
.Fn dbminit
function is used to open a database.
Before the call to
.Fn dbminit ,
the files
.Pa file.pag
and
.Pa file.dir
must exist.
The user is responsible for creating the zero-length
.Pa \&.pag
and
.Pa \&.dir
files.
.Pp
Once the database is open,
.Fn fetch
is used to retrieve the data content associated with the specified
.Fa key .
Similarly,
.Fn store
is used to store the
.Fa content
data with the specified
.Fa key .
.Pp
The
.Fn delete
function removes the specified
.Fa key
and its associated content from the database.
.Pp
The functions
.Fn firstkey
and
.Fn nextkey
are used to iterate over all of the records in the database.
Each record will be reached exactly once, but in no particular order.
The
.Fn firstkey
function returns the first record of the database, and thereafter
.Fn nextkey
returns the following records.
The following code traverses the entire database:
.Bd -literal -offset indent
for (key = firstkey(); key.dptr != NULL; key = nextkey(key))
.Ed
.Pp
The behaviour of
.Fn nextkey
is undefined if the database is modified after a call to
.Fn firstkey .
.Pp
The database is closed with the
.Fn dbmclose
function (it must be closed before a new one can be opened).
.Ss Implementation notes
The underlying database is a
.Xr hash 3
database with a
bucket size of 4096,
a filling factor of 40,
default hashing function and cache size,
and uses the host's native byte order.
.Sh RETURN VALUES
Upon successful completion, all functions that return
.Ft int
return a value of 0, otherwise a negative value is returned.
.Pp
Functions that return a
.Ft datum
indicate errors by setting the
.Va dptr
field to
.Dv NULL .
.Sh SEE ALSO
.Xr db 3 ,
.Xr hash 3 ,
.Xr ndbm 3
.Sh BUGS
Because the
.Nm dbm
routines are implemented on top of
.Xr db 3 ,
only a single file,
.Pa file.pag ,
is used to actually store the database.
The references to
.Pa file.dir
are purely for backwards compatibility with historic implementations.