Relic is the API which is compatible with NDBM. So, Relic wraps functions of Depot as API of NDBM. It
is easy to port an application from NDBM to QDBM. In most cases, you should only replace the includings
of `ndbm.h' with `relic.h' and replace the linking option `-lndbm' with `-lqdbm'.
The original NDBM treats a database as a pair of files. One, `a directory file', has a name with suffix
`.dir' and stores a bit map of keys. The other, `a data file', has a name with suffix `.pag' and stores
entities of each records. Relic creates the directory file as a mere dummy file and creates the data
file as a database. Relic has no restriction about the size of each record. Relic cannot handle
database files made by the original NDBM.
In order to use Relic, you should include `relic.h', `stdlib.h', `sys/types.h', `sys/stat.h' and
`fcntl.h' in the source files. Usually, the following description will be near the beginning of a source
file.
#include<relic.h>#include<stdlib.h>#include<sys/types.h>#include<sys/stat.h>#include<fcntl.h>
A pointer to `DBM' is used as a database handle. A database handle is opened with the function
`dbm_open' and closed with `dbm_close'. You should not refer directly to any member of a handle.
Structures of `datum' type is used in order to give and receive data of keys and values with functions of
Relic.
typedefstruct{void*dptr;size_tdsize;}datum;
`dptr' specifies the pointer to the region of a key or a value. `dsize' specifies the size of the
region.
The function `dbm_open' is used in order to get a database handle.
DBM*dbm_open(char*name,intflags,intmode);
`name' specifies the name of a database. The file names are concatenated with suffixes. `flags'
is the same as one of `open' call, although `O_WRONLY' is treated as `O_RDWR' and additional flags
except for `O_CREAT' and `O_TRUNC' have no effect. `mode' specifies the mode of the database file
as one of `open' call does. The return value is the database handle or `NULL' if it is not
successful.
The function `dbm_close' is used in order to close a database handle.
voiddbm_close(DBM*db);
`db' specifies a database handle. Because the region of the closed handle is released, it becomes
impossible to use the handle.
The function `dbm_store' is used in order to store a record.
intdbm_store(DBM*db,datumkey,datumcontent,intflags);
`db' specifies a database handle. `key' specifies a structure of a key. `content' specifies a
structure of a value. `flags' specifies behavior when the key overlaps, by the following values:
`DBM_REPLACE', which means the specified value overwrites the existing one, `DBM_INSERT', which
means the existing value is kept. The return value is 0 if it is successful, 1 if it gives up
because of overlaps of the key, -1 if other error occurs.
The function `dbm_delete' is used in order to delete a record.
intdbm_delete(DBM*db,datumkey);
`db' specifies a database handle. `key' specifies a structure of a key. The return value is 0 if
it is successful, -1 if some errors occur.
The function `dbm_fetch' is used in order to retrieve a record.
datumdbm_fetch(DBM*db,datumkey);
`db' specifies a database handle. `key' specifies a structure of a key. The return value is a
structure of the result. If a record corresponds, the member `dptr' of the structure is the
pointer to the region of the value. If no record corresponds or some errors occur, `dptr' is
`NULL'. `dptr' points to the region related with the handle. The region is available until the
next time of calling this function with the same handle.
The function `dbm_firstkey' is used in order to get the first key of a database.
datumdbm_firstkey(DBM*db);
`db' specifies a database handle. The return value is a structure of the result. If a record
corresponds, the member `dptr' of the structure is the pointer to the region of the first key. If
no record corresponds or some errors occur, `dptr' is `NULL'. `dptr' points to the region related
with the handle. The region is available until the next time of calling this function or the
function `dbm_nextkey' with the same handle.
The function `dbm_nextkey' is used in order to get the next key of a database.
datumdbm_nextkey(DBM*db);
`db' specifies a database handle. The return value is a structure of the result. If a record
corresponds, the member `dptr' of the structure is the pointer to the region of the next key. If
no record corresponds or some errors occur, `dptr' is `NULL'. `dptr' points to the region related
with the handle. The region is available until the next time of calling this function or the
function `dbm_firstkey' with the same handle.
The function `dbm_error' is used in order to check whether a database has a fatal error or not.
intdbm_error(DBM*db);
`db' specifies a database handle. The return value is true if the database has a fatal error,
false if not.
The function `dbm_clearerr' has no effect.
intdbm_clearerr(DBM*db);
`db' specifies a database handle. The return value is 0. The function is only for compatibility.
The function `dbm_rdonly' is used in order to check whether a handle is read-only or not.
intdbm_rdonly(DBM*db);
`db' specifies a database handle. The return value is true if the handle is read-only, or false
if not read-only.
The function `dbm_dirfno' is used in order to get the file descriptor of a directory file.
intdbm_dirfno(DBM*db);
`db' specifies a database handle. The return value is the file descriptor of the directory file.
The function `dbm_pagfno' is used in order to get the file descriptor of a data file.
intdbm_pagfno(DBM*db);
`db' specifies a database handle. The return value is the file descriptor of the data file.
Functions of Relic are thread-safe as long as a handle is not accessed by threads at the same time, on
the assumption that `errno', `malloc', and so on are thread-safe.
Install Now
PNG Icons
