Bell 32V development

Work on file usr/man/man3/dbm.3x

Co-Authored-By: John Reiser <jfr@research.uucp>
Synthesized-from: 32v

diff --git a/usr/man/man3/dbm.3x b/usr/man/man3/dbm.3x
new file mode 100644 (file)
index 0000000..02afe6d
--- /dev/null
+++ b/usr/man/man3/dbm.3x
@@ -0,0 +1,142 @@
+.TH DBM 3X 
+.SH NAME
+dbminit, fetch, store, delete, firstkey, nextkey \- data base subroutines
+.SH SYNOPSIS
+.nf
+.PP
+.B "typedef struct { char *dptr; int dsize; } datum;"
+.PP
+.B dbminit(file)
+.B char *file;
+.PP
+.B datum fetch(key)
+.B datum key;
+.PP
+.B store(key, content)
+.B datum key, content;
+.PP
+.B delete(key)
+.B datum key;
+.PP
+.B datum firstkey();
+.PP
+.B datum nextkey(key);
+.B datum key;
+.SH DESCRIPTION
+These functions maintain
+key/content pairs in a data base.
+The functions will handle very large
+(a billion blocks)
+databases and will access a keyed item
+in one or two filesystem accesses.
+The functions are obtained with the loader option
+.BR \-ldbm .
+.PP
+.IR Key s
+and
+.IR content s
+are
+described by the
+.I datum
+typedef.
+A
+.I datum
+specifies a string of
+.I dsize
+bytes pointed to by
+.I dptr.
+Arbitrary binary data, as well as normal
+ASCII strings, are allowed.
+The data base is stored in two files.
+One file is a directory containing a bit map
+and has `.dir' as its suffix.
+The second file contains all data and
+has `.pag' as its suffix.
+.PP
+Before a database can be accessed,
+it must be opened by
+.I dbminit.
+At the time of this call,
+the files
+.IB file .dir
+and
+.IB file .pag
+must exist.
+(An empty database is created by
+creating zero-length
+`.dir' and `.pag' files.)
+.PP
+Once open,
+the data stored under a key is
+accessed by
+.I fetch
+and data is placed under a key
+by
+.IR store .
+A key (and its associated contents)
+is deleted by
+.IR delete .
+A linear pass through all keys in a database
+may be made,
+in an (apparently) random order,
+by use of
+.I firstkey
+and
+.IR nextkey .
+.I Firstkey
+will return the first key
+in the database.
+With any key
+.I nextkey
+will return the next key in the database.
+This code will traverse the data base:
+.PP
+       for(key=firstkey(); key.dptr!=NULL; key=nextkey(key))
+.SH DIAGNOSTICS
+All functions that return an
+.I int
+indicate errors with negative values.
+A zero return indicates ok.
+Routines that return a
+.I datum
+indicate errors with a null (0)
+.I dptr.
+.SH BUGS
+The
+`.pag'
+file will contain holes so
+that its apparent size is about
+four times its actual content.
+Older UNIX systems may create real
+file blocks for these holes when touched.
+These files cannot be copied
+by normal means (cp, cat, tp, tar, ar)
+without filling in the holes.
+.PP
+.I Dptr
+pointers returned
+by these subroutines
+point into static storage
+that is changed by subsequent calls.
+.PP
+The sum of the sizes of
+a
+key/content pair must not exceed
+the internal block size
+(currently 512 bytes).
+Moreover all key/content pairs that hash
+together must fit on a single block.
+.I Store
+will return an error in the event that
+a disk block fills with inseparable data.
+.PP
+.I Delete
+does not physically reclaim file space,
+although it does make it available for reuse.
+.PP
+The order of keys presented by
+.I firstkey
+and
+.I nextkey
+depends on a hashing function, not on anything
+interesting.