.\"	$NetBSD: dbm_clearerr.3,v 1.5 2010/05/05 06:55:57 jruoho Exp $
.\"
.\" Copyright (c) 2004 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Klaus Klein.
.\"
.\" 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``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 FOUNDATION OR CONTRIBUTORS
.\" 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 May 5, 2010
.Dt DBM_CLEARERR 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_store ,
.Nm ndbm
.Nd database functions
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In 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 open_flags" "mode_t file_mode"
.Ft int
.Fn dbm_store "DBM *db" "datum key" "datum content" "int store_mode"
.Sh DESCRIPTION
The
.Nm ndbm
facility provides access to hash database files.
.Pp
Two data types are fundamental to the
.Nm ndbm
facility.
.Fa DBM
serves as a handle to a database.
It is an opaque type.
.Pp
The other data type is
.Fa datum ,
which is a structure type which includes the following members:
.Bd -literal -offset indent
void *  dptr
size_t  dsize
.Ed
.Pp
A
.Fa datum
is thus given by
.Fa dptr
pointing at an object of
.Fa dsize
bytes in length.
.Pp
The
.Fn dbm_open
function opens a database.
The
.Fa file
argument is the pathname which the actual database file pathname
is based on.
This implementation uses a single file with the suffix
.Pa .db
appended to
.Fa file .
The
.Fa open_flags
argument has the same meaning as the
.Fa flags
argument to
.Xr open 2
except that when opening a database for write-only access the file
is opened for read/write access, and the
.Dv O_APPEND
flag must not be specified.
The
.Fa file_mode
argument has the same meaning as the
.Fa mode
argument to
.Xr open 2 .
.Pp
For the following functions, the
.Fa db
argument is a handle previously returned by a call to
.Fn dbm_open .
.Pp
The
.Fn dbm_close
function closes a database.
.Pp
The
.Fn dbm_fetch
function retrieves a record from the database.
The
.Fa key
argument is a
.Fa datum
that identifies the record to be fetched.
.Pp
The
.Fn dbm_store
function stores a record into the database.
The
.Fa key
argument is a
.Fa datum
that identifies the record to be stored.
The
.Fa content
argument is a
.Fa datum
that specifies the value of the record to be stored.
The
.Fa store_mode
argument specifies the behavior of
.Fn dbm_store
if a record matching
.Fa key
is already present in the database,
.Fa db .
.Fa store_mode
must be one of the following:
.Bl -tag -width DBM_REPLACEXX -offset indent
.It Dv DBM_INSERT
If a record matching
.Fa key
is already present, it is left unchanged.
.It Dv DBM_REPLACE
If a record matching
.Fa key
is already present, its value is replaced by
.Fa content .
.El
.Pp
If no record matching
.Fa key
is present, a new record is inserted regardless of
.Fa store_mode .
.Pp
The
.Fn dbm_delete
function deletes a record from the database.
The
.Fa key
argument is a
.Fa datum
that identifies the record to be deleted.
.Pp
The
.Fn dbm_firstkey
function returns the first key in the database.
.Pp
The
.Fn dbm_nextkey
function returns the next key in the database.
In order to be meaningful, it must be preceded by a call to
.Fn dbm_firstkey .
.Pp
The
.Fn dbm_error
function returns the error indicator of the database.
.Pp
The
.Fn dbm_clearerr
function clears the error indicator of the database.
.Pp
The
.Fn dbm_dirfno
function returns the file descriptor of the underlying database file.
.Sh IMPLEMENTATION NOTES
The
.Nm ndbm
facility is implemented on top of the
.Xr hash 3
access method of the
.Xr db 3
database facility.
.Sh RETURN VALUES
The
.Fn dbm_open
function returns a pointer to a
.Fa DBM
when successful; otherwise a null pointer is returned.
.Pp
The
.Fn dbm_close
function returns no value.
.Pp
The
.Fn dbm_fetch
function returns a content
.Fa datum ;
if no record matching
.Fa key
was found or if an error occured, its
.Fa dptr
member is a null pointer.
.Pp
The
.Fn dbm_store
function returns 0 when then record was successfully inserted;
it returns 1 when called with
.Fa store_mode
being
.Dv DBM_INSERT
and a record matching
.Fa key
is already present;
otherwise a negative value is returned.
.Pp
The
.Fn dbm_delete
function returns 0 when the record was successfully deleted;
otherwise a negative value is returned.
.Pp
The
.Fn dbm_firstkey
and
.Fn dbm_nextkey
functions return a key
.Fa datum .
When the end of the database is reached or if an error occured, its
.Fa dptr
member is a null pointer.
.Pp
The
.Fn dbm_error
function returns 0 if the error indicator is clear;
if the error indicator is set a non-zero value is returned.
.Pp
The
.Fn dbm_clearerr
function always returns 0.
.Pp
The
.Fn dbm_dirfno
function returns the file descriptor of the underlying database file.
.Sh ERRORS
No errors are defined.
.Sh SEE ALSO
.Xr open 2 ,
.Xr db 3 ,
.Xr hash 3
.Sh STANDARDS
The
.Fn dbm_clearerr ,
.Fn dbm_close ,
.Fn dbm_delete ,
.Fn dbm_error ,
.Fn dbm_fetch ,
.Fn dbm_firstkey ,
.Fn dbm_nextkey ,
.Fn dbm_open ,
and
.Fn dbm_store
functions conform to
.St -xpg4.2
and
.St -susv2 .
The
.Fn dbm_dirfno
function is an extension.