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

       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 order to get a database handle.

       DBM *dbm_open(char *name, int flags, int mode);
              `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.

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

       The function `dbm_store' is used in 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  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.

       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
              it is successful, -1 if some errors occur.

       The function `dbm_fetch' is used in 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 of calling this function with the same handle.

       The function `dbm_firstkey' is used in order to get the first key of a database.

       datum dbm_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.

       datum dbm_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.

       int dbm_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.

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

       int dbm_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.

       int dbm_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.

SEE ALSO

       qdbm(3), depot(3), curia(3), hovel(3), cabin(3), villa(3), odeum(3), ndbm(3), gdbm(3)