RELIC(3) Quick Database Manager RELIC(3)
NAME
Relic - the NDBM-compatible API of QDBM
SYNOPSIS
#include <relic.h>
#include <stdlib.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
typedef struct { void *dptr; size_t dsize; } datum;
DBM *dbm_open(char *name, int flags, int mode);
void dbm_close(DBM *db);
int dbm_store(DBM *db, datum key, datum content, int flags);
int dbm_delete(DBM *db, datum key);
datum dbm_fetch(DBM *db, datum key);
datum dbm_firstkey(DBM *db);
datum dbm_nextkey(DBM *db);
int dbm_error(DBM *db);
int dbm_clearerr(DBM *db);
int dbm_rdonly(DBM *db);
int dbm_dirfno(DBM *db);
int dbm_pagfno(DBM *db);
DESCRIPTION
Relic is the API which is compatible with NDBM. So, Relic wraps func-
tions 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 direc-
tory file(1,n)', has a name with suffix `.dir' and stores a bit map of keys.
The other, `a data file(1,n)', has a name with suffix `.pag' and stores
entities of each records. Relic creates the directory file(1,n) as a mere
dummy file(1,n) and creates the data file(1,n) as a database. Relic has no
restriction about the size of each record. Relic cannot handle data-
base 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(1,8) the source files. Usu-
ally, 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(1,8) order to give and receive data of
keys and values with functions of Relic.
typedef struct { void *dptr; size_t dsize; } 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(1,8) order to get a database handle.
DBM *dbm_open(char *name, int flags, int mode);
`name' specifies the name of a database. The file(1,n) names are
concatenated with suffixes. `flags' is the same as one of
`open(2,3,n)' 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(1,n) as one
of `open(2,3,n)' call does. The return value is the database handle or
`NULL' if(3,n) it is not successful.
The function `dbm_close' is used in(1,8) order to close(2,7,n) a database handle.
void dbm_close(DBM *db);
`db' specifies a database handle. Because the region of the
closed handle is released, it becomes impossible to use the han-
dle.
The function `dbm_store' is used in(1,8) order to store a record.
int dbm_store(DBM *db, datum key, datum content, int flags);
`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 val-
ues: `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(3,n) it is successful, 1 if(3,n) it
gives up because of overlaps of the key, -1 if(3,n) other error(8,n)
occurs.
The function `dbm_delete' is used in(1,8) order to delete a record.
int dbm_delete(DBM *db, datum key);
`db' specifies a database handle. `key' specifies a structure
of a key. The return value is 0 if(3,n) it is successful, -1 if(3,n) some
errors occur.
The function `dbm_fetch' is used in(1,8) order to retrieve a record.
datum dbm_fetch(DBM *db, datum key);
`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(1,2,n) of calling this function with the same handle.
The function `dbm_firstkey' is used in(1,8) order to get the first key of a
database.
datum dbm_firstkey(DBM *db);
`db' specifies a database handle. The return value is a struc-
ture 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(1,2,n) of calling this function or the
function `dbm_nextkey' with the same handle.
The function `dbm_nextkey' is used in(1,8) order to get the next key of a
database.
datum dbm_nextkey(DBM *db);
`db' specifies a database handle. The return value is a struc-
ture 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(1,2,n) of calling this function or the
function `dbm_firstkey' with the same handle.
The function `dbm_error' is used in(1,8) order to check whether a database
has a fatal error(8,n) or not.
int dbm_error(DBM *db);
`db' specifies a database handle. The return value is true if(3,n)
the database has a fatal error(8,n), false if(3,n) not.
The function `dbm_clearerr' has no effect.
int dbm_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(1,8) order to check whether a handle is
read-only or not.
int dbm_rdonly(DBM *db);
`db' specifies a database handle. The return value is true if(3,n)
the handle is read-only, or false if(3,n) not read-only.
The function `dbm_dirfno' is used in(1,8) order to get the file(1,n) descriptor
of a directory file.
int dbm_dirfno(DBM *db);
`db' specifies a database handle. The return value is the file(1,n)
descriptor of the directory file.
The function `dbm_pagfno' is used in(1,8) order to get the file(1,n) descriptor
of a data file.
int dbm_pagfno(DBM *db);
`db' specifies a database handle. The return value is the file(1,n)
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(1,2,n), on the assumption that `errno', `malloc',
and so on are thread-safe.
SEE ALSO
qdbm(3), depot(3), curia(3), hovel(3), cabin(3), villa(3), odeum(3),
ndbm(3), gdbm(3)
Man Page 2004-04-22 RELIC(3)