Return to dbm.3 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libdbm

Annotation of 43BSDReno/lib/libdbm/dbm.3, revision 1.1.1.1

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