.\" David Leonard, 1998. Placed in the public domain.
.\" $OpenBSD: ndbm.3,v 1.16 2007/05/31 19:19:28 jmc Exp $
.Dd $Mdocdate: May 31 2007 $
.Dt NDBM 3
.Os
.Sh NAME
.Nm dbm_clearerr ,
.Nm dbm_close ,
.Nm dbm_delete ,
.Nm dbm_dirfno ,
.Nm dbm_error ,
.Nm dbm_fetch ,
.Nm dbm_firstkey ,
.Nm dbm_nextkey ,
.Nm dbm_open ,
.Nm dbm_pagfno ,
.Nm dbm_rdonly ,
.Nm dbm_store
.Nd database access methods
.Sh SYNOPSIS
.Fd #include <ndbm.h>
.Ft int
.Fn dbm_clearerr "DBM *db"
.Ft void
.Fn dbm_close "DBM *db"
.Ft int
.Fn dbm_delete "DBM *db" "datum key"
.Ft int
.Fn dbm_dirfno "DBM *db"
.Ft int
.Fn dbm_error "DBM *db"
.Ft datum
.Fn dbm_fetch "DBM *db" "datum key"
.Ft datum
.Fn dbm_firstkey "DBM *db"
.Ft datum
.Fn dbm_nextkey "DBM *db"
.Ft "DBM *"
.Fn dbm_open "const char *file" "int flags" "mode_t mode"
.Ft int
.Fn dbm_pagfno "DBM *db"
.Ft int
.Fn dbm_rdonly "DBM *db"
.Ft int
.Fn dbm_store "DBM *db" "datum key" "datum content" "int store_mode"
.Sh DESCRIPTION
These functions provide a ndbm-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 dbm_open
function is used to open a database in the file named by
.Fa file ,
suffixed with
.Dv DBM_SUFFIX
.Pq Sq Pa .db .
If necessary, the file is created with mode
.Ar mode .
Access to this file depends on the
.Fa flags
parameter (see
.Xr open 2 ) .
Read-only access may be indicated by specifying
.Dv DBM_RDONLY .
The
.Fn dbm_rdonly
function may be used to determine if a database is opened for read-only
access.
.Pp
Once the database is open,
.Fn dbm_fetch
is used to retrieve the data content associated with the key
.Fa key .
Similarly,
.Fn dbm_store
is used to store the
.Fa content
data with the key
.Fa key .
When storing, the
.Fa store_mode
parameter must be one of:
.Bl -tag -width DBM_REPLACE -offset indent
.It Dv DBM_INSERT
Only insert new keys into the database.
Existing key/content pairs are untouched.
.It Dv DBM_REPLACE
Replace any existing entry with the same key.
Any previously stored records with the same key are lost.
.El
.Pp
The
.Fn dbm_delete
function removes the key
.Fa key
and its associated content from the database.
.Pp
The functions
.Fn dbm_firstkey
and
.Fn dbm_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 dbm_firstkey
function returns the first record of the database, and thereafter
.Fn dbm_nextkey
returns the following records.
The following code traverses the entire database:
.Bd -literal -offset indent
for (key = dbm_firstkey(db); key.dptr != NULL;
    key = dbm_nextkey(db))
.Ed
.Pp
The behaviour of
.Fn dbm_nextkey
is undefined if the database is modified after a call to
.Fn dbm_firstkey .
.Pp
The
.Fn dbm_error
function returns the last error condition of the database,
or 0 if no error had occurred or had been cleared.
The
.Fn dbm_clearerr
function clears the error condition of the database.
.Pp
The
.Fn dbm_dirfno
function is used to find the file descriptor associated with the
directory file of an open database.
Since a directory bitmap file is not used in this implementation,
this function returns the file descriptor of the database file opened with
.Fn dbm_open .
.Pp
The
.Fn dbm_pagfno
function is used to find the file descriptor associated with the
page file of an open database.
Since a page file is not used in this implementation, this function
is implemented as a macro that always returns the (undefined) value
.Dv DBM_PAGFNO_NOT_AVAILABLE .
.Pp
The database is closed with the
.Fn dbm_close
function.
Thereafter, the
.Fa db
handle is invalid.
.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
Routines that return a
.Ft datum
indicate errors by setting the
.Va dptr
field to
.Dv NULL .
.Pp
The
.Fn dbm_open
function returns
.Dv NULL
on error, and sets
.Va errno
appropriately.
On success, it returns a handle to the database that should be
used as the
.Fa db
argument in the other functions.
.Pp
The
.Fn dbm_store
function returns 1 when it is called with a
.Fa flags
value of
.Dv DBM_INSERT
and a record with the specified key already exists.
.Sh ERRORS
If an error occurs, the error can be retrieved with
.Fn dbm_error
and corresponds to those errors described in
.Xr db 3 .
.Sh SEE ALSO
.Xr open 2 ,
.Xr db 3 ,
.Xr dbm 3 ,
.Xr hash 3