.\" $OpenBSD: dbm.3,v 1.6 2000/04/18 02:31:35 aaron Exp $
.\"
.\" Copyright (c) 1999 Todd C. Miller <Todd.Miller@courtesan.com>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd February 14, 1999
.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 {
	char *dptr;
	int 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
  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 (you must close a database before opening a new one).
.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 the
.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.