Return to dbm.3 CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / man / man3

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