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     ! 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.