Return to dbm.3 CVS log

Up to [Research Unix] / researchv10dc / man / adm / man3

Annotation of researchv10dc/man/adm/man3/dbm.3, revision 1.1.1.1

1.1       root        1: .TH DBM 3X
                      2: .CT 2 data_man
                      3: .SH NAME
                      4: dbminit, fetch, store, delete, firstkey, nextkey \(mi database subroutines
                      5: .SH SYNOPSIS
                      6: .nf
                      7: .B dbminit(file)
                      8: .B char *file;
                      9: .PP
                     10: .B datum fetch(key)
                     11: .B datum key;
                     12: .PP
                     13: .B store(key, value)
                     14: .B datum key, value;
                     15: .PP
                     16: .B delete(key)
                     17: .B datum key;
                     18: .PP
                     19: .B datum firstkey()
                     20: .PP
                     21: .B datum nextkey(key)
                     22: .B datum key;
                     23: .SH DESCRIPTION
                     24: These functions maintain
                     25: key/value pairs (each pair is a
                     26: .IR datum )
                     27: in a data base.
                     28: The functions will handle very large databases
                     29: in one or two file system accesses per key.
                     30: The functions are loaded
                     31: with
                     32: .IR ld (1)
                     33: option
                     34: .BR -ldbm .
                     35: A datum is defined as
                     36: .IP
                     37: .EX
                     38: .ta \w'typedef 'u +\w'struct 'u
                     39: typedef        struct  {
                     40:        char    *dptr;
                     41:        int     dsize;
                     42: } datum;
                     43: .EE
                     44: .PP
                     45: A
                     46: .B datum
                     47: object specifies a string of
                     48: .B dsize
                     49: bytes pointed to by
                     50: .BR dptr .
                     51: Arbitrary binary data, as well as normal
                     52: ASCII strings, are allowed.
                     53: The data base is stored in two files.
                     54: One file is a directory containing a bit map
                     55: and has
                     56: .L .dir
                     57: as its suffix.
                     58: The second file contains all data and
                     59: has
                     60: .L .pag
                     61: as its suffix.
                     62: .PP
                     63: Before a database can be accessed,
                     64: it must be opened by
                     65: .I dbminit.
                     66: At the time of this call,
                     67: the files
                     68: .IB file .dir
                     69: and
                     70: .IB file .pag
                     71: must exist.
                     72: (An empty database has empty
                     73: .L .dir
                     74: and
                     75: .L .pag
                     76: files.)
                     77: .PP
                     78: The value associated with a key is
                     79: retrieved by
                     80: .I fetch
                     81: and assigned by
                     82: .IR store .
                     83: A key and its associated value
                     84: are deleted by
                     85: .IR delete .
                     86: A linear pass through all keys in a database
                     87: may be made,
                     88: in random order,
                     89: by use of
                     90: .I firstkey
                     91: and
                     92: .IR nextkey .
                     93: .I Firstkey
                     94: will return the first key
                     95: in the database.
                     96: With any key
                     97: .I nextkey
                     98: will return the next key in the database.
                     99: This code will traverse the data base:
                    100: .IP
                    101: .L
                    102: for(key = firstkey(); key.dptr != NULL; key = nextkey(key))
                    103: .SH SEE ALSO
                    104: .IR cbt (3)
                    105: .SH DIAGNOSTICS
                    106: All functions that return integers
                    107: indicate errors with negative values.
                    108: A zero return indicates success.
                    109: Routines that return a
                    110: .B datum
                    111: indicate errors with zero
                    112: .BR dptr .
                    113: .SH BUGS
                    114: The
                    115: .L .pag
                    116: file contains holes;
                    117: its apparent size is about
                    118: four times its actual content.
                    119: These files cannot be copied
                    120: by normal means
                    121: .RI ( cat (1),
                    122: .IR tar (1),
                    123: .IR cpio (1),
                    124: .IR ar (1))
                    125: without filling in the holes.
                    126: .br
                    127: Pointers returned
                    128: by these subroutines
                    129: refer to static data
                    130: that is changed by subsequent calls.
                    131: .br
                    132: The sum of the sizes of
                    133: a
                    134: key/value pair must not exceed
                    135: a fixed internal block size.
                    136: Moreover all key/value pairs that hash
                    137: together must fit on a single block.
                    138: .I Store
                    139: will return an error in the event that
                    140: a disk block fills with inseparable data.
                    141: .br
                    142: .I Delete
                    143: does not physically reclaim file space,
                    144: although it does make it available for reuse.

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