These functions create, access and modify a database. They maintain key/content pairs in a database. The functions will handle large databases (up to a billion blocks) and will access a keyed item in one or two file system accesses. This package
replaces the earlier dbm(3UCB) library, which managed only a single database.
keys and contents are described by the datum typedef. A datum consists of at least two members, dptr and dsize. The dptr member points to an object
that is dsize bytes in length. Arbitrary binary data, as well as ASCII character strings, may be stored in the object pointed to by dptr.
The database is stored in two files. One file is a directory containing a bit map of keys and has .dir as its suffix. The second file contains all data and has .pag as its suffix.
The dbm_open() function opens a database. The file argument to the function is the pathname of the database. The function opens two files named file.dir and file.pag. The open_flags argument has the same meaning as the flags argument of open(2) except that a database opened for write-only access
opens the files for read and write access. The file_mode argument has the same meaning as the third argument of open(2).
The dbm_close() function closes a database. The argument db must be a pointer to a dbm structure that has been returned from a call to dbm_open().
The dbm_fetch() function reads a record from a database. The argument db is a pointer to a database structure that has been returned from a call to dbm_open(). The argument key is a datum
that has been initialized by the application program to the value of the key that matches the key of the record the program is fetching.
The dbm_store() function writes a record to a database. The argument db is a pointer to a database structure that has been returned from a call to dbm_open(). The argument key is a datum
that has been initialized by the application program to the value of the key that identifies (for subsequent reading, writing or deleting) the record the program is writing. The argument content is a datum that has been initialized by the application program
to the value of the record the program is writing. The argument store_mode controls whether dbm_store() replaces any pre-existing record that has the same key that is specified by the key argument. The application program must
set store_mode to either DBM_INSERT or DBM_REPLACE. If the database contains a record that matches the key argument and store_mode is DBM_REPLACE,
the existing record is replaced with the new record. If the database contains a record that matches the key argument and store_mode is DBM_INSERT, the existing record is not replaced with the new record. If the database does not
contain a record that matches the key argument and store_mode is either DBM_INSERT or DBM_REPLACE, the new record is inserted in the database.
The dbm_delete() function deletes a record and its key from the database. The argument db is a pointer to a database structure that has been returned from a call to dbm_open(). The argument key is a datum that has been initialized by the application program to the value of the key that identifies the record the program is deleting.
The dbm_firstkey() function returns the first key in the database. The argument db is a pointer to a database structure that has been returned from a call to dbm_open().
The dbm_nextkey() function returns the next key in the database. The argument db is a pointer to a database structure that has been returned from a call to dbm_open(). The dbm_firstkey() function must be called
before calling dbm_nextkey(). Subsequent calls to dbm_nextkey() return the next key until all of the keys in the database have been returned.
The dbm_error() function returns the error condition of the database. The argument db is a pointer to a database structure that has been returned from a call to dbm_open().
The dbm_clearerr() function clears the error condition of the database. The argument db is a pointer to a database structure that has been returned from a call to dbm_open().
These database functions support key/content pairs of at least 1024 bytes.
|