1 files changed, 145 insertions, 0 deletions
diff --git a/lib/libc/db/man/dbm.3 b/lib/libc/db/man/dbm.3
new file mode 100644
index 00000000000..799170cb12e
--- /dev/null
+++ b/lib/libc/db/man/dbm.3
@@ -0,0 +1,145 @@
+.\" $OpenBSD: dbm.3,v 1.1 1999/02/15 05:11:24 millert 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 Feb 14, 1999
+.Os OpenBSD
+.Dt DBM 3
+.Sh NAME
+.Nm dbm ,
+.Nm dbminit ,
+.Nm fetch ,
+.Nm store ,
+.Nm delete ,
+.Nm firstkey ,
+.Nm nextkey ,
+.Nm dbmclose
+.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 in the file named by
+.Fa file ,
+suffixed with
+.Dv DBM_SUFFIX
+.Pq Sq Pa .db .
+The file is created if it does not already exist.
+.Pp
+Once the database is open,
+.Fn fetch
+is used to retrieve the data content associated with the key
+.Fa key .
+Similarly,
+.Fn store
+is used to store the
+.Fa content
+data with the key
+.Fa key .
+.Pp
+The
+.Fn delete
+function removes the key
+.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 set to
+.Dv NULL .
+.Sh SEE ALSO
+.Xr db 3 ,
+.Xr ndbm 3 ,
+.Xr hash 3