Return to dbm.3x CVS log

Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / man / man3

Annotation of cci/usr/src/man/man3/dbm.3x, revision 1.1.1.2

1.1       root        1: .TH DBM 3X  "19 January 1983"
                      2: .UC 4
                      3: .SH NAME
                      4: dbminit, fetch, store, delete, firstkey, nextkey \- data base subroutines
                      5: .SH SYNOPSIS
                      6: .nf
                      7: .PP
                      8: .B typedef struct {
                      9: .B "   char *dptr;"
                     10: .B "   int dsize;"
                     11: .B } datum;
                     12: .PP
                     13: .B dbminit(file)
                     14: .B char *file;
                     15: .PP
                     16: .B datum fetch(key)
                     17: .B datum key;
                     18: .PP
                     19: .B store(key, content)
                     20: .B datum key, content;
                     21: .PP
                     22: .B delete(key)
                     23: .B datum key;
                     24: .PP
                     25: .B datum firstkey()
                     26: .PP
                     27: .B datum nextkey(key)
                     28: .B datum key;
                     29: .SH DESCRIPTION
                     30: These functions maintain key/content pairs in a data base.
1.1.1.2 ! root       31: The functions handle very large (a billion blocks)
        !            32: databases and access a keyed item in one or two file system accesses.
1.1       root       33: The functions are obtained with the loader option
                     34: .BR \-ldbm .
                     35: .PP
                     36: .IR Key s
                     37: and
                     38: .IR content s
                     39: are described by the
                     40: .I datum
                     41: typedef.  A
                     42: .I datum
                     43: specifies a string of
                     44: .I dsize
                     45: bytes pointed to by
                     46: .I dptr.
                     47: Arbitrary binary data, as well as normal ASCII strings, are allowed.
                     48: The data base is stored in two files.
                     49: One file is a directory containing a bit map and has `.dir' as its suffix.
                     50: The second file contains all data and has `.pag' as its suffix.
                     51: .PP
                     52: Before a database can be accessed, it must be opened by
                     53: .I dbminit.
                     54: At the time of this call, the files
                     55: .IB file .dir
                     56: and
                     57: .IB file .pag
                     58: must exist.
                     59: (An empty database is created by creating zero-length
                     60: `.dir' and `.pag' files.)
                     61: .PP
                     62: Once open, the data stored under a key is accessed by
                     63: .I fetch
                     64: and data is placed under a key by
                     65: .IR store .
                     66: A key (and its associated contents) is deleted by
                     67: .IR delete .
                     68: A linear pass through all keys in a database may be made,
                     69: in an (apparently) random order, by use of
                     70: .I firstkey
                     71: and
                     72: .IR nextkey .
                     73: .I Firstkey
1.1.1.2 ! root       74: returns the first key in the database.  With any key
1.1       root       75: .I nextkey
1.1.1.2 ! root       76: returns the next key in the database.
        !            77: This code traverses the data base:
1.1       root       78: .IP
                     79: .B for
                     80: (key = firstkey(); key.dptr != NULL; key = nextkey(key))
                     81: .SH DIAGNOSTICS
                     82: All functions that return an
                     83: .I int
                     84: indicate errors with negative values.  A zero return indicates ok.
                     85: Routines that return a
                     86: .I datum
                     87: indicate errors with a null (0)
                     88: .I dptr.
                     89: .SH BUGS
1.1.1.2 ! root       90: The `.pag' file contains holes so that its apparent size is about
1.1       root       91: four times its actual content.  Older UNIX systems may create real
                     92: file blocks for these holes when touched.  These files cannot be copied
                     93: by normal means (cp, cat, tp, tar, ar) without filling in the holes.
                     94: .PP
                     95: .I Dptr
                     96: pointers returned by these subroutines point into static storage
                     97: that is changed by subsequent calls.
                     98: .PP
                     99: The sum of the sizes of a key/content pair must not exceed
                    100: the internal block size (currently 1024 bytes).
                    101: Moreover all key/content pairs that hash together must fit on a single block.
                    102: .I Store
1.1.1.2 ! root      103: returns an error in the event that a disk block fills with inseparable data.
1.1       root      104: .PP
                    105: .I Delete
                    106: does not physically reclaim file space,
                    107: although it does make it available for reuse.
                    108: .PP
                    109: The order of keys presented by
                    110: .I firstkey
                    111: and
                    112: .I nextkey
                    113: depends on a hashing function, not on anything interesting.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.